Composer怎么配合Yii框架使用_Composer Yii项目集成配置【详解】

说实话，很多人一上手Yii2，第一反应就是“Composer怎么配合Yii用”——这个问法本身就有点偏差。说白了，Composer不是“配合”Yii工作，而是Yii能跑起来的根基。没有它，Yii这个类都加载不了，你敲php yii命令，它直接给你甩个报错。下面这些细节，才是真正让你少踩坑的关键。

composer.json 里 require 和 require-dev 别混用

生产环境里，只有 require 里的包才是“正式员工”。yiisoft/yii2、ext-mbstring、pdo 这些必须放在这里；而 require-dev 是给本地开发用的，比如 phpunit/phpunit、yiisoft/yii2-debug。CI/CD 流水线默认跑的是 composer install --no-dev，require-dev 里的东西根本不会下载，更不会写进 vendor/autoload.php。

• 把 phpunit 写进 require，上线后它会多加载几十个测试类，还可能触发 autoloader 冲突，得不偿失。
• yii2-debug 的 autoload 是 psr-4："yii\debug\": "src/"，它依赖 vendor 目录下真实路径可读；而 yii2-jui 用的是 classmap，更新后必须手动跑 composer dump-autoload -o。
• 自己写的扩展，如果漏了 autoload 声明，Yii::createObject() 就找不到类，报 Class not found 的错误。

入口文件里 autoload.php 路径写错就全崩

所有 Yii 入口文件（web/index.php、frontend/web/index.php）第一行必须是：require __DIR__ . '/../vendor/autoload.php';。高级模板里 web/ 是子目录，少一个 .. 就找不到 vendor，Class 'Yii' not found 立刻出现。

• 检查方式：进入 web/ 目录后执行 ls ../vendor/autoload.php，能列出文件才说明路径对了。
• 别手改或复制 autoload.php——它由 Composer 自动生成，每次 install 或 update 后都会重写。
• 如果加了自定义命名空间（比如 "App\Models\": "app/models/"），Yii 的 Module::getControllerPath() 和 Gii 生成器仍然按约定找 controllers/、models/ 相对路径，不是靠命名空间映射。

安装必须用 create-project，别 require 核心包

composer require yiisoft/yii2 只拉核心库，没有 web/、config/、runtime/ 目录，也没有 index.php 入口，项目根本跑不起来。官方模板（yii2-app-basic 或 yii2-app-advanced）才是完整的骨架。

• 基础版命令：composer create-project --prefer-dist yiisoft/yii2-app-basic basic
• 高级版必须紧接着跑 php init，否则 environments/dev/frontend/web/index.php 不会生成，访问直接报 Invalid Configuration。
• 装完立刻看 vendor/yiisoft/yii2/VERSION，别信 composer show yiisoft/yii2 显示的 “latest”，那只是 Packagist 上的 tag。
• PHP 版本和扩展缺失（如 pdo、mbstring）不是 Composer 错误，是运行环境问题。先用 php -m | grep -E "pdo|mbstring" 确认一下。

版本约束写错会让整个应用启动失败

Yii2 和 Yii3 完全不兼容。"yiisoft/yii2": "^2.0.0" 看似安全，但一旦被其他包间接升级成 "^3.0.0"，new yiiaseComponent() 就会爆 Class 'yiiaseComponent' not found（注意少了反斜杠）。

• Yii2 项目务必锁死范围："yiisoft/yii2": "~2.0.49"（波浪号只允许补丁级更新）。
• Yii3 要配齐配套包："yiisoft/yii-core": "^3.0" + "yiisoft/di": "^3.0"，少一个 new Container() 就失败。
• 卡住升级时，用 composer why-not yiisoft/yii2:2.0.49 快速定位哪个依赖在拦路。

说实话，最常被忽略的其实是 cookieValidationKey 没设——它不报错在 Composer 层，但一访问首页就 InvalidConfigException，而且这个 key 上线后不能改，否则所有用户得重新登录。