class not found 错误极大概率源于 composer 自动加载失效，需依次验证 autoload.php 引入、重建 autoload 映射、清理缓存、检查 psr-4 命名空间格式（末尾双反斜杠）、区分 classmap 与 psr-4 优先级。
如果您在运行 ThinkPHP 项目时遇到 Class not found 错误，但确认类文件真实存在、路径正确、语法无误，则问题极大概率出在 Composer 自动加载机制失效。以下是排查此类错误的具体操作步骤：
一、验证 vendor/autoload.php 是否被正确引入
ThinkPHP 启动的第一步即加载 Composer 自动生成的自动加载器，若该文件未被引入、路径错误、权限不足或 PHP 版本不兼容，将直接导致白屏或致命错误，框架甚至无法进入初始化流程。
1、打开 public/index.php 文件，检查首行是否为 require __DIR__ . '/../vendor/autoload.php';
2、在命令行中执行 ls -l vendor/autoload.php，确认文件存在且权限至少为 -rw-r--r--
3、在浏览器中直接访问 public/index.php，若返回 500 或空白页，立即检查 Web 服务器错误日志中是否含 “failed to open stream: No such file” 类提示
二、强制重建自动加载映射并启用详细输出
composer dump-autoload 命令用于重新生成 vendor/composer/ 下的 autoload_psr4.php、autoload_classmap.php 等映射文件；加 -v 参数可输出扫描过程细节，是定位路径与命名空间错配的核心手段。
1、在项目根目录下执行 composer dump-autoload -v
2、观察输出中是否出现您自定义命名空间（如 appcontroller）对应的扫描路径和匹配类名
3、若输出中完全未列出您的命名空间前缀或目标文件路径，说明 composer.json 中 autoload 配置未被识别，需检查 JSON 格式（逗号缺失、缩进错误、键名拼写）
三、清理 autoload 缓存文件后重生成
Composer 在 vendor/composer/ 目录下缓存了 autoload_*.php 文件，若此前生成失败或残留旧状态，即使修改了 composer.json 并执行 dump-autoload，仍可能读取损坏缓存，导致映射未更新。
1、执行 rm -f vendor/composer/autoload_*.php
2、再次运行 composer dump-autoload -v
3、打开 vendor/composer/autoload_psr4.php，搜索您的命名空间（如 'app\controller\'），确认其值为包含 controller 子目录的数组路径
四、检查 PSR-4 命名空间配置格式是否合规
PSR-4 映射要求命名空间前缀必须以反斜杠结尾，在 composer.json 中需表示为双反斜杠（JSON 字符串转义），例如 "app\controller\"；漏写末尾反斜杠将导致整个命名空间映射失效，且 dump-autoload 不报错。
1、打开 composer.json，定位 autoload.ps r-4 字段，检查 key 是否含结尾反斜杠，如 "app\controller\": "app/controller/" ✅，而非 "app\controller": "app/controller/" ❌
2、确认该命名空间对应路径下所有 PHP 文件的命名空间声明与目录结构严格一致，例如 app/controller/IndexController.php 内必须声明 namespace app\controller;
3、在 Linux 服务器上验证文件名大小写：执行 ls app/controller/ | grep -i indexcontroller，确保实际文件名为 IndexController.php 而非 indexcontroller.php
五、区分 classmap 与 PSR-4 的优先级与行为差异
当一个类同时满足 PSR-4 和 classmap 规则时，classmap 映射会优先生效；若 classmap 路径配置错误或未覆盖目标类，而 PSR-4 又因前缀或路径问题未命中，则类将彻底无法加载。
1、检查 composer.json 中 autoload.classmap 是否包含冗余或冲突路径，例如同时配置了 "app/" 和 "app/controller/"
2、若使用 classmap 手动注册工具类（如 lib/Helper.php），确保路径为相对路径且含 .php 后缀："lib/Helper.php" ✅，而非 "lib/Helper" 或 "./lib/Helper.php"
3、执行 composer dump-autoload -o 后，打开 vendor/composer/autoload_classmap.php，确认 Helper 类名是否已出现在键名中
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
