Composer自动加载不生效的五大原因：未引入vendor/autoload.php、命名空间与路径不匹配、类文件不满足PSR-4/classmap规则、缓存未更新、文件系统或IDE映射不同步。
Composer 自动加载不生效，通常不是 autoload 配置写错了，而是 vendor/autoload.php 没被正确引入、类名/命名空间/文件路径不匹配，或缓存没更新——先确认这五点，90% 的问题当场解决。
是否在入口文件中 require 了 vendor/autoload.php？
这是最常被忽略的一步。Composer 只生成自动加载逻辑，但不会自动执行它。
- 必须在项目启动入口（如
index.php、cli.php）顶部显式require：require __DIR__ . '/vendor/autoload.php';
- 如果用了框架（Laravel、Symfony），检查其入口是否已被修改，比如误删了该行，或改用其他 autoloader
- CLI 脚本尤其容易漏掉——哪怕
composer dump-autoload成功，没require就等于没加载
composer.json 中的 autoload 配置是否与实际文件结构一致？
常见错误是命名空间前缀（psr-4 的 key）和物理路径（value）不对应，或类文件没放在声明的目录下。
-
"App\\": "src/"表示App\Foo\Bar类必须位于src/Foo/Bar.php - 路径末尾不能带
/（虽然 Composer 有时容忍，但某些版本会静默失败） - 检查大小写：Linux 系统下
src/Models/User.php无法被App\Models\user加载（类名小写） - 运行
composer dump-autoload -v查看是否报出 “No files found for…” 类警告
类文件是否满足 PSR-4 或 classmap 的基本规则？
PSR-4 不是“自动猜路径”，它依赖严格的命名约定；classmap 则要求手动触发生成且不支持动态文件变化。
- PSR-4 下，类文件内必须有
namespace声明，且与配置中的前缀完全匹配（包括末尾反斜杠） - classmap 方式需先运行
composer dump-autoload --classmap-authoritative，且之后新增类不会自动加入——适合稳定库，不适合开发期 - 如果混用 PSR-4 和 files（如全局函数），确保
"files"数组里的路径是相对于composer.json的绝对路径（支持__DIR__吗？不支持，只能写相对路径）
是否因缓存或旧生成文件导致失效？
Composer 5.6+ 默认启用 classmap 缓存，且 vendor/composer/autoload_classmap.php 文件可能残留旧映射。
- 执行
composer dump-autoload -o（优化模式）会重建完整 classmap，适合上线；开发时用-a（--apcu）要确认 APCu 已启用 - 删除整个
vendor/composer/目录再composer install，可排除缓存污染 - 如果用 Docker 或 NFS 共享卷，注意文件系统事件监听失效，
composer watch类工具可能不触发重载
真正麻烦的是命名空间嵌套过深却没同步更新 composer.json，或者 IDE 自动生成的类文件保存后没刷新 Composer 映射——这时候别猜，直接查 vendor/composer/autoload_psr4.php 里有没有你期望的映射项，没有就说明配置或路径肯定不对。
