“Class not found” 根本原因是 autoload 映射未生效，需严格核对 composer.json 的 PSR-4 配置、路径与命名空间层级一致性、vendor/autoload.php 是否正确引入、dump-autoload 是否强制优化及 OPcache 等缓存是否清理。
“Class not found” 不是 Composer 没联网，而是 autoload 映射没生效——哪怕你本地改了类、加了文件、重写了命名空间，只要 vendor/autoload.php 里没对应条目，PHP 就真不认识它。
检查 composer.json 的 autoload 配置是否匹配路径和命名空间
PSR-4 映射不是“大概对就行”，而是「命名空间前缀 + 目录路径」必须严丝合缝。比如配置 "App\": "src/"，那 AppControllersHomeController 就必须落在 src/Controllers/HomeController.php；如果类文件直接放在 src/HomeController.php，或者目录写成 controllers/（小写），就会断掉。
- 确认类文件所在路径与命名空间层级完全一致（
AppServicesFooService→src/Services/FooService.php） - 检查 composer.json 中路径末尾有没有多余斜杠（
"src"✅，"src/"❌ 在某些旧版本会出问题） - 用
composer dump-autoload -v查看输出里是否扫描到了你的类路径——没出现就说明配置根本没命中 - 如果用了
classmap，注意它不支持自动发现：新增文件后必须显式加-a参数重扫：composer dump-autoload -a
确认 vendor/autoload.php 是否被正确引入且无前置输出
入口脚本（如 index.php 或测试文件）第一行就必须是 require，不能有空格、BOM、echo、var_dump 甚至注释前的不可见字符。否则 PHP 会因“headers already sent”类错误导致 autoloader 初始化失败，但报错却显示为 “Class not found”。
- 入口文件顶部第一行只能是：
require __DIR__ . '/vendor/autoload.php';（用__DIR__，别用getcwd()） - CLI 下执行时，确保当前工作目录不影响路径解析——
php /path/to/script.php比cd /path && php script.php更可靠 - 在 Web 环境中，检查是否有其他框架或中间件提前输出了内容（比如日志、调试工具、BOM）
验证 dump-autoload 是否真正更新了映射文件
运行 composer dump-autoload 不等于映射就刷新了。默认命令只更新 PSR-4 规则，不清理旧缓存、不处理 autoload-dev、也不生成优化版映射。离线环境尤其容易卡在这一步。
- 强制覆盖并优化：用
composer dump-autoload -o（生成autoload_static.php，跳过运行时查找） - 开发依赖也要加载？加
--dev：composer dump-autoload -o --dev - 检查
vendor/composer/autoload_psr4.php里有没有你期望的命名空间条目——没有就说明配置或路径仍有偏差 - Linux 离线机上务必检查大小写：文件叫
Userservice.php，但类声明是class UserService，系统直接找不到
排查 opcode 缓存和 classmap 权威模式干扰
部署后类突然找不到，十有八九是 OPcache 还在用旧的字节码，或者 classmap 开了 --classmap-authoritative 却没同步新文件。
- OPcache 必须重置：
php -r "opcache_reset();"（前提是opcache.enable=1且opcache.revalidate_freq=0） - 若用了
--classmap-authoritative，新增类文件后不跑composer dump-autoload -a，运行时直接 fatal error - 检查
vendor/composer/autoload_static.php和autoload_classmap.php是否存在、是否最新——这两个文件是 classmap 和优化加载的核心依据 - 某些 CI/CD 流程中误加了
--no-scripts，导致dump-autoload根本没触发，得手动补上
最易忽略的是：你以为改了配置、跑了命令、清了缓存，但 vendor/autoload.php 文件本身可能被手动修改过，或被某些 IDE 插件/部署脚本覆盖。直接删掉整个 vendor/ 目录再 composer install --no-dev -o，反而比修修补补更快定位问题根源。
