Composer的依赖分层管理策略

Composer依赖分层管理的核心逻辑与常见陷阱

说到底，Composer在安装依赖时，其底层逻辑并不区分“开发”与“生产”的行为模式。它只认两样东西：当前的环境变量，以及composer.json里白纸黑字写着的require和require-dev分区。这恰恰是许多部署问题的根源。

为什么 composer install 有时装出不同版本？

你猜怎么着？如果在CI流水线或者生产服务器上，你习惯性地敲下composer install而忘了加上--no-dev这个关键参数，那么所有躺在require-dev里的包——比如phpunit/phpunit、mockery/mockery这类测试工具——就会一并被安装到线上环境。这不仅仅是增加了不必要的部署体积，更可能引入意料之外的自动加载冲突，甚至潜在的安全风险。

那么，正确的实操姿势是什么？

• 线上部署必须是硬性动作：务必使用composer install --no-dev --optimize-autoloader。这事儿不能只靠文档提醒，得成为肌肉记忆。
• CI流水线要明确阶段：测试阶段可以用默认的composer install（包含开发依赖）；但在构建最终部署产物的阶段，必须切换到生产模式。
• 锁住版本一致性：务必检查composer.lock文件是否提交到了代码库。这个文件是所有环境安装一致性的基石，没提交它，就等于没锁住版本，各环境装出不同依赖组合也就不奇怪了。

require-dev 里能放运行时需要的包吗？

技术上可行，但从架构设计上讲，这通常是个坏主意。举个例子，假如你把symfony/var-dumper这样的调试工具只放在require-dev里，本地开发一切正常。可一旦代码上线，如果某个未捕获的异常触发了错误页面，而这个页面又恰好依赖它来渲染变量信息，那么用户看到的将直接是一个冰冷的Class not found错误。这类包本质上属于“条件性运行时依赖”，而非纯粹的开发工具。

如何准确判断一个包该归入哪一类？可以看这几个标准：

• 检查自动加载引用：这个包是否在autoload（而非autoload-dev）配置中被引用？如果主业务代码里直接use了它，那它就应该放进require。
• 审视脚本调用：它是否会被bin/目录下的自定义命令行脚本直接调用？例如，一个内部工具依赖guzzlehttp/guzzle来发送HTTP请求，那它就是实打实的运行时依赖。
• 评估间接加载路径：在生产环境的某条执行链路中，它有没有可能被间接加载？比如在日志处理器、事件监听器或某个中间件里，直接实例化了它的类。

如何安全地升级 require-dev 中的工具链？

升级phpunit或psalm这类开发工具，常常会引发测试大面积失败或者静态分析报告爆出大量新错误。但问题往往不在于你的业务代码，而是工具链本身对PHP版本、新语法或扩展的支持发生了变化。例如，phpunit/phpunit:^10要求PHP版本至少是8.1，如果你的项目还在跑PHP 8.0，那么composer update可能表面成功，但一执行vendor/bin/phpunit就会立刻遭遇ParseError。

因此，升级工具链需要一点策略：

• 先查后动：动手前，务必查看目标版本的官方支持矩阵，确认与当前项目PHP版本及扩展的兼容性。
• 连带升级：使用composer update phpunit/phpunit --with-all-dependencies这样的命令，确保其相关的子依赖也被同步升级，避免意外降级导致奇怪问题。
• 干跑验证：升级后，先别急着跑全量测试。用./vendor/bin/phpunit --dry-run这类命令验证工具本身能正常解析和执行，再进行全面测试。
• 锁死小版本：考虑将工具版本约束写死，例如"phpunit/phpunit": "10.5.2"，而不是使用宽松的^10.5，这样可以避免Composer自动更新到可能存在兼容性问题的小版本。

composer.json 的 config.platform 怎么影响分层？

config.platform这个配置项，会让Composer在解析依赖时，“假装”当前运行环境已经安装了指定的PHP扩展或达到了某个PHP版本。但需要注意的是，这个“假装”对require和require-dev里的所有依赖是平等生效的。这里有个常见的陷阱：假设你本地开发机装了ext-redis扩展，但生产服务器没有。为了绕过安装检测，你在config.platform里添加了"ext-redis": "5.3.7"。结果，require-dev里某个工具（比如lara vel/pint）恰好声明ext-redis是其可选扩展，Composer就会认为条件已满足，进而可能拉取一些本不该安装的Redis相关适配器或填充库。

更稳妥的做法应该是：

• 限定使用场景：config.platform最好只用于锁定PHP主版本（如"php": "8.1.10"），以避免因团队成员本地PHP小版本不同而导致依赖解析结果不一致。
• 环境问题环境解决：对于扩展缺失这类环境差异问题，应该通过Docker容器统一开发与生产环境，或者使用Ansible等运维工具确保扩展安装到位，而不是在Composer配置里“模拟”。
• 使用更精准的忽略选项：如果确实需要模拟扩展环境，在Composer 2.2+版本中，可以优先考虑使用config.platform.ignore来排除对特定扩展的检测，这比伪造一个版本号要安全得多。

说到底，依赖分层管理的真正难点不在于语法，而在于每一次修改composer.json时，都需要同步思考：这个包到底属于哪一层？它会被谁加载？在什么条件下才会生效？漏掉其中任何一次判断，都可能让一个不起眼的开发工具，悄然变成线上故障的导火索。