为什么我的Composer自动加载（Autoload）不生效？五步排查法

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/" 表示 AppFooBar 类必须位于 src/Foo/Bar.php
• 路径末尾不能带 /（虽然 Composer 有时容忍，但某些版本会静默失败）
• 检查大小写：linux 系统下 src/Models/User.php 无法被 AppModelsuser 加载（类名小写）
• 运行 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 里有没有你期望的映射项，没有就说明配置或路径肯定不对。