根本原因是APP_MULTI_MODULE未启用或域名部署开关未打开，导致框架不解析多模块而默认进入index模块；必须确认入口定义APP_MULTI_MODULE常量、开启url_domain_deploy、确保api子目录合法且结构完整。
tp5 多域名绑定时提示“控制器不存在”
根本原因不是路由没配对，而是模块名被框架自动截断或误判。比如你绑定了 api.xxx.com 到 api 模块，但访问时却走到了 index 模块，或者直接报 控制器不存在 —— 这通常是因为 APP_MULTI_MODULE 未启用，或域名部署开关没打开。
必须确认以下三点：
-
public/index.php中define('APP_MULTI_MODULE', true)在require autoload.php之前，且不能被 config/app.php 里的同名配置覆盖 -
application/config.php中'url_domain_deploy' => true已开启 -
app/目录下存在合法的api子目录（不含大写、短横线、中文），且内部有标准结构（controller/、model/等）
常见陷阱：把 api 模块建在 app/api/ 下，但入口文件里漏了 APP_MULTI_MODULE 定义，此时框架压根不会尝试解析多模块，所有域名请求都默认落到 index 模块。
nginx 配置导致域名绑定失效
Nginx 的 root 设置和 location 匹配顺序，会直接绕过 ThinkPHP 的域名路由逻辑。典型错误是把多个域名共用一个 root，却没在 server 块里区分 server_name 对应的模块入口。
立即学习“PHP免费学习笔记（深入）”；
正确做法是每个域名单独一个 server 块，并显式指定模块参数：
server {
listen 80;
server_name api.example.com;
root /path/to/public;
index index.php;
<pre class="brush:php;toolbar:false;">location / {
if (!-e $request_filename) {
rewrite ^(.*)$ /index.php?s=$1 last;
}
}
location ~ \.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
# 关键：强制传入模块名
fastcgi_param PHP_VALUE "auto_prepend_file=/path/to/public/index.php";
fastcgi_param PATH_INFO "/api";
}}
更稳妥的方式是用 URL 参数透传模块：
- 在
api.example.com的 location 里 rewrite 加上/index.php?s=/api/index/index这类固定路径 - 或在
application/route.php中用Route::domain('api.example.com', 'api')显式绑定 - 避免依赖 Nginx 的
fastcgi_split_path_info，它容易与 TP5 的 pathinfo 解析冲突
二级域名绑定后仍访问 index 模块
即使开了 url_domain_deploy，如果 DNS 解析、宝塔子目录绑定、Nginx server_name 三者不一致，框架连域名都收不到，自然无法做后续匹配。
检查步骤：
- curl -H "Host: api.example.com" http://127.0.0.1 —— 看是否能触发域名路由（排除 DNS 和反代问题）
- 在
application/common.php开头加var_dump($_SERVER['HTTP_HOST']); die;，确认实际收到的 host 是什么 - 确保
application/config.php中没有硬编码'default_module' => 'index'覆盖了域名判断结果
特别注意：TP5 的域名绑定只识别 $_SERVER['HTTP_HOST']，不读取 X-Forwarded-Host。如果你用 CDN 或反向代理，必须在 Nginx 里用 proxy_set_header Host $host; 透传原始 host。
模块名含特殊字符或大小写引发的 404
TP5 默认将模块名转为小写并校验合法性。如果你建了 AppApi 或 API 目录，框架会拒绝加载，报 InvalidArgumentException，但错误信息常被静默吞掉，只显示 404 或 “控制器不存在”。
解决办法很直接：
- 模块目录名必须全小写、纯字母、无下划线（如
api、v2、admin） - 对应命名空间也得匹配：模块
api→app\api\controller\Index - 删掉
app/下所有空目录、测试目录、Git 临时文件（TP5 启动时会扫描全部子目录并尝试加载）
最容易被忽略的是：模块目录存在，但里面没有 controller 子目录，或 controller 下没 PHP 文件 —— 此时框架认为该模块“不可用”，直接跳过，不报错也不提示，最终 fallback 到默认模块。
