ThinkPHP多模块需严格遵循物理目录与命名规则：模块名须为合法PHP类名，目录下必须含controller子目录及控制器文件，且需启用auto_multi_module并清理路由缓存。
模块目录结构怎么组织才不被框架忽略
ThinkPHP 默认只识别 app 目录下的模块，多模块不是靠配置“打开开关”，而是靠物理目录和命名规则生效。如果你把模块放在 app/admin 却访问不到，大概率是目录名没对上或没启用模块化支持。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 模块名必须是合法的 PHP 类名（字母、数字、下划线，不能以数字开头），比如
admin、api_v2可以，1admin或user-center不行 - 每个模块目录下必须有
controller子目录，且至少有一个控制器类文件（如IndexController.php），否则框架启动时可能报ClassNotFoundException - 确认
app/middleware.php和app/provider.php没误删或注释掉模块自动加载逻辑 —— ThinkPHP 6+ 的模块发现依赖think\facade\App::module()的扫描机制，删了就失效
路由访问不到模块？检查这三处配置
最常见现象：URL 写成 /admin/index/index 却跳转到默认模块或 404。这不是路由没写，而是模块未被识别或路由未绑定到模块上下文。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 在
config/route.php中显式声明模块路由：用Route::domain('admin.example.com', function () { ... })或前缀分组Route::group('admin', function () { ... })，但注意：后者只是路径前缀，不等于模块切换；真正激活模块需配合Route::module('admin')或在 URL 中带m=admin参数（取决于app.url_common配置） - 检查
config/app.php中'default_module' => 'index'是否覆盖了你的意图；若想让所有请求按域名/路径自动匹配模块，得设'auto_multi_module' => true（TP6.1+ 支持） - 禁用 URL 兼容模式时（
app.url_common = false），模块名必须出现在 PATH_INFO 第一段，即/admin/index/index才有效，/index/index?m=admin会被忽略
模块间模型和配置怎么共享又不冲突
不同模块共用一张用户表，但各自需要不同的字段校验规则或数据库连接配置 —— 这时候直接复制模型会埋坑，硬编码配置又难维护。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 模型统一放在
app/common/model（非模块内），通过命名空间app\common\model\User调用，避免各模块重复定义；模块专属逻辑用继承扩展，比如app\admin\model\AdminUser extends \app\common\model\User - 模块级配置不要写死在
config/根目录，改用app/admin/config/下的同名文件（如database.php），框架会自动合并：模块配置优先级高于全局，但仅限该模块内生效 - 跨模块调用服务类时，别用
new AdminService()，改用容器注入或think\Container::getInstance()->get('admin_service')，否则自动依赖注入失效，且测试难 mock
调试时模块路由总跳错？先看日志里的 Route::rule 输出
开发中改了几版路由，结果请求进错控制器，var_dump($this->request->module()) 返回的却是 index —— 这往往不是代码问题，而是路由缓存没清或规则顺序错了。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 每次改完
route.php，立刻执行php think route:clear，否则旧规则还在runtime/route缓存里躺着 - 用
php think route:list查看实际注册的路由，重点观察Method列是否为*（表示通配），以及Rule列是否含[module]占位符 —— 没有说明模块识别逻辑根本没挂上 - 如果用了闭包路由或中间件拦截，检查是否在
before阶段提前返回了响应（比如权限判断失败直接return json(...)），导致后续模块解析流程被跳过
模块不是插件，它和框架生命周期深度耦合。一个没声明的模块目录，即使放满代码也不会被加载；一条没清理的路由缓存，能让新规则永远不生效。动手前先确认 app/multi_module 开关状态和 runtime 目录权限，比反复改控制器更省时间。
