ThinkPHP多应用模式怎么配置_ThinkPHP模块化多应用拆分开发方案【指南】

ThinkPHP 的多应用模式，说起来好像就是改个配置的事儿，但真上手的时候，不少人会发现——怎么报错了？怎么找不到控制器？其实这背后藏着四个必须同时满足的条件：目录结构要建对、命名空间要配好、路由要手动导入、自动加载要打通。少一个，系统就跟你“装死”给你看。

子应用目录：框架不会帮你建，得自己动手

很多人以为把 app_multi_module 设为 true 就完事了，结果请求打进来，直接甩你一个 AppNotFoundException。原因很简单：框架不会自动在 app/ 下面给你建 admin 或 api 目录——你得手动搭好这个架子。

怎么做？TP6.1+ 版本可以用 php think app:create admin，旧版用 php think build admin。目的是确保 app/admin/ 下面有 controller/、model/、view/、config/ 这些标准子目录。另外还有一个容易踩坑的地方：模块名必须是合法的 PHP 类名——字母、数字、下划线都行，但不能以数字开头。所以 admin 没问题，但 1admin 或 user-api 这种，系统直接不认。

还有一点老手也容易忘：原始的 app/controller 目录必须删掉。这个目录是单应用模式的标志，你不删，框架会误以为整个项目还是单应用，多应用识别根本不会触发。

配置文件：三个开关一个都不能少

很多人以为 app_multi_module => true 就是开启多应用的钥匙，其实这只是“允许”多模块而已。真正让系统识别多应用的，是另外两个配置项：auto_multi_app => true 和 app_namespace => 'app'。缺了它们，自动加载就会失败，报 Class not found 的错误。

所以，请确认你的 config/app.php 里包含了这三行：

• 'auto_multi_app' => true
• 'app_namespace' => 'app'
• 'default_app' => 'index'（这个可以换成你想要的默认应用）

另外，如果你用了 topthink/think-multi-app 扩展（官方推荐的做法），别忘了检查 config/app.php 的 providers 数组里是否包含了 \think\multi\AppServiceProvider::class。改完配置后，千万别偷懒——一定要清空 runtime/cache/ 和 runtime/route/ 下的缓存文件。旧的路由缓存会掩盖配置生效情况，让你以为配置没生效，白白浪费时间排查。

子应用路由：不手动导入，就是一团死代码

config/route.php 是全局路由入口，但它不会自动去扫描 app/*/route.php。你必须手动把每个子应用的路由文件导入进来，否则无论你怎么拼 URL，系统都匹配不到任何控制器。

具体写法是在 config/route.php 里加上：Route::import('admin', 'admin')。注意，第二个参数是子应用目录名，大小写敏感，必须和 app/admin 完全一致。这里还有一个常见问题：app/admin/route/app.php 里面不要再套 Route::group('admin', ...)，否则访问路径会变成 /admin/admin/login，多了一层目录，看着就别扭。

更关键的是，每新增一个应用，必须同步追加对应的 Route::import() 行。漏掉一条，那个应用就完全不可达，这在联调的时候特别容易让人困惑。

域名绑定：入口文件和服务端重写都要配

只在 config/app.php 里写一个 'domain_bind' => ['admin.example.com' => 'admin']，还不足以让 admin.example.com 正常工作。你还需要为每个域名准备一个独立的入口文件，比如 public/admin.php。这个文件内容和 index.php 几乎一样，只需要改一行：define('APP_NAME', 'admin')。

然后，Web 服务器（Nginx/Apache）必须把该域名的请求指向对应的入口文件。举个 Nginx 的例子：root 指向 public/ 目录，然后用 fastcgi_param SCRIPT_FILENAME $document_root/admin.php; 指定入口文件。

当然，如果你坚持用 public/index.php 作为统一入口，也不是不行，但域名绑定会依赖 PATH_INFO 的解析。这时候需要确保 app.url_common 为 true，否则系统无法从 Host 头中提取应用名。

最容易忽略的一点：应用之间默认不共享

最后说一个很多人踩过坑的点：多应用之间默认不共享模型、中间件和配置。你想在 admin 和 api 之间复用用户模型？那就得把模型放在 app/common/model/ 目录下，并且在引用时使用完整的命名空间。如果你想给 admin 应用单独配置 Redis 缓存前缀，不要直接改全局的 cache.php，而是要在 app/admin/config/cache.php 里单独覆盖 'prefix' 配置项。

说白了，多应用模式不是简单的开关切换，它更像是一种架构思维的转变——每个应用都是一个独立的小世界，你需要手动告诉它们：哪些可以共享，哪些必须隔离。