ThinkPHP5服务器域名绑定模块配置要点-ThinkPHP-PHP中文网

thinkphp5域名绑定模块需同时满足三个条件：开启url_domain_deploy配置、在route.php中正确配置__domain__数组、web服务器将二级域名解析至public目录，缺一不可。

thinkphp5服务器域名绑定模块配置要点

ThinkPHP5 的域名绑定模块功能本身可用，但必须满足三个硬性条件：开启 url_domain_deploy、路由文件中用 __domain__ 配置、DNS 和 Web 服务器已正确解析二级域名到 public/ 目录——缺一不可，否则静默失效。

url_domain_deploy 必须显式开启

TP5 默认不启用域名部署，仅靠写 Route::domain() 或配置 __domain__ 不会生效。必须在 config/app.php（或 application/config.php）中设置：

'url_domain_deploy' => true,

这个开关控制整个域名路由解析流程的启动。未开启时，框架直接跳过域名匹配逻辑，所有请求都走默认路由。

常见错误：只改了 route.php 里的 __domain__，却忘了开这个配置项，结果怎么测都是 404
注意位置：该配置必须在应用配置层（config/app.php），不能放在 config/route.php 或中间件里
TP5.1+ 可配合 url_domain_root 处理 .com.cn 类特殊后缀，例如：'url_domain_root' => 'example.com.cn'

domain 配置必须写在 route.php 返回数组中

TP5 的域名绑定不是靠 Route::domain() 函数动态注册，而是靠路由配置数组中的 __domain__ 键静态声明。格式必须是：

PHP

编写健壮的PHP代码，规避类型转换陷阱、数组怪癖及常见安全漏洞。

下载

return [
    '__domain__' => [
        'admin' => 'admin',
        'api'   => 'api',
        'm'     => 'mobile',
    ],
];

admin 是子域名前缀（即 admin.example.com 中的 admin），右侧 admin 是对应模块名，二者可不同
不能写成 Route::domain('admin', 'admin') —— 这是 TP6 的写法，在 TP5 下会报错或被忽略
如果用了完整域名（如 admin.example.com），左侧键名就得写全：'admin.example.com' => 'admin'
配置后，访问 admin.example.com/index/index 等价于 www.example.com/admin/index/index，模块前缀自动补上

Web 服务器必须将子域名指向 public/ 目录

TP5 域名绑定是纯 PHP 层路由映射，不改变请求路径，所以 Nginx/Apache 必须把所有子域名的 DocumentRoot 都设为项目根目录下的 public/，否则根本进不了框架。

Nginx 示例（关键点：所有 server 块 root 一致）：

<pre class="brush:php;toolbar:false;">server {
    listen 80;
    server_name admin.example.com;
    root /var/www/myapp/public;
    index index.php;
    ...
}
server {
    listen 80;
    server_name api.example.com;
    root /var/www/myapp/public;  # 必须相同
    index index.php;
    ...
}

宝塔用户：网站 → 添加站点 → 域名填 admin.example.com → 根目录选到 <code>public/（不是项目根目录）
本地开发用 hosts + Apache 虚拟主机时，每个 <virtualhost></virtualhost> 的 DocumentRoot 都要指向 public/，且确保 mod_rewrite 开启
若子域名解析到了项目根目录（比如 /var/www/myapp），则入口文件 public/index.php 无法被访问，直接 404

模块内控制器和视图路径需与配置严格对应

绑定成功后，URL 中不再显式出现模块名，但框架内部仍按模块路径加载资源。例如 admin.example.com/index/index 实际调用的是 application/admin/controller/Index.php 中的 index 方法。

控制器命名空间必须是 app\admin\controller（TP5.0）或 app\admin\controller（TP5.1+），不能漏掉 admin\ 前缀
模板文件路径默认为 application/admin/view/index/index.html，不能放在 application/view/ 下
如果用了多模块但没启用 url_domain_deploy，__domain__ 配置会被完全忽略，请求直接 fallback 到默认模块
调试技巧：在 application/admin/controller/Index.php 的方法开头加 dump(request()->domain());，确认是否命中域名绑定逻辑