如何使用Composer require命令安装扩展包？

本文共计865个文字，预计阅读时间需要4分钟。

为什么不能手动改 composer.json 再跑 composer install

手动编辑容易漏掉三件事：版本号写错（比如把 ^2.9 写成 2.9）、没加 ^ 导致 Composer 解析为精确匹配（而 Packagist 上往往没有 exact 版本）、忘记运行 composer install 就直接写代码。这些都会造成本地能跑、CI 报错、线上 Class not found。而 composer require 任一步失败就中止，不会留下半残状态。

composer require 的版本约束怎么写才不翻车

常见错误是以为 1.2 就是固定小版本，其实它等价于 ^1.2.0，会升到 1.999.999；真要锁死次版本，得用 ~1.2.0（允许 1.2.x，但不进 1.3.0）。

• guzzlehttp/guzzle:^7.5.0 → 允许 7.5.0 到 7.999.999，不跨 8.0
• monolog/monolog:~2.9.0 → 允许 2.9.0 到 2.9.999，不进 2.10.0
• 不写版本号（如 composer require foo/bar）→ Composer 自己猜最新稳定版，可能选到 v3 而非你期望的 v2
• 想查某包所有可用版本？运行 composer show foo/bar --all

开发依赖和生产依赖必须分开写

require-dev 不是“放不重要的包”，而是明确告诉 Composer：“这个包只在开发时需要，部署时请彻底跳过”。否则 CI 流水线加了 --no-dev，结果关键类因为依赖被误塞进 require-dev 而炸了。

• 装 PHPUnit：composer require --dev phpunit/phpunit:^10 → 写入 require-dev
• 装 Guzzle（运行时必需）：composer require guzzlehttp/guzzle:^7.5 → 写入 require
• 如果某个包既被 require 又被 require-dev 引入，最终生效的是 require 里的版本约束
• 部署命令必须带 --no-dev，否则开发工具会打进生产环境

装完之后类还是找不到？别急着删 vendor

新增包后，vendor/autoload.php 不会自动重生成映射——它只反映上一次 composer dump-autoload 的结果。哪怕包自身有 autoload 配置，也得靠这一步注册进去。

• 检查该包的 composer.json 是否含 autoload 字段（比如 "psr-4": {"Monolog\": "src/"}）
• 如果你自己项目加了新命名空间（如 "psr-4": {"App\": "app/"}），必须手动运行 composer dump-autoload
• 调试 autoload 问题时，可先加 --no-autoloader 参数跳过自动加载注册，再单独跑 dump-autoload
• 线上报错而本地正常？优先核对 composer.lock 是否提交、CI 是否用了旧 lock 文件

最常被跳过的动作不是加包，而是确认 composer.lock 已更新、dump-autoload 已执行、且部署流程里没漏掉 --no-dev —— 这三处任意一个出问题，都比包本身难排查。