ThinkPHP 多级命名空间类加载失败的根本原因是 PSR-4 路径映射不匹配、Composer 配置错误或 ThinkPHP 自动加载器冲突；需严格统一命名空间、物理路径、composer.json 的 psr-4 配置，并禁用 ThinkPHP 传统加载、显式路由绑定、清理 Composer 缓存。
ThinkPHP 的命名空间路径和 PSR-4 不匹配
ThinkPHP 默认用 app 目录做根命名空间，但 PSR-4 要求命名空间前缀必须严格对应物理路径。比如你写 appserviceorderV1OrderService，它就要求文件必须在 app/service/order/V1/OrderService.php；如果实际放在 app/service/Order/V1/OrderService.php，Composer 自动加载会失败——不是 ThinkPHP 报错，而是 Class not found。
常见错误现象：Class 'appserviceorderV1OrderService' not found，但文件明明存在、类名也对；根本原因是 Composer 没注册这个映射，或者映射路径写错了。
- 检查
composer.json里的psr-4配置，确保前缀和目录一一对应，例如："psr-4": {"app\": "app/"} - 命名空间里不能出现小写
v1，PSR-4 规范要求命名空间段必须是合法的 PHP 标识符（即首字母大写或全大写），V1可以，v1不行 - 改完
composer.json后必须运行composer dump-autoload，否则新映射不生效
ThinkPHP 自动加载器和 Composer 加载器混用冲突
ThinkPHP 5.1+ 内置了类自动加载逻辑，但它默认只处理 app、extend、vendor 等固定路径；一旦你手动加了 set_include_path 或在 bootstrap.php 里注册了自定义 spl_autoload_register，就可能绕过 Composer 的 PSR-4 解析，导致多级命名空间类找不到。
使用场景：你在 app/common 下放了一个 BaseController，又在 app/api/v2 下写了继承它的控制器，结果启动时报 Class 'appcommonBaseController' not found——其实不是类不存在，而是 ThinkPHP 的加载器没走 PSR-4 规则，而是按旧路径规则找去了。
立即学习“PHP免费学习笔记（深入）”；
- 优先用 Composer 的 PSR-4，禁用 ThinkPHP 的传统路径映射：在
config/app.php中设'auto_load' => false - 不要在
public/index.php或start.php里手动 require 类文件，这会破坏自动加载链 - 确认
vendor/autoload.php是最早被引入的，ThinkPHP 的thinkphp/base.php必须在其后加载
多级子目录下控制器/服务类无法被路由识别
即使类能正常 new 出来，ThinkPHP 的 URL 路由和命令行指令仍可能找不到它们——因为框架内部用字符串拼接生成类名时，对斜杠/反斜杠、大小写、下划线转换很敏感。
典型表现：http://test.com/api/v2/order 报 ClassNotFoundException，而 apppi 2OrderController 文件存在、命名空间也对；问题出在 ThinkPHP 的 Route::parseUrl 默认把 v2 当成方法名，而不是命名空间段。
- 在
route/route.php中显式绑定路由到完整类名：Route::get('api/v2/order', 'app\api\v2\OrderController@index'); - 避免在命名空间中使用纯数字段（如
v2），改用V2或Version2，否则部分版本的 ThinkPHP 会截断解析 - CLI 命令类若放在多级目录（如
app/command/db/Backup.php），需在command.php中手动添加映射：'db:backup' => 'app\command\db\Backup'
composer dump-autoload 后类仍不生效
这是最让人抓狂的一环：配置改了、命令跑了、缓存清了，但类还是加载不到。本质原因往往是 Composer 缓存了旧的 classmap 或生成了错误的静态映射。
性能影响：启用 --optimize-autoloader 会让 Composer 把所有类路径预生成到 vendor/composer/autoload_classmap.php，一旦路径变更但没重新 dump，就会一直读错的映射。
- 先删掉
vendor/composer/autoload_*.php手动清理缓存文件 - 用
composer dump-autoload -o -a强制重生成优化版 classmap（-a表示包含所有包） - 检查
vendor/composer/autoload_static.php里是否真有你新增的命名空间条目，没有就说明 PSR-4 配置格式有误（比如漏了结尾反斜杠或用了正斜杠）
多级命名空间本身不难，难的是每个环节都得对齐：文件路径、命名空间字符串、Composer 配置、ThinkPHP 的加载开关、路由解析逻辑——漏掉任意一环，都会表现为“类找不到”，但报错位置离真实问题可能隔了三层。
