ThinkPHP自动加载找不到类的根本原因是类名、命名空间、文件路径三者未严格对齐；需确保PSR-4映射一致、执行composer dump-autoload -o、检查大小写与文件后缀，并清除runtime缓存。
ThinkPHP 自动加载找不到类，绝大多数情况不是框架坏了，而是类名、命名空间、文件路径三者没对齐——尤其在手动引入第三方类、迁移旧代码或自定义命令行类时特别容易出问题。
类名与文件路径不匹配导致 ClassNotFoundException
ThinkPHP 6+ 使用 PSR-4 自动加载，要求目录结构严格对应命名空间。比如声明了 namespace app\command;，那这个类就必须放在 app/command/YourCommand.php；如果错放到 app/command/tools/YourCommand.php，即使命名空间写成 app\command\tools，但没在 composer.json 中配置该子命名空间映射，就会报错。
- 检查
composer.json的"autoload": {"psr-4": {...}}是否包含你新增的命名空间前缀和路径 - 确认文件后缀是
.php（不是.php~或隐藏备份文件） - Windows 下注意大小写不敏感但 Linux 敏感，开发时就按 Linux 规则写：类名
SendEmail→ 文件名必须是SendEmail.php，不能是sendemail.php
think 命令找不到自定义指令类
运行 php think list 看不到你的命令，或执行时报 Class not found，常见原因是：
- 类没继承
think\console\Command - 没在
app/command/下（或你自定义的命令目录），且未在config/console.php的'commands'中显式注册 - 类中缺少
configure()方法（TP6.1+ 强制要求，哪怕只写$this->setName('your:cmd');） - 运行命令前忘了执行
composer dump-autoload（尤其是修改了composer.json或新增了非标准路径）
使用 Loader::addNamespace() 手动注册时踩的坑
某些场景下需要临时加一个非 PSR-4 路径（比如 vendor 外的老模块），用 think\facade\Loader::addNamespace() 是可行的，但要注意：
立即学习“PHP免费学习笔记（深入）”；
- 必须在自动加载器初始化前调用——最佳位置是
public/index.php中require __DIR__.'/../vendor/autoload.php';之后、(new App())->run()->send();之前 - 第二个参数是**绝对路径**，别传相对路径或带
./，推荐用__DIR__.'/../old_module/' - 它只是补充规则，不会覆盖 PSR-4；如果命名空间已存在映射，新注册的不会生效
调试技巧：快速定位加载失败点
别靠猜。直接在 vendor/composer/ClassLoader.php 的 findFile() 方法里加一句 var_dump($class, $file); die;，就能看到框架到底想找哪个类、去哪些路径搜了。更轻量的方式是：
- 运行
composer show --platform确认当前加载器状态 - 在报错页面点击「Trace」看堆栈，找到触发
loadClass的那一行，反推是谁在 new 或 use 一个不存在的类 - 临时在
app/common.php加一行echo 'Loading: ' . $class . PHP_EOL;（需配合自定义加载器或重写Loader）
最常被忽略的是：改完命名空间或移动文件后，忘了删 runtime/container 和 runtime/cache 里的缓存——这些缓存会固化旧的类映射，导致改了也白改。
