ThinkPHP自动加载类名规范_类名规范自动加载【教程】

ThinkPHP 6+ 报“找不到类”，十有八九不是框架坏了，也不是自动加载没注册，而是类名、文件名、命名空间这三者之间的大小写或拼写没对齐——PSR-4 映射根本没匹配上。下面把这几个最容易踩的坑拆开讲清楚。

类名和文件名必须严格驼峰且首字母大写

PSR-4 规则很死：类名叫什么，文件名就得叫什么，大小写一个不能差，而且必须带 .php 后缀。别用什么 .class.php 或者全小写的文件名，那都是给自己挖坑。

• User 类 → 文件必须叫 User.php，写 user.php、user.class.php、UserClass.php 都不行
• UserLoginService 类 → 文件就得是 UserLoginService.php，中间别加下划线
• 注意：Linux/macOS 对大小写敏感。你在 Windows 上开发即使能跑，上线到 Linux 必报 Class "app\service\User" not found，到那时候再排查就晚了

命名空间必须与物理路径逐段对应

命名空间里的反斜杠 \ 对应目录分隔符，而且全部小写。比如 app\controller\Index 就意味着文件在 app/controller/Index.php，一个萝卜一个坑。

• 控制器类必须声明 namespace app\controller;，写成 App\Controller（首字母大写）或 app/controller（缺反斜杠）都不认
• 自定义工具类放 app/utils/ArrHelper.php，命名空间就得是 app\utils，末尾的反斜杠在 composer.json 配置里必须保留
• 路径里出现大写字母（如 App/Controller）或下划线（如 app_v2）会直接中断映射，Composer 根本不去扫那个目录

composer.json 的 psr-4 配置必须手动补全

ThinkPHP 6 默认没把 app/ 目录注册进 Composer 自动加载。你写了新类却不配，Composer 根本不知道还要去扫那个目录。

• 编辑项目根目录的 composer.json，在 "autoload": {"psr-4": {...}} 里加一行："app\\": "app/"（注意双反斜杠转义）
• 改完立刻执行 composer dump-autoload -o。不加 -o 有时开发环境不生效；但调试阶段建议先不加，避免 classmap 缓存把路径问题掩盖掉
• 如果类放在 common/ 或 support/ 这类非标准目录，一样要单独加 psr-4 规则，别指望 ThinkPHP 能“自动识别”

vendor 第三方包加载失败不是 TP 的锅

报 Class "Overtrue\Pinyin\Pinyin" not found，大概率是入口没引 vendor/autoload.php，或者包本身换了命名空间。

• 检查 public/index.php 是否有 require __DIR__.'/../vendor/autoload.php';（TP6 默认有，但有人删过入口文件后会漏掉这一行）
• 运行 composer show overtrue/pinyin 看实际安装版本。v5+ 已经把主类从 Pinyin 改成 Generator，命名空间也变成 Overtrue\Pinyin\Generator
• 某些老包用 classmap 加载，必须 composer dump-autoload -o 才生效，光 require 不行

还有一个最容易被忽略的细节：PSR-4 映射只看命名空间前缀是否匹配，一旦匹配成功，就不再查其他规则。所以如果你在 composer.json 里同时写了 "app\\": "app/" 和 "App\\": "app/"，后者永远无效——因为 app\controller\User 会被前者吃掉，根本轮不到 App。记住这一点，能省掉不少排查时间。