ThinkPHP多应用模式实战：二级域名绑定admin/api模块【详解】

ThinkPHP 多应用模式下实现二级域名绑定，比如让 admin.example.com 指向 admin 应用、api.example.com 指向 api 应用，这事儿看着简单，实际踩坑的人不少。很多人以为改个配置就行，结果死活出不来。核心问题在于：目录结构、域名识别、路由导入、入口控制，这四步必须协同生效，缺一不可。特别是 TP6.1+ 已经废弃了 config/app.php 里的 domain_bind 配置，还拿着老办法去绑定子域名，那必然失败。

一、先搭好多应用骨架

这一步没做对，后面全是白忙。先确保基础结构正确：

• 执行 composer require topthink/think-multi-app 安装多应用扩展。
• 手动删除根目录下的 app/controller——这是单应用的标志，不删掉，框架就没法进多应用模式。
• 运行命令创建具体应用：php think build admin 和 php think build api，生成 app/admin/ 和 app/api/ 目录。
• 检查每个子应用目录是否包含标准结构：controller/、model/、config/、route.php。模块名必须是合法 PHP 类名，比如 admin 可以，admin-v2 就不行。
• 确认 config/app.php 里设置了 'auto_multi_app' => true，并且 'app_namespace' => 'app'。

二、启用域名识别与子域名路由

只开启 url_domain_deploy 是不够的，还得配合显式注册子域名规则。很多人卡在这一步——配置写了，但没注册路由，结果等于没配。

• 在 config/app.php 中设置 'url_domain_deploy' => true（注意：不是旧版的 APP_SUB_DOMAIN_DEPLOY）。
• 在 route/app.php（推荐）或 app/common/route.php 中注册：
  

  use thinkRoute;
  Route::domain('admin', 'admin'); // admin.example.com → app/admin/
  Route::domain('api', 'api');     // api.example.com → app/api/
  Route::domain('*', 'index');     // 其他域名（含 www、无子域）→ app/index/

• 每个子应用的 app/{name}/route.php 文件必须存在，且以 use thinkfacadeRoute; 开头，里面注册本应用的实际路由，比如 Route::get('login', 'index/login')。

三、必须显式导入子应用路由

TP6 不会自动扫描所有 app/*/route.php，这个坑很容易被忽略——漏掉导入，对应应用就完全不可访问。所以需要在全局路由入口 config/route.php 中明确导入：

• Route::import('admin', 'admin');
  Route::import('api', 'api');

• 第二个参数大小写必须与应用目录名严格一致。比如 app/admin/ 对应 'admin'，不能写 'Admin' 或 'ADMIN'。
• 新增应用后，务必同步追加 Route::import() 行，否则该应用路由不会加载。

四、Web 服务器与开发环境准备

PHP 层配置得再好，如果服务器没有把正确的 Host 头传过来，一切都白搭。这里有几个关键点：

• Nginx/Apache 必须将所有请求统一指向 public/ 目录，千万不要为每个子域名配不同的入口文件。
• 确保 fastcgi_param HTTP_HOST $http_host;（Nginx）或对应的 Apache 设置已启用，让 PHP 能读到原始的 Host 值。
• 本地测试时，在 hosts 文件添加：
  

  127.0.0.1 admin.test
  127.0.0.1 api.test

  然后在 PHPStudy 或 Nginx 中将这两个域名 root 指向项目 public/ 目录。
• 最后别忘了清空 runtime/ 下的 cache/ 和 route/ 目录，避免旧缓存干扰新配置。

总的来说，这四个步骤是一条完整的链条，任何一环被忽略都可能让整个绑定失效。按照上面的顺序检查一遍，基本就能跑通。