multi_app.php缺失或未引入、Route::import()参数大小写错误、缓存未清及app/controller目录残留，均会导致多应用路由失效。必须确保multi_app.php存在并显式引入，Route::import第二个参数与子目录名严格一致，执行php think clear:route，并彻底删除app/controller目录。
multi_app.php 文件缺失或声明错误
ThinkPHP 多应用模式依赖 vendor/topthink/think-multi-app 提供的自动加载逻辑，但关键入口文件 multi_app.php 必须存在且被正确引入——它不是可选补丁，而是多应用路由解析的启动开关。
常见错误现象：AppNotFoundException 报错、子应用目录（如 app/admin）完全不被识别、Route::import() 静默失败。
-
vendor/topthink/think-multi-app/src/multi_app.php必须存在；若用 Composer 安装后该文件缺失，说明安装异常，应删掉vendor重装：composer require topthink/think-multi-app - 该文件必须在
public/index.php中被显式引入（TP6/TP8 均需），位置在require __DIR__ . '/../vendor/autoload.php';之后、(new App())->run()->send();之前，缺一行就降级为单应用 - 若项目启用了 Swoole（
php think swoole），multi_app.php还需在server.php或 Swoole 启动脚本中重复引入——Swoole 不走标准 CLI 入口链，会跳过默认加载
Route::import() 调用位置和参数大小写敏感
子应用路由不会自动加载，Route::import('admin', 'admin') 必须出现在全局路由入口 app/route/app.php 中，且第二个参数必须与子目录名**逐字符一致**（包括大小写），否则框架找不到对应 app/admin/route/ 下的文件。
常见错误现象：访问 /admin/login 返回 404，但 app/admin/route/app.php 确实存在且语法正确。
立即学习“PHP免费学习笔记（深入）”；
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 不能写成
Route::import('admin', 'Admin')或Route::import('admin', 'ADMIN')—— Linux 环境下路径匹配直接失败 - 不能只写
Route::import('admin')（省略第二个参数），此时框架默认去app/route/admin.php查找，而非app/admin/route/app.php - 若想支持
/admin/xxx前缀，必须配合分组：Route::group('admin', function () { Route::import('admin', 'admin'); })->app('admin');，漏掉->app('admin')将导致控制器命名空间仍按主应用解析
缓存未清导致新路由结构不生效
TP6/TP8 的路由缓存机制对多应用极其严格：旧缓存文件若残留，哪怕你已补全所有目录和 Route::import()，框架仍会加载过期的路由快照，子应用路由等于没注册。
常见错误现象：改完配置、加了 multi_app.php、写了 Route::import()，但 php think route:list 输出里始终没有子应用路由。
- 执行
php think clear:route是必须动作，它会清理runtime/cache/route.php和各子应用下的同名缓存（如app/admin/runtime/cache/route.php） - 若使用注解路由（
@Route），必须额外加--annotation参数重建：php think route:cache --annotation；否则只扫描app/route/app.php，忽略子应用路由文件 - 检查
config/app.php中'app_debug' => false是否真正生效——dump(\think\App::debug())输出true时，缓存完全不参与匹配，所有“清缓存”操作都白做
子应用目录下 controller/ 存在引发静默降级
这是最隐蔽的坑：app/controller 目录只要存在（哪怕为空），ThinkPHP 就强制判定为单应用模式，所有多应用逻辑（包括 multi_app.php 加载、Route::import() 解析、子应用命名空间映射）全部失效，且不报任何警告。
常见错误现象：多应用配置全对、multi_app.php 已引入、Route::import() 正确，但 /admin/login 仍走主应用的 IndexController。
- 务必确认项目根
app/下**没有**controller/目录；若有，立刻删除（单应用残留） - 子应用自己的
controller/（如app/admin/controller/）可以存在，且必须存在；但根app/controller/是绝对禁区 - 检查
app/config/app.php中'app_namespace' => 'app'是否设置；若仍是默认的'app\controller'，命名空间自动加载会去错路径找类，报Class not found
多应用路由失效往往不是某一个点错了，而是多个环节卡死在“看起来正常”的状态里。尤其注意 app/controller 目录是否存在、multi_app.php 是否真被引入、以及缓存是否彻底清空——这三个地方出问题，调试日志里几乎不报错，只能靠手动验证。
