Composer项目中如何正确使用dev依赖配置

Composer项目中如何正确使用dev依赖配置

一个核心原则必须牢记：开发依赖必须严格写入 require-dev 字段，并且在安装时明确加上 --dev 参数。 如果这一步搞错了，后果可能很严重——不仅会污染生产环境的依赖树，上线后还可能因为依赖包缺失或者自动加载规则冲突，导致应用直接报错。

话说回来，如果已经误将包写入了require字段，补救措施也很直接：删除vendor目录和composer.lock文件，然后重新安装。

怎么把包正确加进 require-dev

使用 composer require 命令时，--dev 参数的位置是关键。记住，它必须紧跟在命令末尾，顺序不能乱：

• composer require phpunit/phpunit --dev ✅（正确，包会写入 require-dev）
• composer require --dev phpunit/phpunit ✅（等效，同样正确）
• composer require phpunit/phpunit ❌（错误，包会误入 require，导致生产环境也被安装）
• composer require phpunit/phpunit -d ❌（注意，-d 是旧版别名，在 Composer 2.2 及以上版本中，建议统一使用 --dev）

安装完成后，一个好习惯是立刻检查 composer.json 文件：确认新增的包确实出现在 "require-dev" 字段下面，而不是 "require" 里。否则，后续执行 composer install --no-dev 时，这个包依然会被安装进来，那就失去隔离开发依赖的意义了。

为什么 --no-dev 有时不生效

有时候明明加了 --no-dev 参数，开发依赖却依然被安装了，或者反过来，没加参数却跳过了安装。这通常不是参数本身的问题，而是环境变量或者锁定文件在“捣鬼”：

• 环境变量干扰：如果全局环境变量 COMPOSER_NO_DEV 被设置成了 1（例如在某些CI/CD脚本中设置了但未清除），那么即使你执行命令时再加 --no-dev，效果也是重复的；而如果你漏掉了这个参数，命令反而会跳过开发依赖。第一步，先检查一下环境变量：echo $COMPOSER_NO_DEV。
• 锁定文件的影响：如果团队中有人使用 composer install --no-dev 生成了 composer.lock 文件并提交到了仓库，那么你本地直接执行不带参数的 composer install 时，也会按照这个锁定文件的记录来安装，自然就不会包含开发依赖了。
• 如何验证：运行 composer show --dev，如果输出显示 No dependencies installed for development，才算是真正跳过了开发依赖。为了更保险，还可以手动去 vendor/ 目录下看看，像 phpunit、php-cs-fixer 这类典型的开发工具目录是否还存在。

dev 分支依赖怎么安全引入

有时候需要直接依赖某个Git仓库的开发分支（比如dev-main），但直接这么写很容易失败，因为Composer默认只识别稳定的（stable）版本。

• 先确认分支名：别想当然地用 main。使用 composer show vendor/package --all 命令查看该包的所有可用分支，GitHub的默认分支也可能是 develop 或 next。
• 锁定具体提交：安装时带上具体的commit hash会更稳妥，例如 composer require vendor/package:dev-main#abc123。这样可以避免下次执行 composer update 时，拉取到意料之外的代码变更。
• 调整稳定性设置：如果不想全局修改稳定性设置，可以在安装时使用 --stability-dev 参数：composer require vendor/package:dev-main --stability-dev。这个操作会自动在 composer.json 中添加相应的 "stability-flags" 配置。
• 注意风险：需要警惕的是，开发分支没有语义化版本约束，这意味着 composer update 可能会拉取到不兼容的新提交，composer.lock 文件也无法像标签（tag）那样提供确定的版本保证。

autoload-dev 和 --no-dev 的关系容易被忽略

这里有个容易踩的坑：--no-dev 参数只控制「是否安装开发依赖包」，但并不控制这些包定义的「自动加载规则是否被注册」。

• 举个例子，如果一个仅在 require-dev 中声明的包，在其 composer.json 里定义了 "autoload-dev": {"psr-4": {"Tests\": "tests/"}}，那么当它被 --no-dev 跳过安装后，vendor/autoload.php 文件自然就不会加载 Tests\ 这个命名空间。
• 问题来了：如果你的生产代码里不小心写了 new Tests\FooTest() 这样的调用，运行时就会抛出 Class not found 错误——因为类既没有被安装，也没有被映射到自动加载器中。
• 更隐蔽的情况是：有些包的配置可能写混了，误将生产代码的路径放在了 autoload-dev 里，或者反过来。这时，即便使用了 --no-dev，也无法阻止这些类的加载规则被注册，从而导致环境边界模糊。

所以，真正需要留意的，是那些既在 require-dev 里声明，又通过 autoload-dev 暴露了生产环境可能用到的类的包。它们会让开发和生产环境的边界变得模糊不清，在上线前，务必人工仔细审查一遍。