composer dump-autoload 是唯一应使用的命令，它仅按 composer.json 的 autoload 配置重新生成 autoload 文件，不重装依赖、不改 lock 文件；需确保 autoload 为顶层字段、PSR-4 末尾带反斜杠、路径相对且合法、类名与文件名严格一致；新增类文件必须加 -o 参数；验证需检查映射文件、class_exists 和 opcache。
直接运行 composer dump-autoload 就能生成或刷新 autoload 文件，不需要删 vendor、不用重装依赖，也不用改任何代码——但前提是 composer.json 里的 autoload 配置写对了。
为什么 composer dump-autoload 是唯一该用的命令
它只做一件事：按当前 composer.json 的 autoload 字段，重新生成 vendor/autoload.php 和它背后那堆映射文件（比如 vendor/composer/autoload_psr4.php）。不碰已安装的包，不改 composer.lock，不升级任何依赖。
- 执行
composer install或composer update也会顺带刷 autoload，但这是副作用——它们本质是装包命令，会重写整个vendor/，可能覆盖你本地改过的第三方代码 - CI/CD 流水线里用
install来“修自动加载”，等于每次构建都重装全部依赖，纯属浪费时间和磁盘 I/O - 你只是加了个新类、改了命名空间路径、或者从 Git 拉了别人提交的 autoload 配置？
dump-autoload是唯一安全且精准的操作
composer.json 中 autoload 配置必须满足的硬性条件
配置写错，dump-autoload 再跑十遍也没用。常见卡点：
-
"autoload"必须是composer.json的顶层字段，不能塞在require或scripts里 - PSR-4 命名空间末尾必须带反斜杠：
"App\": "src/"✅，"App"或"App\"（多一个空格）❌ - 路径值是相对于
composer.json所在目录的子路径，不支持../，也不能以./开头；"src/"✅，"./src/"❌ - 类文件必须是
.php后缀，且文件名与类名严格一致（UserService.php→class UserService），Linux 下大小写敏感 - 如果用了
classmap，默认dump-autoload不扫描文件——必须加-o才会实际遍历目录并重建映射
什么时候必须加 -o（--optimize）参数
不加 -o，Composer 只更新 PSR-4/PSR-0 映射路径，不会重新扫描磁盘上新增或删除的 PHP 类文件。也就是说，你加了一个 src/Utils/Helper.php，但没加 -o，new AppUtilsHelper() 依然报 Class not found。
- 新增、移动或删除了类文件（尤其没改
composer.json，只动了代码结构）→ 必须加-o - 生产环境部署后确保 autoload 与当前代码完全一致 → 推荐
composer dump-autoload -o --no-dev - 想启用权威 classmap 模式（遇到未声明类直接报错，不 fallback 到文件系统查找）→ 加
--classmap-authoritative，但前提是已用-o生成过 classmap - 本地开发调试时可先不加
-o，出问题再补；CI/CD 构建脚本里建议固定加-o，避免因缓存或旧映射导致偶发失败
验证 autoload 是否真正生效的三步检查法
别只看命令有没有报错，得确认映射真进了文件、类真能被识别、运行时真加载了：
- 打开
vendor/composer/autoload_psr4.php，搜你的命名空间前缀（如'App\'），确认对应路径（如__DIR__ . '/../src/'）存在且拼写一致 - 在 CLI 中临时执行：
php -r "require 'vendor/autoload.php'; var_dump(class_exists('App\User'));"，输出bool(true)才算通过 - 如果 Web 请求仍报错，检查是否用了 opcache 且没清理（
opcache_reset()或重启 PHP-FPM）；Docker 环境下更要确认vendor/目录是否真实同步到了运行容器中
最常被忽略的一点：改完 composer.json 后，人脑以为“配置生效了”，其实 vendor/autoload.php 还是旧的——它不会自己监听文件变化，必须手动敲一次 composer dump-autoload，哪怕只是改了一个斜杠。
