1.2 搭工棚：环境搭建与 Composer 备料

1.2 搭工棚：环境搭建与 Composer 备料

本节摘要：开工前要备齐三样料：PHP 运行环境、Composer 依赖管理器、一个跑得起来的 Laravel 骨架。本节给出 Windows 与 macOS 的安装要点，讲清 Composer 依赖解析与 PSR-4 自动加载的原理，对比 Valet、Homestead、Docker 三种工棚方案的取舍，最后把新项目跑起来并用 artisan 完成第一次体检。

先把工具领齐，再谈施工

上一节认识了工地全貌，这一节轮到搭自己的工棚。环境问题是最劝退新手的一关：报错信息天书一样，搜出来的答案互相矛盾。本节的策略是把"要装什么、为什么装它、装完怎么验"三件事一次讲透，让你出问题时知道往哪查。

备料清单：装什么、为什么

• PHP 8.2 及以上：Laravel 11 的硬性底线。除了 PHP 本体，还要确认 fileinfo、openssl、pdo、mbstring、tokenizer、xml 这几个扩展处于启用状态——它们是框架核心组件的直接依赖。
• Composer：PHP 世界的依赖管家。Laravel 内核本身就是一组 Composer 组件，没有它，工地连材料都进不了场。
• Node.js 与 npm：前端资产编译要用（第六章会细讲 Vite），搭环境阶段先装上即可。
• 数据库：开发期用 SQLite 最省事（Laravel 11 默认配置就是它），想贴近生产就装 MySQL 或 PostgreSQL。

Composer 在工地上的角色

Composer 做两件事：按 composer.json 声明解析并下载依赖；按 PSR-4 约定生成自动加载器。理解第二件事，你就明白为什么 Laravel 项目里类文件放对目录就能被找到——vendor 里生成的 autoload 文件把命名空间前缀映射到了目录。

{
    "name": "mycompany/workorder",
    "require": {
        "php": "^8.2",
        "laravel/framework": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "app/",
            "Database\\Factories\\": "database/factories/"
        }
    }
}
​

# 常用备料命令速查
composer install                 # 按 lock 文件原样装依赖（新机器首次拉项目用它）
composer update                  # 重新解析并升级依赖（慎用，会动 lock 文件）
composer require laravel/horizon # 新增一个包并写入 json
composer dump-autoload           # 只重建自动加载映射（新增类文件找不到时跑它）
​

💡 关键直觉：install 认 lock 文件，update 认 json 文件。团队协作里，提交 lock 文件、少跑 update，能让所有人的依赖版本完全一致——工地上材料批次统一，才不会出现"我这没事啊"的经典扯皮。

三种工棚方案怎么选

我的建议很直接：个人练手用直装加 artisan serve 起步，团队项目用 Docker（Laravel 官方的 Sail 就是一套现成编排），Homestead 除非你在维护相关旧项目，否则不必再入坑。

动手：从零跑起第一个项目

# 1. 确认 PHP 版本与关键扩展（Windows 可用 php -m 看扩展列表）
php -v
php -m | grep -E "openssl|pdo|mbstring|tokenizer|xml|fileinfo"

# 2. 建项目：两种方式等价，任选其一
composer create-project laravel/laravel workorder
# 或安装官方全局安装器后：
laravel new workorder

# 3. 进入项目目录，生成应用密钥（Laravel 11 的 create-project 已自动执行）
cd workorder
php artisan key:generate

# 4. 起开发服务器
php artisan serve
# 输出类似：Server running on http://127.0.0.1:8000
​

浏览器访问后看到 Laravel 欢迎页，工棚就算搭好了。接着做一次全面体检：

php artisan about
​

这条命令会列出 PHP 版本、已加载扩展、缓存驱动、队列驱动、会话驱动等一整版环境报告。它也是日后排查"为什么队列没跑"这类问题的第一入口——先看报告里各驱动是什么，再谈为什么。

图 1-2：环境搭好后项目里的关键料位

常见坑与排查路数

⚠️ 新手最容易踩的坑：PHP 装了但命令行找不到、扩展没开、.env 没建（Laravel 11 已自带 .env，老教程让你手动复制的情况不适用了）、端口被占。逐条对号入座：

• php -v 报命令不存在：PHP 未加入系统 PATH，或装了多个版本互相打架。Windows 下查环境变量，macOS 下用 brew 管理。
• 报缺少扩展：编辑 php.ini，把对应扩展行前的分号去掉，重启终端再验。
• composer install 卡住或超时：网络问题，换国内镜像源后重试。
• 页面报 500 且日志为空：检查 storage 与 bootstrap/cache 目录是否可写，以及 .env 的 APP_KEY 是否存在。

本节要点回顾

• 备料三件套：PHP 8.2 加关键扩展、Composer、数据库，缺一开工就停工。
• Composer 双职责：装依赖 + 生成 PSR-4 自动加载，install 与 update 的区别要刻进肌肉记忆。
• 工棚选型：练手直装、团队 Docker、Homestead 不必再入坑。
• 体检入口：php artisan about 是排查环境与驱动问题的第一步。

工棚搭好了，下一章我们展开工地平面图：目录为什么这样分区、服务容器这台调度机器怎么运转、一个请求在内核里的完整旅程。