ThinkPHP自动加载原理图解_自动加载原理详解【教程】

ThinkPHP 6+ 的自动加载机制，说白了，完全交给了 Composer 的 PSR-4 来管。框架自己不再折腾 __autoload 或者手动 require 那一套。你改了个类文件，结果抛个 Class not found？十有八九是没搞通这条加载链。

为什么 new AppServiceUser() 找不到类？

这是最常见的问题——路径和命名空间对不上号。TP6 并不会自动把 app/ 目录丢给 Composer 去加载，你在 app/service/User.php 里写了 namespace appservice;，但 composer.json 里没配 "App\": "app/"，那肯定不行。

• Composer 拿到 AppServiceUser 之后，会把它拆成前缀 App 和相对类名 ServiceUser，然后去 app/ 底下找 ServiceUser.php。注意，它找的是 ServiceUser.php，不是 User.php，也不是 service/User.php。
• 命名空间末尾必须带双反斜杠 "App\"，漏掉一个 \，Composer 就会把 AppServiceUser 当成顶层命名空间，跑到项目根目录去找 AppServiceUser.php。
• 文件名必须和类名完全一致：类叫 User，文件就得是 User.php，写成 user.php 或 UserService.php 都不行（除非你用 classmap）。
• 改完 composer.json 之后必须运行 composer dump-autoload -o，否则新的映射不会写入 vendor/composer/autoload_psr4.php。

composer dump-autoload -o 到底做了什么？

简单来说，它把所有 PSR-4 映射规则拍平成一张扁平的类名→文件路径映射表，存在 vendor/composer/autoload_classmap.php 里。启用优化后，new AppServiceUser() 不再每次去拼路径，直接查表，速度飞快。代价呢？你新增类或者改了命名空间，不重新 dump 就永远找不到。

• 开发阶段建议只用 composer dump-autoload（不加 -o），避免缓存导致的“改了代码却没生效”假象。
• -o 生成的 classmap 会覆盖 PSR-4 行为，哪怕你配置了 "App\": "app/"，最终也按 classmap 里的绝对路径加载。
• 如果某个类既在 PSR-4 映射范围，又被 classmap 扫到（比如你手动把 app/ 加进了 classmap），classmap 条目优先生效，PSR-4 规则被跳过。

第三方包如 overtrue/pinyin 加载失败怎么查？

这锅别甩给 ThinkPHP，是 Composer autoloader 链断了。入口文件 public/index.php 必须包含 vendor/autoload.php，少这一行，整个 vendor 下的包全失效。

• 检查 vendor/autoload.php 是否被引入：打开 public/index.php，确认有 require __DIR__.'/../vendor/autoload.php';。
• 运行 composer show overtrue/pinyin 看实际安装的版本，v5+ 已把主类从 OvertruePinyinPinyin 改成 OvertruePinyinGenerator。
• 某些老包用的是 classmap autoload 类型，必须加 -o 才能生效，单纯 dump-autoload 不够。
• 别去动 vendor/composer/autoload_*.php —— 它们是自动生成的，下次 composer install 就被覆盖。

这里有个特别容易被忽视的细节：TP6 的“自动加载”其实分两层——框架核心类走自己的 thinkLoader（比如 thinkDb），而你写的业务类、服务类、工具类，全部依赖 Composer。这两套机制互不感知，也绝不混用。想让 app/utils/ArrHelper.php 被 new apputilsArrHelper() 加载，唯一正路就是配 PSR-4 + dump-autoload，别去试 thinkLoader::addNamespace()，那玩意儿 TP6 早就删了。