必须运行 composer dump-autoload 当手动新增 PHP 类但未更新 autoload 配置，或修改了 composer.json 中的 autoload/ autoload-dev；此时类无法被自动加载，导致 class not found 错误。
composer dump-autoload 什么时候必须运行
当你手动新增了 PHP 类文件，但没改 composer.json 的自动加载配置（比如没加新 psr-4 映射、也没把文件放进已声明的命名空间目录），composer 就不知道该类的存在——此时 class not found 错误不是代码问题，而是自动加载器没刷新。
常见场景包括：
- 在已有 PSR-4 命名空间目录外，新建了一个类并想直接
use它 - 改了
composer.json里的autoload或autoload-dev配置 - 从 git 拉了别人加了新类的代码，但本地没执行过 autoload 更新
注意：composer install 和 composer update 默认会自动触发 dump-autoload；但仅改代码或配置后不重装依赖，就必须手动跑。
composer dump-autoload 的常用参数怎么选
composer dump-autoload 默认只生成生产环境的自动加载映射（跳过 autoload-dev）。如果你在写测试、用 tests/ 下的类，或者用了 files 类型的全局加载，不加参数就会找不到这些类。
关键参数组合：
-
--dev：包含autoload-dev配置（比如tests/目录和files列表） -
-o（即--optimize）：生成优化版classmap，跳过动态扫描，适合部署环境；但会忽略files加载项 -
--classmap-authoritative：告诉 autoloader “所有类都在 classmap 里”，找不到就直接报错，不 fallback 到文件系统查找；配合-o使用更安全 - 开发中推荐：
composer dump-autoload --dev，兼顾完整性和调试友好性
为什么 vendor/autoload.php 能直接 require，但改完却没生效
因为 vendor/autoload.php 是一个“门面”，它内部加载的是 vendor/composer/autoload_*.php 这些生成的映射文件。你改了代码或配置，但没运行 dump-autoload，这些底层映射文件就不会更新——require 的还是旧的路由表。
容易踩的坑：
- 误以为改完
composer.json后只要composer update就行，其实如果只是改 autoload 没动依赖版本，update可能跳过 autoload 重建（尤其启用了--lock或缓存） - 在 docker 或 CI 环境里，
vendor/是挂载卷或缓存的，本地运行了dump-autoload，但容器里没运行，结果容器内仍报错 - 用了
composer install --no-autoloader，后续忘了补dump-autoload
autoload 生成失败的典型错误信息怎么看
遇到报错别急着重装，先看具体提示：
-
Class XXX is not autoloadable, can not use it in YYY：说明这个类没被任何 autoload 规则覆盖，检查路径是否符合 PSR-4 声明，或是否漏加files条目 -
Warning: Ambiguous class resolution：两个不同路径下存在同名类（比如src/Helper.php和lib/Helper.php），autoloader 不知道该加载哪个；删掉冗余文件或调整映射优先级 -
Could not scan for classes inside "xxx" which does not appear to be a file nor a folder：composer.json里写了不存在的目录，检查psr-4或classmap路径拼写和大小写
真实项目里，autoload 问题往往不是“不会用”，而是“改了什么自己忘了通知 composer”。每次增删类、挪目录、改配置，顺手敲一行 composer dump-autoload --dev 几乎能避开 80% 的类加载异常。