thinkphp 6+ 自定义类自动加载只认 composer 的 psr-4 配置，必须在项目根目录 composer.json 的 "autoload"."psr-4" 中严格声明命名空间与路径映射（如 "app\utils\": "app/utils/"），并执行 composer dump-autoload -o 生效；漏配、格式错误（反斜杠/斜杠缺失、大小写不一致）或未运行命令均导致 class not found。
ThinkPHP 6+ 的自定义类自动加载，只认 Composer 的 PSR-4 配置，不认手动 require、不认 TP5 的 thinkLoader::addNamespace()，也不自动扫描 app/utils/ 这类目录——配错或漏执行命令，就直接报 Class "apputilsHelper" not found。
为什么 new apputilsHelper 会报错
不是类写错了，是加载链根本没走到你文件上。TP6 启动时只加载 vendor/autoload.php，而它只按 composer.json 里声明的 PSR-4 规则找路径。如果你没在项目根目录的 composer.json 中注册 "app\utils\": "app/utils/"，Composer 就当这个命名空间不存在。
- 错误现象：
Class "apputilsArrHelper" not found，但文件明明在app/utils/ArrHelper.php，且命名空间写了namespace apputils; - 根本原因：命名空间前缀
apputils没在composer.json的"autoload"."psr-4"里声明，或路径末尾少了反斜杠 - 大小写必须完全一致：
apputils≠AppUtils，Linux 下路径区分大小写，Windows 也可能因缓存失效 - 别指望改完文件就生效——
composer dump-autoload -o必须手动运行一次
如何正确配置 composer.json 实现自动加载
打开你项目根目录的 composer.json，编辑 "autoload"."psr-4" 字段。注意格式细节，一个字符错就白配：
- 命名空间末尾必须带双反斜杠：
"app\utils\": "app/utils/"（Windows 下用双反斜杠转义，Linux/macOS 也兼容） - 路径末尾必须带正斜杠：
"app/utils/"，不能写成"app/utils"或"./app/utils/" - 如果同时有多个自定义目录，每行一个映射，例如：
"app\service\": "app/service/"、"app\dto\": "app/dto/" - 改完立即执行：
composer dump-autoload -o（加-o才生成优化映射，开发期不加可能不生效）
vendor 里的第三方包加载失败怎么办
报 Class "OvertruePinyinPinyin" not found，但 composer require overtrue/pinyin 明明成功了？这不是 ThinkPHP 的锅，是 Composer 加载链断在入口。
- 检查
public/index.php是否引入了vendor/autoload.php（TP6 默认有，但若你重写过入口，可能删掉了） - 确认该包的
composer.json声明了 PSR-4（查看vendor/overtrue/pinyin/composer.json的"autoload"."psr-4"） - 有些老包用
"classmap"，必须加-o参数才能生成映射：composer dump-autoload -o - 别在控制器里临时
require_oncevendor 文件——破坏自动加载一致性，IDE 和测试都难跟上
自定义类被 IDE 标红但运行正常
PHPStorm 或 VS Code 提示 Undefined class，可运行、可调试，就是跳转不了、没类型提示。这是 IDE 没读到你的 PSR-4 配置，不是代码问题。
- 确保 IDE 已识别项目根目录下的
composer.json（PHPStorm：File → Settings → PHP → Composer → Enable auto-loading） - 重启 IDE 索引：PHPStorm 选 File → Reload project，VS Code 运行
Developer: Restart Extension Host - 检查
composer.json中的路径是否为相对路径（如"app/utils/"），绝对路径或变量插值会导致 IDE 解析失败 - 别手动在 IDE 里添加 include path——它不会同步 Composer 的命名空间逻辑，反而造成混淆
最常被忽略的一点：TP6 不再解析 AUTOLOAD_NAMESPACE 配置项，也不再扫描 extend/ 目录。所有自定义类，无论放在哪，只要想自动加载，就必须走 Composer PSR-4 这一条路——没有例外，也没有后门。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
