Composer怎么管理多环境配置_Composer如何区分开发测试和生产环境的依赖安装【指南】

生产环境必须加--no-dev，否则会强制安装PHPUnit、PHPStan等dev包，导致体积膨胀、启动变慢、暴露调试入口甚至fatal error；其生效前提为composer.lock不含dev包记录。

在生产环境执行 composer install 时，如果漏掉 --no-dev 参数，后果可不是“可能有点小麻烦”。这相当于把 PHPUnit、PHPStan、Xdebug 这些开发调试工具，一股脑全打包进了线上容器或服务器——结果几乎是注定的：镜像体积膨胀、应用启动变慢、调试接口意外暴露，更糟的是，还可能因为生产环境缺失某些扩展而直接导致致命错误。

composer install 默认到底装哪些包？

这个问题很关键。composer install 的行为其实很“单纯”：它完全依据 composer.lock 文件里的记录来安装，里面写了什么，它就装什么。那么，这个 lock 文件里的记录又是怎么来的呢？这取决于你上次生成或更新它时，用的是 composer update 还是 composer update --no-dev。

日常开发中，经常能见到两种典型的错误现象：一种是明明执行了 composer install --no-dev，但 vendor/ 目录里依然能找到 phpunit；另一种是线上应用突然抛出 Class 'Mockery\MockInterface' not found 异常，而你明明记得 mockery/mockery 这个包是放在 require-dev 里的。

• 根本原因：问题出在 lock 文件本身。如果 composer.lock 里已经包含了 require-dev 中定义的包，那么 install 命令就会默认安装它们。此时，即便加上 --no-dev 参数也无效，因为它无法改变 lock 文件已确定的包列表。
• 正确做法：在持续集成（CI）流程中，为生产环境构建镜像之前，应该先运行一次 composer update --no-dev --lock。这个命令会基于当前的 composer.json，但仅更新非开发依赖，并生成一个不包含 dev 包记录的干净 lock 文件。将这个新 lock 文件提交后，后续的部署流程再使用 composer install --no-dev 就能确保只安装生产依赖了。
• 这里有个重要原则需要牢记：composer install 从不修改 lock 文件，它只是忠实的执行者；而 composer update 才会根据 json 文件去更新 lock。因此，在部署阶段，永远不要使用 update 命令。

require-dev 里的包，真能“只在开发用”吗？

答案是不能一概而论。一个包是否真的能安全地限定在开发环境，关键不在于它被放在哪个配置段，而在于它是否会被生产环境的运行时代码直接引用。

举个例子：很多项目会把 symfony/var-dumper 这样的调试工具放在 require-dev 里。这看起来没问题，但如果在某个控制器里不小心留下了 dump($data) 这样的调试语句，并且这个控制器在某种条件下（比如开启了调试模式）被线上请求触发了，那么这个包就瞬间变成了运行时依赖——缺少它，应用就会直接返回 500 错误。

• 检查方式：对于每一个列在 require-dev 里的包，一个可靠的验证方法是，在项目根目录执行类似 grep -r "vendor/name" src/ tests/ 的命令。重点检查 src/ 这类生产代码目录下，是否存在直接的 use 或 new 语句引用了该包。
• 需要区分一个概念：autoload-dev 配置项只影响 Composer 自动加载器去扫描哪些路径（比如 tests/ 测试目录），它与“包是否被安装”是两回事。如果 require-dev 里的包根本没有被安装，那么即使配置了对应的 autoload-dev 路径，也是无效的。
• 另一个细节是：运行 composer dump-autoload --no-dev 时，Composer 才会从生成的 vendor/autoload.php 文件中剔除 autoload-dev 所配置的路径映射。如果漏掉了这一步，自动加载文件可能仍然包含测试类的路径，在某些情况下会引发自动加载冲突。

Docker 和 CI 里怎么写才不出错？

在自动化的构建和部署流程中，可靠性源于显式和明确。相关的参数必须写死，不能省略，也不要过度依赖环境变量的“默认”行为。虽然设置 COMPOSER_DEV_MODE=0 环境变量有一定作用，但直接使用 --no-dev 参数优先级更高，意图也更清晰、更可控。

• Dockerfile：在生产镜像的构建指令中，应该明确写成：RUN COMPOSER_DEV_MODE=0 composer install --no-dev --optimize-autoloader。双管齐下，确保万无一失。
• GitHub Actions 缓存：缓存键（cache key）的设计必须包含明确的语义。例如，应该使用 composer-${{ hashFiles('**/composer.lock') }}--no-dev 这样的格式，将是否安装 dev 包作为缓存键的一部分。否则，缓存可能会在不恰当的阶段被复用，导致开发包被意外安装或漏装。
• CI 流程阶段分离：在 CI 的测试阶段，需要完整安装所有依赖，命令通常是 composer install && ./vendor/bin/phpunit。而到了为生产环境构建的阶段，则必须切换回 --no-dev 模式。这两个阶段的命令和上下文必须严格区分，不能混用。
• 一个禁止项：除非是在一个专门用于更新依赖的独立流水线中，否则禁止在常规的 CI 脚本里出现 composer update 命令，以免意外污染 lock 文件。

最后，还有一个最容易被忽略的要点：并非所有“开发阶段使用”的工具，都适合放进 require-dev。举个例子，像 roa ve/security-advisories 这类仅用于本地安全扫描、既不参与运行时也不参与构建过程的工具包，其实根本不应该进入项目的 composer.json。为它们创建一个临时的容器环境，或者通过独立的本地脚本运行，是更清晰、更干净的做法。