Nginx 为 ThinkPHP 实现分流测试需五步：一、基于 $binary_remote_addr 的 IP 分流；二、基于 $cookie_uid 的登录用户分流并设 fallback；三、基于 URL 参数的临时分流，需 map 预过滤；四、静态资源路径重写实现灰度加载；五、透传 X-ThinkPHP-Version 请求头供后端识别。
如果您在 Nginx 中为 ThinkPHP 应用配置 split_clients 实现分流测试，需确保请求能稳定携带可哈希标识，并通过变量拼接、路径重写或 upstream 动态路由将不同分组导向对应 ThinkPHP 版本实例。以下是实现此目标的步骤：
一、基于客户端 IP 的稳定分流配置
使用 $binary_remote_addr 作为哈希输入源，避免 NAT 环境下 IP 字符串重复导致的散列偏差，确保同一真实客户端始终落入相同分组。该方式无需前端修改，适用于未登录用户灰度场景。
1、在 nginx.conf 的 http 块中添加 split_clients 指令，定义分组变量 $tp_version：
2、配置内容为：split_clients "$binary_remote_addr" $tp_version { 5% "v6"; * "v5"; }
立即学习“PHP免费学习笔记（深入）”；
3、确认已定义两个 upstream，分别指向不同 ThinkPHP 版本的后端服务：
4、upstream tp_v5 { server 127.0.0.1:8085; }
5、upstream tp_v6 { server 127.0.0.1:8086; }
6、在 server 块中，将请求代理至动态 upstream 名称：proxy_pass http://tp_$tp_version;
二、基于 Cookie 的登录用户精准分流
当 ThinkPHP 应用已通过 cookie 设置唯一用户标识（如 thinkphp_session 或自定义 uid），可优先采用 $cookie_uid 作为哈希源，实现跨设备、跨会话的用户级一致性分流，避免因 IP 变化导致版本跳变。
1、在 http 块中配置：split_clients "$cookie_uid" $tp_group { 10% "v6"; * "v5"; }
2、添加 fallback 逻辑：若 cookie 为空，则强制归入 v5 组，防止空值哈希为空字符串引发流量倾斜；
3、使用 if 指令覆盖默认分组：if ($cookie_uid = "") { set $tp_group "v5"; }
4、在 location / 中启用 proxy_pass：proxy_pass http://tp_$tp_group;
三、基于 URL 参数的临时测试分流
为支持运营或 QA 人员手动触发特定 ThinkPHP 版本，可在 split_clients 输入中拼接可信参数（如 ?tp_ver=v6），但需配合 map 预过滤以保障哈希稳定性，避免参数动态值破坏确定性。
1、先定义 map 将参数映射为稳定键：map $arg_tp_ver $tp_route_key { "" $remote_addr; default $arg_tp_ver; }
2、再基于该键分流：split_clients "$tp_route_key" $tp_route { 100% "v6"; * "v5"; }
3、注意：此方式仅用于临时验证，不可用于正式灰度，因参数易被篡改且不具用户持久性；
4、proxy_pass 直接使用：proxy_pass http://tp_$tp_route;
四、ThinkPHP 路径级静态资源灰度加载
若仅需对 ThinkPHP 输出的 JS/CSS/图片等静态资源做版本隔离（如 /static/js/app.js → /static/v6/js/app.js），可跳过 upstream，直接使用 rewrite 修改 URI，降低后端改造成本。
1、在 http 块中配置 salt 增强哈希随机性：split_clients "${binary_remote_addr}THINKPHP_SALT" $tp_static_ver { 3% "v6"; * "v5"; }
2、在 server 的 location ^~ /static/ 块中启用重写规则：
3、rewrite ^(/static/)(.*)$ /static/$tp_static_ver/$2 break;
4、确保 ThinkPHP v5 和 v6 的 public/static/ 目录结构一致，且文件已部署至对应路径；
5、root 指令须指向统一根目录，例如：root /var/www/thinkphp-root;
五、Nginx 与 ThinkPHP 版本标识透传方案
为便于后端识别当前请求所属分组，需将 $tp_version 或 $tp_group 变量注入请求头，使 ThinkPHP 应用层可记录日志、调整逻辑或返回对应 UI 版本。
1、在 proxy_pass 所在 location 中添加：proxy_set_header X-ThinkPHP-Version $tp_version;
2、若使用多级分流变量（如 $tp_group），则替换为：proxy_set_header X-ThinkPHP-Group $tp_group;
3、在 ThinkPHP 的中间件或全局请求钩子中读取该 header 值；
4、示例 PHP 代码：$_SERVER['HTTP_X_THINKPHP_VERSION'] ?? 'v5';
