Class not found 是自动加载失败，非文件缺失；根本原因是命名空间、目录结构、composer autoload 配置或 runtime/classmap 缓存不匹配导致框架无法定位类。
Class not found 是自动加载失败，不是文件没写
ThinkPHP 报 Class not found，绝大多数情况不是你漏写了类，而是自动加载机制压根没找到它。框架不会主动扫描所有 PHP 文件，它依赖命名空间、目录结构和 composer.json 中的 autoload 配置来决定“去哪找”。一旦路径或命名空间对不上，哪怕文件真实存在，也会报这个错。
常见错误现象：Class app\controller\IndexController not found，但你确认 app/controller/IndexController.php 存在且语法正确；或者改了命名空间后刷新就崩，但 IDE 没报错。
- 检查类文件的命名空间是否与目录结构严格匹配（如
app\controller\IndexController必须放在app/controller/IndexController.php） - 确认文件名大小写完全一致（Linux 服务器区分大小写，
indexcontroller.php≠IndexController.php） - 如果类在
extend/或自定义目录下，必须在composer.json的"autoload": {"psr-4": {...}}中显式声明映射
composer dump-autoload 不是万能的，但不执行一定不行
composer dump-autoload 的作用是重新生成 vendor/composer/autoload_psr4.php 等映射文件。如果你新增了 PSR-4 映射、改了目录、或用了 --optimize 模式，不运行这句命令，Composer 就不知道新类在哪。
使用场景：添加新模块、迁移旧项目、CI/CD 构建后部署到服务器时遗漏该步骤。
立即学习“PHP免费学习笔记（深入）”；
- 开发中改了
composer.json后，必须运行composer dump-autoload（加-o可选，但非必需） - 线上环境如果用
composer install --no-dev --optimize-autoloader，本地改完记得同步更新 autoload 映射 - 不要依赖“重启 PHP-FPM”或“清空 runtime/cache”来解决 autoload 问题——它们不重建类路径索引
ThinkPHP 自带的 Loader::addNamespace() 容易被忽略
除了 Composer 的 autoload，ThinkPHP 还支持运行时手动注册命名空间，通过 Loader::addNamespace()。这个机制常用于插件、多应用或动态扩展场景，但它不会被 Composer 扫描，也不会写入 autoload 文件。
性能影响：每次请求都走一次映射查找，不如 Composer 的静态映射快；兼容性上，5.1+ 支持，但 6.x 已移除该方法，改用容器绑定或事件驱动方式。
- 检查
app/common.php或thinkphp/base.php是否调用了Loader::addNamespace('addon', '../addon/')类似代码 - 确认传入的路径是相对入口文件的，不是相对当前文件——容易写成
__DIR__.'/../addon'导致路径错位 - ThinkPHP 6.x 不再有
Loader类，这类逻辑需迁移到AppService或服务提供者中
runtime/cache 下的 classmap 文件可能过期
ThinkPHP 在开启类库映射缓存（'class_map' => true）时，会把常用类路径写进 runtime/cache/classmap.php。这个文件不会自动更新，一旦你移动、重命名或删除类文件，旧缓存就会导致“找不到类”——即使 autoload 配置完全正确。
最容易踩的坑：开发中频繁增删控制器/模型，又习惯性只清 log 和 temp，忘了 classmap.php。
- 临时排查：直接删掉
runtime/cache/classmap.php，看是否恢复 - 长期方案：开发环境关闭
'class_map'（设为false），上线前再开启并配合php think optimize:autoload - 注意
php think optimize:autoload生成的是 Composer 风格的 classmap，和 runtime 下的 classmap 不是一回事，别混淆
真正卡住人的地方往往不是“怎么写类”，而是“框架在哪个环节放弃了寻找”。路径、命名空间、autoload 配置、缓存文件，四者只要有一环脱节，Class not found 就会准时出现——而且错误信息从不告诉你断在哪一环。
