为什么 FrankenPHP 运行 ThinkPHP 项目路由解析异常-php教程-PHP中文网

frankenphp运行thinkphp路由异常的根本原因是其不自动填充path_info且无重写逻辑，导致tp6/tp8无法解析原始路径；需改用url_model=>0、确保nginx透传$query_string与host头，并显式启用url_route_on。

为什么 frankenphp 运行 thinkphp 项目路由解析异常

FrankenPHP 运行 ThinkPHP 项目时路由解析异常，根本原因不是 FrankenPHP 本身不兼容，而是其底层机制与 ThinkPHP 默认依赖的 PATH_INFO 或 QUERY_STRING 解析方式存在错位。ThinkPHP（尤其是 TP6/TP8）在传统 PHP-FPM 环境中习惯通过 $_SERVER['PATH_INFO'] 或 $_SERVER['REQUEST_URI'] + 重写规则提取路由参数，而 FrankenPHP 作为 Swoole/React 基础上的现代 PHP 运行时，默认不自动填充 PATH_INFO，也不执行 Apache/Nginx 那类重写逻辑——它直接将原始请求路径交给 PHP，由框架自行解析。

以下是关键问题点和对应解决方向：

✅ 路由无法匹配（如 `/user/list` 报 404，但 `/index.php/user/list` 可用）

FrankenPHP 不会自动把 /user/list 重写为 /index.php?s=/user/list 或 /index.php/user/list
ThinkPHP 若配置为 url_model => 2（PATH_INFO 模式）或未启用 url_route_on，就收不到有效路径信息
$_SERVER['PATH_INFO'] 为空或为 /index.php，导致路由系统“看不见” /user/list

解决建议：

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

下载
在 config/app.php 中强制使用 兼容性更强的 URL 模式：
'url_model' => 0, // 普通模式（?s=xxx），最稳
'url_route_on' => true,
'url_route_must' => true,
同时确保所有访问都带 s= 参数（开发调试可用 Nginx 做一层透传，见下文）

✅ `php think route:list` 显示路由但访问仍 404

表明路由文件已加载、规则语法无误，但请求未按预期格式进入路由分发流程
FrankenPHP 的 $_SERVER['REQUEST_URI'] 是原始路径（如 /user/list），但 ThinkPHP 若未开启 url_parse_on 或 url_domain_deploy，可能跳过解析直接 fallback 到默认模块/控制器

解决建议：
在 route/app.php 开头加调试语句确认是否执行：
file_put_contents('/tmp/route_loaded.log', date('Y-m-d H:i:s') . "\n", FILE_APPEND);
检查 public/index.php 是否被 FrankenPHP 正确设为入口（FrankenPHP 要求显式指定 DOCUMENT_ROOT 和 SCRIPT_NAME，不能依赖 .htaccess 或 try_files）

✅ Nginx 前置代理后路由参数丢失（如 `?id=123` 不进 `$_GET`）

FrankenPHP 在反向代理场景下，若 Nginx 未透传完整查询字符串，$query_string 会被截断
错误配置如 fastcgi_param QUERY_STRING $args; 缺失，或 try_files 写成 /index.php?s=$1（TP5 风格），TP8 不识别

解决建议（Nginx 配置片段）：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param QUERY_STRING $query_string;  # 必须显式传递
    fastcgi_pass 127.0.0.1:6000; # 指向 FrankenPHP 监听端口
}

✅ 域名路由（Route::domain）失效或 `url()` 生成链接错误

FrankenPHP 不自动处理 Host 头转发逻辑，若 Nginx 未设置 proxy_set_header Host $host;，$_SERVER['HTTP_HOST'] 可能为 localhost 或空
导致 Route::domain('api.example.com') 匹配失败，且 url() 辅助函数无法判断当前域名

解决建议：
Nginx 反代配置中必须包含：
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
ThinkPHP 中开启域名部署：config/route.php 加 'url_domain_deploy' => true

不复杂但容易忽略。FrankenPHP 不是“另一个 FPM”，它要求 ThinkPHP 主动适配运行时环境，而不是等待 Web 服务器做重写兜底。核心动作就三步：关 PATH_INFO 依赖、用 s= 模式保底、Nginx 透传关键变量。