第一反应是运行composer dump-autoload -v查看实时扫描路径，确认命名空间是否出现、路径是否匹配、文件是否被跳过或解析失败，并核对autoload_psr4.php中映射是否准确。
看 composer dump-autoload -v 的实时扫描路径
自动加载失败，第一反应不该是删缓存或重装依赖，而是让 Composer 自己“说话”。composer dump-autoload -v 会逐行输出它扫描了哪些目录、匹配到哪些类、跳过了哪些文件、为什么跳过——这是最接近真相的日志。
常见误判点：
- 终端输出里压根没出现你的命名空间（比如
"App": "app/"），说明composer.json的 autoload 段有语法错误（逗号遗漏、缩进错位、引号不闭合） - 路径显示为
/path/to/project/app/，但你实际把类放在src/下——配置和物理路径对不上，dump 不会报错，只会安静跳过 - 看到
Skipping file xxx.php: syntax error，说明该文件 PHP 语法错误，Composer 直接丢弃，不会映射
查 vendor/composer/autoload_psr4.php 里的真实映射
别信配置，看生成结果。vendor/composer/autoload_psr4.php 是 PSR-4 映射的最终快照，里面每一行都对应一个命名空间 → 目录的绝对路径映射。打开它，搜索你的命名空间前缀（如 "App\"），确认右边路径是否指向你预期的目录（比如 __DIR__ . '/../app/'），而不是 __DIR__ . '/../src/' 或其他拼错路径。
关键细节：
- 末尾反斜杠不能少：
"App\": "app/"✅，"App": "app/"❌（后者会导致类名解析多截一层） - 路径必须是相对 vendor 的，且以
/结尾；写成"app"而非"app/"，映射会失效但不报错 - Windows 下路径分隔符是
\，但 Composer 生成时自动处理，不用手动改
确认类文件是否真被 autoload 规则覆盖
很多“类找不到”本质是规则根本没管到那个文件。Composer 只加载 composer.json 中 autoload 和 autoload-dev 明确声明的路径下的类。如果你把新类扔在 lib/、helpers/ 或 config/ 这类非标准目录，它永远不会被 PSR-4 扫到。
应对方式：
- 要么把目录加进
psr-4（如"Lib\": "lib/"），然后composer dump-autoload - 要么用
"files"类型直接 require 单个文件（如"files": ["lib/helpers.php"]） - 检查是否误用了
autoload-dev：CI 构建时加了--no-dev，那里面配的"Tests\": "tests/"就不会生效
排除 OPcache、IDE 缓存和 runtime 干扰
命令行跑通但 Web 请求仍报错？大概率不是 Composer 问题，而是环境层缓存没清干净。
必须同步清理的几处：
-
runtime/下全部内容（ThinkPHP 等框架会缓存类映射、容器绑定等，仅清cache/不够，container/和log/也得清） - OPcache：CLI 和 Web SAPI 的缓存隔离，
php -r "opcache_reset();"只清 CLI；Apache 需重启 httpd，Nginx+PHP-FPM 需sudo systemctl reload php-fpm或调用opcache_get_status()页面触发 - IDE 符号缓存：VS Code 关闭重开项目，PHPStorm 执行
File → Reload project或Index → Rebuild
最常被忽略的是：autoload_psr4.php 被 OPcache 缓存后，你改了 composer.json 并 dump-autoload，PHP 实际仍在执行旧字节码。这时候看文件内容已更新，但行为没变——不是配置问题，是缓存没清透。
