Composer自动加载失败时应先运行composer dump-autoload -v排查，它会详细输出扫描路径、类匹配及映射状态；常见原因包括autoload.json缓存未更新、composer.json配置错误（如PSR-4末尾缺双反斜杠）、路径与命名空间不匹配等。
自动加载失败时先看 composer dump-autoload -v 输出
Composer 自动加载出问题，90% 的情况不是代码写错，而是 autoloader 没生成或没更新。直接运行 composer dump-autoload -v（加 -v 是关键），它会逐行打印扫描路径、匹配到的类、跳过的文件，以及 classmap/PSR-4 映射是否生效。
常见错误现象：Class XXX not found 但文件明明存在；composer install 没报错，但运行时报错——这说明 autoload.json 已缓存旧状态。
- 必须删掉
vendor/composer/autoload_*.php和vendor/composer/autoload_classmap.php再重跑dump-autoload -v，否则可能读缓存 - 如果输出里压根没出现你的命名空间或路径，说明
composer.json里的autoload配置没被识别（比如缩进错误、逗号遗漏） -
psr-4条目末尾必须带\（如"App\": "src/"），少一个反斜杠会导致整个映射失效，但dump-autoload不报错
classmap 和 psr-4 混用时谁优先？
两者不冲突，但行为完全不同：psr-4 是“按命名空间前缀动态推导路径”，classmap 是“把所有类名硬编码到一张表里”。当一个类同时满足两种规则，classmap 会覆盖 psr-4 —— 因为 autoload 逻辑里 classmap 查表是第一层判断。
使用场景：你给第三方库打补丁，加了几个工具类放 lib/Utils.php，又不想改命名空间，就用 classmap 手动注册；但主业务代码必须用 psr-4，否则 IDE 跳转和静态分析会失效。
- classmap 路径写相对路径（如
"lib/"），不能写./lib/或绝对路径 - 执行
composer dump-autoload -o后，classmap 会生成完整列表；但-o模式下 psr-4 映射仍保留，只是 classmap 查不到时才 fallback - 如果你在
psr-4下写了"App\": "src/"，又在classmap里加了"src/Helper.php"，那new Helper()会走 classmap，而new AppHelper()仍走 psr-4 —— 类名不匹配，不会混
PSR-4 映射失败的三个典型路径陷阱
PSR-4 不是简单拼路径，它会截掉命名空间前缀再拼剩余部分。很多人卡在“文件存在却找不到”，本质是路径推导错了。
假设配置是 "MyApp\": "app/"，那么 MyAppHttpControllersHomeController 应该放在 app/Http/Controllers/HomeController.php —— 注意不是 app/MyApp/Http/...。
- 路径中不能有大写字母开头的目录名对应小写命名空间（如
"myapp\": "App/"+new myappFoo()，但App/目录实际是小写，Windows 可能侥幸通过，Linux 直接失败） -
composer.json里写"MyApp\": "app/"，但文件实际在app/Http/Controller/HomeController.php，而类声明是class MyAppHttpControllersHomeController—— 这没问题；但如果类声明是class MyAppHttpControllerHomeController（少一个s），就会映射到app/Http/Controller/HomeController.php，但文件名是Controllers，就失败 - IDE 自动生成类时可能把命名空间写成
MyAppHttpControllers，但目录结构是app/Http/controllers/（小写controllers），Linux 下直接 404
验证 autoload 是否生效的最快方式
别急着跑整个应用，用 composer show --platform 看 PHP 环境，再用最简脚本直连 autoload：
<?php
require 'vendor/autoload.php';
var_dump(class_exists('MyAppHttpControllersHomeController'));
?>
如果返回 false，但文件路径和命名空间都确认无误，问题一定出在 autoload 生成环节，而不是运行时环境。
- 确保脚本在项目根目录执行，否则
vendor/autoload.php路径会错 - 不要用
php -a交互模式测试 —— 它不触发 Composer 的 autoloader 初始化逻辑 - 如果
class_exists返回true，但实际 new 实例时报Class not found，大概率是类里用了__autoload或spl_autoload_register冲突，得查自己代码
