运行 composer dump-autoload -v 可实时查看自动加载诊断信息，包括扫描目录、匹配类、跳过文件及 PSR-4 前缀识别情况；若未出现目标命名空间（如 "App"），通常因 composer.json 格式错误、PSR-4 末尾缺反斜杠或路径使用相对写法导致。
看 composer dump-autoload -v 的实时输出，别猜路径
自动加载失败时，第一反应不是改代码，而是让 Composer 自己说话。运行 composer dump-autoload -v，它会逐行打印扫描了哪些目录、匹配到哪些类、跳过了哪些文件、PSR-4 前缀是否被识别。如果输出里压根没出现你的命名空间（比如 "App"），说明 composer.json 里的 autoload 配置根本没生效——常见原因是 JSON 格式错误（漏逗号、多逗号、缩进错）、PSR-4 键值末尾缺反斜杠（"App" 写成 "App"）、或路径写成了 ./src/ 这种相对写法（Composer 不认）。
这个命令还能暴露文件级问题：比如某 PHP 文件含 BOM、语法错误、或用了 短标签但未开启 short_open_tag，它会在报错前卡在那个文件上，直接告诉你“Parse error on line X”。这时候不用全局排查，就盯住最后成功扫描的路径，再查那个目录下的可疑文件（如 .php.bak、config.example.php）。
检查 vendor/composer/autoload_psr4.php 和 autoload_classmap.php 里有没有你的类
这些文件是 Composer 自动加载的最终执行依据，不是缓存，是真相。打开 vendor/composer/autoload_psr4.php，搜索你的命名空间前缀（如 "App\"），确认它映射到的物理路径是否是你预期的绝对路径（比如 /var/www/project/src/）。再打开 autoload_classmap.php，搜你调用的类名（如 "App\Controllers\HomeController"），看对应路径是否存在、拼写是否完全一致（注意大小写、斜杠方向、有无多余空格）。
如果类名在 classmap 里找不到，但 PSR-4 映射又对得上，说明问题出在路径推导环节：比如配置了 "MyApp\": "app/"，但类 MyAppHttpControllersHomeController 实际放在 app/MyApp/Http/Controllers/HomeController.php —— 多了一层 MyApp/，PSR-4 会截掉前缀后去拼 Http/Controllers/HomeController.php，结果去找 app/Http/Controllers/HomeController.php，自然失败。
确认 vendor/autoload.php 被引入，且路径不依赖当前工作目录
很多“Class not found”其实和 Composer 没关系，只是入口脚本压根没加载自动加载器。检查你的 index.php 或 CLI 脚本顶部，必须有且仅有这一行有效引入：require __DIR__ . '/vendor/autoload.php';。这里的关键是 __DIR__，不是 ../vendor/autoload.php 或 ./vendor/autoload.php —— 前者在 Web 环境下容易因 DOCUMENT_ROOT 和脚本位置不一致而失效，后者在 CLI 下一旦从其他目录执行就会挂。
加一行验证更保险：if (!file_exists(__DIR__ . '/vendor/autoload.php')) { die('autoload.php not found at ' . __DIR__ . '/vendor/autoload.php'); }。尤其在 Docker 或部署脚本里，vendor/ 目录可能被挂载到别处，或构建阶段漏掉了 composer install，这个判断能立刻暴露环境问题。
警惕 classmap 和 PSR-4 混用时的覆盖逻辑
如果你在 composer.json 里同时配了 psr-4 和 classmap，它们不是并列关系，而是有优先级：classmap 查表是第一层，命中就直接返回路径，不再走 PSR-4 推导。这意味着，哪怕你的类名符合 PSR-4 规则，只要它被 classmap 收录（比如你把整个 lib/ 加进了 classmap），那它的加载行为就完全由 classmap 文件决定——删了 lib/Utils.php 却忘了 composer dump-autoload，classmap 里还留着旧路径，运行时就会 require 一个不存在的文件，报错却是 failed to open stream，而不是 Class not found。
混用时务必注意：classmap 路径必须写相对路径（如 "lib/"），不能写 "./lib/"；新增类后必须重跑 composer dump-autoload（-o 模式下更要重跑，否则 classmap 不更新）；用 exclude-from-classmap 显式排除干扰文件，比靠运气强。
真正卡住人的往往不是配置本身，而是路径、命名、大小写、执行上下文这四者的微小错位。每次改完 composer.json 或移动类文件，别急着跑代码，先 dump-autoload -v 看输出，再瞄一眼生成的 autoload_psr4.php —— 这两步省下的调试时间，够你喝三杯咖啡。
