ThinkPHP伪静态规则与API接口路由分离的操作说明【说明】-ThinkPHP-PHP中文网

thinkphp伪静态规则与api路由互相干扰，是因为默认重写规则将/api/请求也转发给index.php，而未加前缀限制的兜底路由会匹配/api/路径并返回html；需通过显式prefix、ext限制及web服务器location分离来解决。

thinkphp伪静态规则与api接口路由分离的操作说明【说明】

ThinkPHP伪静态规则和API路由为什么会互相干扰

因为伪静态规则默认把所有非静态文件请求都交给 index.php 处理，而 API 接口路径（比如 /api/v1/user）如果没被显式排除，就会被前端 fallback 规则吞掉，最终返回 index.html 而不是 JSON 数据——现象就是接口 404 或返回 HTML 内容。

根本原因不是路由写错了，而是「非 API 请求 fallback」和「API 请求直通后端」这两条路径没划清边界。

Apache 的 RewriteRule ^(.*)$ index.php/$1 [QSA,PT,L] 会把 /api/v1/user 也重写进 index.php，后续全靠框架路由判断走哪边
Nginx 的 try_files $uri $uri/ /index.php?s=$uri&$args; 同理，s=api/v1/user 这个参数会被框架解析，但若没提前拦截，就可能落入前端路由逻辑
TP6 默认关闭 url_route_must，意味着未匹配路由会 fallback，而 Route::rule('[:path]', 'index/index') 这类兜底规则又没加后缀限制，/api/xxx 就被当成前端路径处理了

怎么让 /api/ 开头的请求绕过前端 fallback

关键不是堵住所有请求，而是让框架在路由分发前就识别出 API 请求并跳过前端逻辑。

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

在 app/route/app.php 中，用 Route::domain() 或 Route::group() 显式声明 API 路由入口，例如：
```
Route::group('api', function () { Route::get('v1/user', 'api/v1/User/index'); })->prefix('api/');
```
务必在 group 外层加 ->prefix('api/') 或用 Route::domain('api.your.com', ...)，否则 /api/v1/user 仍可能被 [:path] 匹配到
避免使用正则通配如 @^/:path$，它不区分路径前缀，/api/xxx 也会被重定向到 index/index
在兜底规则里加 ->ext('html')，例如 Route::rule('[:path]', 'index/index')->ext('html')，这样带 .json 或无后缀的 /api/xxx 就不会命中

服务器层如何配合避免伪静态吃掉 API 请求

光靠框架路由不够，Nginx/Apache 必须确保 /api/ 请求不被重写规则误伤，或至少让其参数可被正确识别。

Apache：确认 .htaccess 中有 RewriteCond %{REQUEST_URI} !^/api/ 前置条件，再写主规则；或者把 API 请求单独指向一个入口（如 api.php），但需同步改框架配置

Nginx：不要用全局 try_files，改用 location 分离：

location /api/ { try_files $uri $uri/ /index.php?s=$uri&$args; } location / { try_files $uri $uri/ /index.html; }

TP6 默认用 s= 参数传路径，所以 Nginx 的 /index.php?s=$uri&$args 必须保留；若你启用了 pathinfo_depr => '/'，就得确保 fastcgi_param PATH_INFO 正确传递，且 PHP-FPM 没注释掉相关行
检查 config/app.php 中 'url_route_on' => true 已开启，否则所有重写都无效

为什么 /api/v1/user 返回了 HTML 而不是 JSON

大概率是控制器方法里没显式 return JSON，或者中间件干扰了输出。

必须在 API 控制器中用 return json(...) 或 return $this->success(...)，不能只 echo 或 var_dump
确认没启用 view_filter 类中间件，它可能对 /api/ 路径也执行模板渲染
Session 相关中间件（如 session）在 API 场景下应禁用，否则可能触发 cookie 输出，破坏 JSON 格式
检查响应头是否被覆盖：header('Content-Type: application/json; charset=utf-8') 不能被其他代码提前输出内容（比如空格、BOM、调试语句）

真正麻烦的点不在规则多难写，而在于 Apache/Nginx 配置、框架路由定义、控制器输出三者之间只要有一处没对齐，/api/ 就会悄无声息地变成前端页面。尤其要注意 ext('html') 和 ->prefix('api/') 这两个看似微小的配置，漏掉任何一个，fallback 就会越界。