Composer create-project怎么用？Composer项目初始化【开发指南】

很多开发者第一次接触 composer create-project 时，容易把它当成一个高级版的 composer require。这个误解，往往是后续一系列错误的起点。

直接说结论：create-project 的核心任务不是“安装一个包”，而是“拉取一个完整、可运行的项目骨架”。根据经验，90% 的初始化失败，都源于三个看似简单的环节：用错了包名、漏掉了关键参数，或者忽略了 PHP 环境的隐形约束。

为什么 composer require lara vel/framework 跑不起来？

这个问题非常典型。你猜怎么着？lara vel/framework 本质上是一个类库，它只包含框架的核心代码，并不附带项目运行所必需的文件结构。这意味着，你拉下来的代码里，既没有 artisan 命令行工具，也没有 public/index.php 这个前端控制器，甚至连 .env.example 环境模板都找不到。

结果就是，当你兴冲冲地执行 php artisan serve 时，会收到一个冰冷的提示：Command “serve” is not defined。如果把 Web 服务器的根目录指向项目文件夹，访问域名只会返回 404 错误，因为服务器根本找不到入口文件。

问题的关键在于，一个包必须被明确声明为“项目”类型，才能用于 create-project。这需要在其 composer.json 文件中包含 “type”: “project” 的配置。

• 正确示例：lara vel/lara vel 是项目骨架，而 lara vel/framework 只是核心库。
• 常见合法模板：除了 Lara vel，像 symfony/skeleton、yiisoft/yii2-app-basic、roots/bedrock 等都是标准的项目模板。
• 操作建议：在 Packagist 上找到心仪的包时，先别急着复制命令。点开其 composer.json 文件，确认 type 字段的值确实是 project，这个习惯能避免很多无效操作。

create-project 命令必须带的四个参数组合

如果只是简单地运行 composer create-project lara vel/lara vel myapp，在国内网络环境下，大概率会卡在 Loading composer repositories 这一步，或者因为拉取了不稳定的开发分支，导致后续命令缺失。想要稳定、高效地完成初始化，下面这组参数组合几乎是标配：

• --prefer-dist：强制使用压缩包（zip）方式下载，避免因 Git 克隆失败或 SSH 密钥权限问题导致的安装中断。
• --no-scripts：跳过包安装后自动执行的脚本（例如 Lara vel 的 php artisan key:generate）。这在网络不稳定时尤为重要，可以防止脚本执行超时导致整个安装过程失败。
• --stability=stable：明确要求安装稳定版本。对于 Yii2 或 Symfony 等项目，如果不加此参数，可能会拉取到 dev-main 这样的开发分支，导致一些关键配置（如 Yii2 的 cookieValidationKey）缺失。
• --no-interaction：关闭交互式提示。对于 Lara vel 项目，这会跳过诸如“是否安装 Breeze/Jetstream 前端脚手架”之类的选择，让安装过程完全自动化，这在 CI/CD 流水线中是必备选项。

一个完整的 Lara vel 11 初始化命令示例看起来是这样的：
composer create-project lara vel/lara vel:^11.0 myapp --no-interaction --no-scripts --prefer-dist

装完不能直接跑？三件事漏一不可

骨架下载成功，并不意味着项目已经准备就绪。很多开发者遇到的“Class not found”或“500 Internal Server Error”错误，其实只是漏掉了以下三个标准步骤：

• 复制环境文件：进入项目目录后，需要根据模板创建实际的配置文件。在 Lara vel 中是 cp .env.example .env；在 Yii2 中，则需要运行 php init 命令并按提示选择环境。
• 生成应用密钥：对于 Lara vel，必须执行 php artisan key:generate 来生成一个唯一的 APP_KEY。否则，所有会话（session）、加密 cookie 都会失效。
• 设置目录权限：在 Linux/macOS 环境下，需要确保框架有写入权限，通常执行 chmod -R 775 storage bootstrap/cache。否则日志无法写入，视图缓存也无法生成。

还有一个极易忽略的配置：确保你的 Web 服务器（如 Nginx 或 Apache）的根目录（Document Root）正确指向了项目的 public/ 目录（Lara vel）或 web/ 目录（Symfony），而不是整个项目的根目录。

--no-install 和 --no-dev 到底影响什么？

参数选择不当，会让事情变得更复杂。--no-install 就是一个典型的“陷阱”选项，它声称可以“省事”，但实际上只解压项目源码，完全不安装任何依赖，也不会生成至关重要的 vendor/autoload.php 文件。结果就是，你尝试运行 php artisan 时，会立刻遭遇 Class ‘Illuminate\Foundation\Application’ not found 这样的致命错误。

• --no-dev：这个参数会跳过 composer.json 中 require-dev 部分定义的开发依赖包（如 PHPUnit、Faker）。它适用于生产环境部署，以减小依赖体积。但要注意，有些项目模板的初始化脚本（如 post-root-package-install）可能依赖这些开发包，此时使用该参数反而会导致安装失败。
• 离线安装策略：如果需要在离线环境部署，正确的流程是先用 --no-install 拉取代码，然后进入项目目录，手动执行 composer install --no-dev 来安装生产依赖。
• 版本兼容性错误：如果遇到 [RuntimeException] Package has a PHP requirement incompatible with your PHP version 这样的错误，问题不在 Composer，而在于目标项目要求的 PHP 版本（例如 8.2）高于你本地的 PHP 版本（例如 8.1）。解决方案要么是升级本地 PHP，要么是指定一个兼容的旧版本项目。

话说回来，最隐蔽的坑往往来自 PHP 扩展。例如，Lara vel 运行依赖于 openssl、pdo、mbstring 等扩展。缺少任何一个，create-project 过程都可能静默失败，或者安装后运行 artisan 命令时突然报错“找不到类”。一个良好的习惯是，在执行安装命令前，先通过 php -m | grep -E “(openssl|pdo|mbstring)” 这样的命令快速检查一下关键扩展是否已就位。