composer require --dev是唯一正确入口,它将包写入require-dev字段并更新lock文件,确保composer install --no-dev能准确跳过;手动编辑json后必须运行composer update --lock,否则CI可能安装旧版本或报错。

composer require --dev 是唯一正确入口
直接运行 composer require --dev 命令,才是为项目添加开发依赖的标准方式。它会把包写入 composer.json 的 require-dev 字段,并更新 composer.lock,后续 composer install 才能识别并跳过这些包(当加 --no-dev 时)。
常见错误是手动编辑 composer.json 后忘记运行 composer update --lock,导致 composer.lock 未同步,CI 流水线里 composer install 仍可能装出旧版本或报错。
- 必须用
--dev标志,composer require phpunit/phpunit --dev和composer require phpunit/phpunit写入的位置完全不同 - 不推荐用
composer update phpunit/phpunit单独升级 dev 包——它会触发整棵树重解析,可能意外升级其他包 - 如果只是想临时测试一个 dev 工具(比如
larastan/larastan),但又不想污染composer.json,可加--no-update:composer require --dev larastan/larastan --no-update,再手动删掉composer.json里那行
安装后命令在哪?vendor/bin/ 是默认出口
绝大多数 Composer 包(如 phpunit/phpunit、phpstan/phpstan)声明了 bin 字段,安装后二进制文件会落在 vendor/bin/ 下,不是全局可执行的。直接敲 phpunit 会提示 command not found,必须用 vendor/bin/phpunit。
别信“安装成功就完事了”——很多插件(比如 laravel/pint)要求宿主项目满足特定框架版本,require --dev 成功不代表命令能跑通,得看它的 require 约束是否和你的项目兼容。
- 检查包是否带 bin:打开该包在 Packagist 上的页面,点「Source」看它的
composer.json里有没有"bin": ["xxx"] - Windows 用户注意:
vendor/bin/下是 .bat 文件,不是 .exe,不能双击;Linux/macOS 下是 shell 脚本,需确保有执行权限(一般自动设置好) - 想省略
vendor/bin/前缀?可以加export PATH="./vendor/bin:$PATH"到 shell 配置,但上线部署时别这么干——PATH不可控
CI/CD 中 --no-dev 必须显式声明
生产环境部署时,composer install 默认会装 require-dev 里的包,除非你加 --no-dev。这不只是为了节省空间,更是安全底线:PHPUnit、PHPStan 这类工具自带大量反射和 eval 类逻辑,绝不该出现在线上 PHP 进程里。
很多团队在 GitHub Actions 或 GitLab CI 里漏掉这个参数,结果线上 vendor/ 多出几十 MB,还埋下 RCE 风险。
-
composer install --no-dev --optimize-autoloader --classmap-authoritative是推荐的线上命令组合 - 本地开发时若误用了
--no-dev,会导致phpunit找不到,报Class 'PHPUnit\Framework\TestCase' not found -
composer.json里没写require-dev字段?composer install --no-dev依然安全,只是没效果
扩展包里不能执行 composer install
如果你在写一个 Composer 扩展包(比如 myorg/my-macro),千万别在它的目录下运行 composer install。生成的 vendor/ 对宿主项目完全无效——Composer 只加载项目根目录下的 vendor/autoload.php。
真正起作用的是:宿主项目执行 composer require myorg/my-macro 时,Composer 解析你扩展包的 composer.json,把其中 require 声明的运行时依赖(如 illuminate/support)一并拉进宿主项目的 vendor/ 目录。
- 扩展包的
require-dev仅用于你本地开发调试,比如写测试时需要phpunit/phpunit,但它不会被宿主项目安装 - 本地联调未发布的扩展包,用
composer link或repositories的path类型,别靠git clone + composer install - CI 流水线里,扩展包的
vendor/应该被.gitignore忽略,否则容易误提交
实际操作中,最常被忽略的是 composer.lock 的更新时机和 --no-dev 的强制使用场景。这两处一旦出错,轻则本地和线上行为不一致,重则引入非预期的 dev 工具到生产环境。











