如何遵循ThinkPHP类名规范实现自动加载？

本文共计886个文字，预计阅读时间需要4分钟。

ThinkPHP6找不到类，90%的情况是类名、文件名、命名空间三者大小写不一致，不是框架问题，也不是autoload没注册——是PSR-4映射根基本没有匹配上。

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

PSR-4 要求类名与文件名完全一致（含大小写），且以 .php 结尾，不接受 .class.php 或小写文件名。

• User 类 → 文件必须叫 User.php，不能是 user.php、user.class.php 或 UserClass.php
• UserLoginService 类 → 文件必须叫 UserLoginService.php，中间不能加下划线
• Linux/macOS 系统对大小写敏感，Windows 开发时即使能跑，切到生产环境必报 Class "appserviceUser" not found

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

命名空间里的反斜杠 必须和目录分隔符一一对应，且全部小写；appcontrollerIndex 就意味着文件在 app/controller/Index.php。

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

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

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

立即学习“PHP免费学习笔记（深入）”；

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

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

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

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

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