“Class not found”错误源于自动加载失败，需依次检查命名空间与路径一致性、Composer自动加载配置、文件存在性与权限、框架引导时机及调试模式以定位真实异常。
如果您在使用PHP框架时遇到“Class not found”错误，说明PHP运行时无法定位并加载所引用的类文件。该问题通常由自动加载机制失效、命名空间不匹配、文件路径错误或类名拼写偏差引起。以下是排查与解决此错误的具体步骤：
一、检查命名空间与类名是否严格一致
PHP自动加载依赖于PSR-4或PSR-0规范，要求类文件的物理路径必须与命名空间层级及类名完全对应。任意一级大小写不一致或拼写错误均会导致加载失败。
1、打开报错提示中指定的类名（例如 AppControllersUserController），确认其声明的命名空间是否为 namespace AppControllers;
2、检查该类所在文件路径是否为 app/Controllers/UserController.php（注意大小写，Linux系统区分大小写）。
立即学习“PHP免费学习笔记（深入）”；
3、核对文件中类定义是否为 class UserController，而非 class usercontroller 或 class UserController1。
二、验证自动加载配置是否生效
Composer生成的自动加载映射未更新或配置错误，将导致类无法被正确注册。需确保 autoload 部分已包含对应命名空间，并执行重生成操作。
1、打开项目根目录下的 composer.json 文件，检查 "autoload" 段中是否包含类似以下配置：
"psr-4": { "App\": "app/" }
2、确认该配置中命名空间末尾反斜杠 和路径结尾斜杠 / 均存在且无多余空格。
3、在终端中进入项目根目录，执行命令：composer dump-autoload -o 强制重建优化后的自动加载映射。
三、确认类文件实际存在且可被读取
即使路径与命名空间匹配，若文件被误删、权限不足或位于.gitignore中被忽略，也会触发类找不到错误。需逐层验证文件系统状态。
1、根据报错类名推导完整路径（如 AppModelsPost → app/Models/Post.php），使用 ls -l app/Models/Post.php 检查文件是否存在。
2、执行 php -l app/Models/Post.php 验证PHP语法是否合法，排除因语法错误导致解析中断而无法注册类的情况。
3、检查文件权限是否允许Web服务器用户（如 www-data 或 nginx）读取，必要时执行：chmod 644 app/Models/Post.php。
四、排查框架引导流程中的类引用时机
某些框架（如Laravel、ThinkPHP）在服务提供者注册或中间件加载阶段提前调用未初始化的类，若该类依赖尚未注册的绑定或配置未加载，可能抛出伪装成“Class not found”的异常。
1、查看报错堆栈中最顶层调用位置，确认是否发生在 config/app.php、app/Providers/AppServiceProvider.php 或路由闭包中。
2、若类在服务提供者 register() 方法中被实例化，应移至 boot() 方法内，避免依赖未就绪。
3、检查是否在配置文件中错误地将类名作为字符串直接赋值给非延迟解析字段（如 'cache' => AppCacheRedisCache::class 应确保该类已声明且路径可达）。
五、启用调试模式并捕获真实错误源
部分框架会静默吞掉原始异常，仅显示通用的“Class not found”。需开启底层错误报告，定位是否为其他异常被错误掩盖。
1、临时在入口文件（如 public/index.php）顶部添加：error_reporting(E_ALL); ini_set('display_errors', '1');
2、在框架配置中启用调试模式，例如 Laravel 设置 APP_DEBUG=true，ThinkPHP 设置 app_debug = true。
3、刷新页面后查看完整异常堆栈，确认是否为 Fatal error: Uncaught Error: Class "XXX" not found 还是嵌套在 ReflectionException 或 BindingResolutionException 中。
