Class not found是自动加载失败，需检查命名空间与目录结构是否严格匹配、执行composer dump-autoload刷新映射、确认spl_autoload_register注册生效、排除files误用干扰、必要时启用classmap兜底。
如果您在ThinkPHP项目中定义了新类，但运行时提示“Class not found”，则很可能是Composer自动加载机制未正确识别该类的路径与命名空间映射关系。以下是解决此问题的步骤：
一、确认PSR-4命名空间与目录结构严格匹配
ThinkPHP默认依赖Composer的PSR-4自动加载规范，该规范要求命名空间前缀必须与物理目录路径一一对应，且大小写完全一致。任何偏差都会导致类文件无法被定位。
1、检查composer.json中autoload段的PSR-4配置，例如："App\": "app/"。
2、确认类文件实际存放路径是否为app/目录下，且子目录层级与命名空间剩余部分完全一致，如AppControllerUserController必须位于app/Controller/UserController.php。
立即学习“PHP免费学习笔记（深入）”；
3、验证类文件名是否与类名完全相同（含大小写），例如class UserController对应文件必须命名为UserController.php，不可为usercontroller.php或user_controller.php。
4、确保app/路径末尾含有斜杠，不可写作"App\": "app"或"App\": "/app/"。
二、执行dump-autoload强制刷新映射表
Composer不会实时监听文件系统变更，修改类位置、命名空间或composer.json中的autoload配置后，必须显式重建自动加载映射，否则vendor/autoload_psr4.php仍保留旧路径记录。
1、在项目根目录（composer.json所在位置）执行命令：composer dump-autoload。
2、若需生成优化版classmap（适用于生产环境），追加-o参数：composer dump-autoload -o。
3、执行后检查vendor/composer/autoload_psr4.php内容，确认新命名空间条目已写入且路径正确。
三、验证spl_autoload_register注册链是否生效
ThinkPHP底层通过spl_autoload_register()将Composer生成的加载器注入PHP自动加载队列。若该注册过程被覆盖或中断，PSR-4规则将不触发。
1、打开vendor/autoload.php，确认其末尾存在类似require_once __DIR__ . '/autoload_real.php';并调用ComposerAutoloaderInit初始化逻辑。
2、检查项目入口文件（如public/index.php）是否确实引入了该文件：require __DIR__.'/../vendor/autoload.php';。
3、在任意可执行脚本中插入调试代码：var_dump(spl_autoload_functions());，确认Composer的ClassLoader::loadClass方法存在于返回数组中。
四、排除files方式误用干扰
若在composer.json中配置了"files"字段，该机制会在引入autoload.php时无条件一次性加载指定PHP文件，不参与按需类加载流程；若错误地将类文件列入files，会导致重复定义错误或掩盖PSR-4失效问题。
1、检查composer.json中"autoload": {"files": [...]}是否包含任何以.php结尾且内含class声明的文件路径。
2、若存在，立即将其移出files，改用PSR-4或classmap方式管理。
3、修改后必须再次执行：composer dump-autoload，否则变更不生效。
五、启用classmap作为兜底方案
当项目中存在无命名空间的老代码、第三方库或路径结构混乱的类时，PSR-4无法覆盖全部场景，此时classmap提供O(1)查找能力，可作为补充加载策略。
1、在composer.json中添加classmap配置项，例如："classmap": ["library/", "old_code/"]。
2、执行composer dump-autoload，Composer将扫描指定目录下所有PHP文件并生成autoload_classmap.php。
3、确认vendor/composer/autoload_classmap.php中已包含目标类的完整路径映射，格式为'ClassName' => $baseDir . '/library/ClassName.php'。
