Composer命令怎么查阅 Composer官方文档使用指南

在日常使用 Composer 时，有几个高频问题经常让人犯嘀咕：命令怎么查、依赖怎么分类、install 和 update 到底选哪个，还有那个让人头疼的 autoload 加载失败。其实把这些基础逻辑梳理清楚，后续的依赖管理会顺手很多。

Composer 命令查不到 help 选项，怎么办

很多人习惯直接敲 composer，发现只显示版本号和 usage 提示，命令列表并不出现。这不是 Composer 偷懒，而是它的帮助系统对空命令或 -h 参数（尤其是一些旧版本）根本不响应。正确的打开方式是加 --help 或者用 composer list。

常见的错误现象很集中：

• 直接敲 composer 回车，只会看到版本号和简单提示，不列具体命令。
• 运行 composer -h，如果在较老的 Composer 2.0 之前版本，会直接报错 Unrecognized option "-h"。
• 误输 composer help（没加 --），Composer 会提示 Command "help" is not defined。

正确做法其实很简单：

• composer --help 是最稳妥的，会显示全局选项和所有内置命令名。
• composer list 是等价的，而且更直观，日常推荐用它。
• 想查某个具体命令的参数和别名，比如 composer require --help 或 composer show --help，这样就能看到 --all 和 --installed 到底有什么区别。

composer.json 里 require 和 require-dev 的区别在哪

这两个字段都用来写依赖，但作用域完全不同。一旦混淆，生产环境很可能多出一堆调试工具，或者本地测试跑不起来——都不算罕见。

关键差异要记住：

• require 是运行时必需的库，composer install 默认只安装这部分；上线部署时必须保留。
• require-dev 仅开发阶段需要，比如 phpunit/phpunit、phpstan/phpstan 这类工具。执行 composer install --no-dev 会直接跳过它们。
• 如果项目里配置了 autoload-dev，对应路径下的类只在开发环境下自动加载，生产环境是看不见的。
• composer update 默认会同时更新 require 和 require-dev，只有加了 --no-dev 才会跳过后者。

容易踩的坑有两个：

• 把 symfony/var-dumper 这样的调试工具写进 require，后果是生产环境也会加载 dump() 函数，存在安全隐患。
• CI 流水线没加 --no-dev，构建出的镜像体积会变大，还可能因为 dev 包触发了额外的 autoload 规则，导致性能下降。

composer install 和 composer update 到底该用哪个

一句话判断：composer install 是按 lock 文件还原依赖，composer update 是重新解析并升级依赖。日常开发中，90% 的场景应该用 install。

不同场景的用法很明确：

• 第一次拉下项目代码，必须用 composer install。如果没有 composer.lock 文件，它也会自动生成。
• 团队协作、CI/CD 构建、线上部署，只能用 composer install，确保所有人装的版本完全一致。
• 想升级某个特定包（比如 monolog/monolog）到新版本，先改 composer.json 中的版本约束，然后运行 composer update monolog/monolog。
• 想批量更新所有包到最新兼容版本，可以用 composer update，但前提是务必先提交当前的 composer.lock 文件，否则一旦出问题，回滚会很麻烦。

性能和风险方面，有几个点值得注意：

• update 会重新走一遍依赖求解（solver），耗时较长。在大型项目中，卡住几秒甚至几十秒都算正常。
• update 有可能引入破坏性变更（BC break）。即使版本号符合 ^2.0 约束，也建议先用 composer outdated 查看哪些包可以安全升级。
• 如果没有 composer.lock 文件，install 的行为其实等同于 update，但不会生成 lock 文件——这属于配置缺失，不属于正常流程。

vendor/autoload.php 加载失败的常见原因

报错 Warning: require(vendor/autoload.php): failed to open stream 或者 Fatal error: Uncaught Error: Class 'Monolog\Logger' not found，基本都可以归为以下三类问题。

排查顺序可以这样来：

• 先确认 vendor 目录是否存在，里面有没有 autoload.php 文件。如果没有，说明 composer install 没成功运行，或者 .gitignore 误删了目录。
• 检查 require 路径是否写错。推荐用 __DIR__ . '/vendor/autoload.php'，不要硬写相对路径比如 ../vendor/autoload.php，因为执行位置不同很容易失效。
• 确认 PHP 版本是否满足依赖要求。比如某个包声明了 "php": "^8.1"，但服务器跑的是 PHP 7.4，composer install 会静默跳过 autoload 生成。可以通过 composer diagnose 来发现这类问题。
• 如果用了自定义 autoloader（比如 PSR-4 映射），要检查 composer.json 中 autoload 字段的拼写是否正确。key 必须是 "psr-4"，不是 "psr4" 或 "PSR-4"。

还有一个容易被忽略的点：某些 IDE 或部署脚本会清理空目录。而 vendor 下某些包的 tests/ 或 docs/ 目录可能是空的，被误删后可能触发 Composer 的 autoload 重生成失败。建议在 composer.json 中加入 "optimize-autoloader": true，并运行 composer dump-autoload -o 生成优化版映射。