Class not found 错误90%源于命名空间、composer.json配置与文件路径三者未对齐；需严格检查namespace末尾双反斜杠、PSR-4前缀匹配、路径大小写及composer.json格式有效性。
Class not found 错误里，90% 不是类写错了，而是命名空间声明、composer.json 配置、文件路径三者之间有一处没对齐。 直接看 composer dump-autoload -v 输出，比翻代码快十倍。
为什么 namespace 声明少一个反斜杠就找不到类
PHP 允许写 namespace AppHttpControllers;（带反斜杠）和 namespace AppHttpControllers;（不带），但 Composer 的 PSR-4 匹配是字符串级精确比对：它拿你声明的完整命名空间字符串，去匹配 composer.json 里配置的前缀（如 "App\": "src/"）。如果声明写成 namespace AppHttpControllers;，那整个字符串就不以 App 开头，PSR-4 映射直接跳过。
常见错误现象：
- 文件在
src/Http/Controllers/HomeController.php，但报Class 'AppHttpControllersHomeController' not found -
composer dump-autoload -v输出里完全没扫这个文件，也没映射任何App下的类
检查要点：
- 确认类文件顶部
namespace声明末尾有双反斜杠：namespace AppHttpControllers;（注意不是单斜杠，也不是没斜杠） - 确认
composer.json中 PSR-4 键是"App\": "src/"，不是"App": "src/"或"App/": "src/" - 用
grep -n "namespace" src/Http/Controllers/HomeController.php快速验证声明是否一致
composer.json 配置没被读取的三个硬信号
运行 composer dump-autoload -v 后，输出里压根没出现你的命名空间前缀或扫描路径？说明配置根本没生效。这不是 autoload 失效，是配置失联。
必查三点：
-
composer.json缩进用了 tab 而非空格（JSON 不允许 tab）或末尾多了一个逗号（JSON 不允许尾逗号） - 字段名拼错：比如写成
autoloader、auto_load、autoloads，正确只能是autoload - 改的是子目录下的
composer.json（比如某个 vendor 包里的），而不是项目根目录那个
验证方法：
- 先跑
composer validate—— 如果报错，说明 JSON 格式或字段名有问题 - 再跑
composer show -s—— 如果 autoload 段为空，说明配置没加载，dump-autoload 再跑十遍也没用
文件路径与命名空间推导断裂的典型表现
PSR-4 不是“看到 src/ 就扫所有 PHP 文件”，而是严格按规则截前缀、拼路径。很多人卡在“文件明明存在，就是不加载”，本质是推导路径和实际路径不一致。
假设配置是 "App\": "src/"，那么：
-
namespace AppHttpControllers;→ 截掉App，剩HttpControllers→ 拼路径src/Http/Controllers/ - 类名
HomeController→ 文件必须叫HomeController.php，不能是homecontroller.php或Home.php - 目录名大小写必须完全一致：Linux 下
src/http/controllers/≠src/Http/Controllers/
容易踩的坑：
- 把文件放在
app/Http/Controllers/，但配置写的是"App\": "src/"——dump-autoload -v根本不会扫app/这个目录 - 类名是
UserRepository，但文件叫user-repository.php—— PSR-4 要求文件名 = 类名，不含扩展名，大小写全等 - IDE 自动生成了嵌套命名空间如
AppApiV1ControllersUser，但实际路径是src/Api/v1/Controllers/User.php—— 小写v1在 Linux 下直接失败
为什么删 vendor/autoload_*.php 后再 dump 才有效
Composer 会缓存生成的 autoload 文件（如 vendor/composer/autoload_psr4.php）。如果你改了 composer.json 但只跑 composer dump-autoload，它可能复用旧缓存，导致新配置不生效 —— 尤其是 CI 环境或频繁切换分支时。
可靠做法：
- 删掉整个
vendor/composer/下的 autoload_*.php 文件（不是删 vendor 目录） - 再执行
composer dump-autoload -v - 检查输出里是否出现了你的命名空间前缀、扫描路径、以及具体类的映射行
最常被忽略的一点：classmap 和 psr-4 同时存在时，classmap 优先级更高。如果你在 classmap 里手动加了 "lib/Utils.php"，又在 psr-4 里配了 "App\": "src/"，那 new Utils() 会走 classmap，而 new AppUtils() 才走 psr-4 —— 两者互不干扰，但排查时容易误判为“psr-4 失效”。
