PHP Class not found类找不到,自动加载失败排查思路-php教程-PHP中文网

composer autoload配置没生效最常见原因是未执行composer dump-autoload，或psr-4命名空间与文件路径不匹配（如namespace appcontrollers声明但文件在src/http/controllers/），需严格校验大小写、斜杠结尾、相对路径及vendor/autoload.php引入方式。

php class not found类找不到,自动加载失败排查思路

Composer autoload 配置没生效

最常见的情况是 composer.json 里写了 "autoload" 但没运行 composer dump-autoload，或者改了命名空间/路径后忘记重新生成自动加载映射。

检查 vendor/autoload.php 是否被正确引入（通常在入口文件第一行）
确认 composer.json 中的 psr-4 或 classmap 路径是否拼写正确，末尾有无多余斜杠（如 "App\": "src/App/" 不能写成 "App\": "src/App"）
运行 composer dump-autoload -o 强制重生成优化版自动加载文件（尤其上线后）
如果用的是 classmap，确保类文件名和类名严格一致（包括大小写），且该目录下没有遗漏 .php 后缀文件

命名空间与文件路径不匹配

PSR-4 自动加载要求命名空间前缀 + 子命名空间必须能一对一映射到文件系统路径，稍有偏差就报 Class not found。

例如声明了 namespace AppControllers;，但文件实际放在 src/Http/Controllers/HomeController.php，而 composer.json 只配置了 "App\": "src/" —— 这时会去查 src/Controllers/HomeController.php，自然找不到
Windows 下不区分大小写，Linux/macOS 区分：类名 MyClass 对应文件 MyClass.php，若写成 myclass.php，在 Linux 上必报错
使用 composer show --path 查看某个命名空间实际映射到哪个路径，快速验证是否符合预期

手动 require/require_once 干扰自动加载

有些老项目混用 require 和 Composer 自动加载，容易导致类重复定义或加载顺序错乱，最终表现为“有时能找到、有时找不到”。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

检查是否有类似 require 'app/Models/User.php'; 的硬编码路径 —— 它绕过了 Composer，也破坏了 PSR-4 规则
如果必须手动加载（比如引导阶段），优先用 include_once 避免重复包含；更稳妥的做法是把这类文件加入 composer.json 的 files 数组，由 Composer 统一管理
运行 php -d display_errors=1 -f index.php 看完整错误堆栈，确认报错位置是自动加载失败，还是后续某处 new 实例时报的错（后者可能是前面已加载但类定义有语法错误）

OPcache 缓存了旧的自动加载映射

开发中改了 composer.json 或移动了类文件，但 OPcache 没刷新，仍按旧规则找类，就会持续报错。

临时解决：重启 PHP-FPM 或 Apache/Nginx；命令行下可加 -d opcache.enable=0 测试是否为缓存问题
长期方案：开发环境禁用 OPcache（opcache.enable=0），或设置 opcache.validate_timestamps=1 并调小 opcache.revalidate_freq（如设为 2）
注意：Docker 环境中若挂载了 vendor 目录，宿主机修改 composer.json 不一定触发容器内 OPcache 更新，需进容器手动 composer dump-autoload

真正卡住的地方往往不是语法或路径本身，而是多个机制叠加后的隐性冲突：比如你改了命名空间、跑了 dump-autoload、却忘了清 OPcache，又恰好在 CI 环境里用了缓存的 vendor 目录——这时候单看任一环节都没问题，合起来就找不到类。