dump-autoload 不能解决类路径或命名不匹配问题，仅刷新自动加载映射；常见原因包括 PSR-4 命名空间与目录结构不一致、autoload 路径配置错误、classmap 未覆盖新增文件、OPcache 或 IDE 缓存未清除。
Composer 自动加载失效，不是 autoload 配置错了，就是类文件没按 PSR-4/PSR-0 规则放对位置 —— dump-autoload 只是刷新映射，不解决根本路径或命名问题。
为什么 dump-autoload 执行后仍找不到类？
常见现象：新增类文件后 php artisan tinker 或 php index.php 报 Class not found，但 composer dump-autoload 明明执行成功了。
- PSR-4 的
namespace和目录结构不匹配（比如App\Models\User对应的文件却放在src/Model/User.php，少了个s） -
composer.json里autoload段写的是"App\\": "src/"，但实际类在app/下，路径没同步 - 用了
classmap但新增文件没在已扫描目录内，又没加--optimize或重新生成 - 开发中启用了 OPcache，PHP 缓存了旧的 autoloader，导致新映射不生效
执行 dump-autoload 前必须检查的三件事
别急着敲命令，先确认这三项是否对齐：
- 类文件路径是否严格符合 PSR-4 声明：比如
"App\\": "app/"→app/Http/Controllers/HomeController.php内必须有namespace App\Http\Controllers; -
composer.json中的autoload和autoload-dev是否包含你当前修改的目录（尤其是测试类或新模块） - 运行
composer show -s看当前 autoload 配置是否已加载；再跑composer dump-autoload -v（加-v查看详细扫描路径），确认你的文件夹真被扫进去了
dump-autoload 的实用参数组合
默认命令只生成开发用的映射，生产环境或排查问题时需要更精准控制：
-
composer dump-autoload --optimize：生成扁平化classmap，跳过 PSR 解析，适合部署后提速，但会忽略动态 require 的文件 -
composer dump-autoload --classmap-authoritative：强制只走 classmap，完全禁用 PSR fallback，能提前暴露漏扫的类 -
composer dump-autoload -o -a：等价于--optimize --classmap-authoritative，CI/CD 流水线常用 - 如果只是改了某几个文件，可临时用
composer dump-autoload --no-scripts跳过 post-autoload-dump 脚本干扰
OPcache 和 IDE 缓存带来的“假失效”
命令行跑通但 Web 请求仍报错？大概率是缓存没清干净：
- CLI 和 Web SAPI 的 OPcache 是分开的，
php -r "opcache_reset();"只清 CLI，Apache/Nginx 需要重启或调用对应 SAPI 的 reset（如通过opcache_get_status()页面触发） - VS Code / PHPStorm 有时会缓存符号表，关掉再重开项目，或手动执行
Index → Reload project from disk - 某些 Docker 环境中，宿主机改了文件但容器内 inotify 没监听到，
composer dump-autoload在容器外执行无效，必须进容器执行
真正卡住的地方往往不在命令本身，而在 namespace、路径、缓存三者的隐式耦合 —— 尤其当项目混用 PSR-4 和 classmap，或者从 Laravel 迁移时保留了旧 app/ 结构但 composer.json 指向了 src/。这时候 dump-autoload -v 输出的扫描日志，比任何文档都管用。
