准确识别API版本是灰度转发前提，常用URL路径、请求头或查询参数；推荐用map指令映射版本到后端服务，支持正则与默认值；可结合X-Gray-Tag等请求头实现精细化分流；rewrite可清理路径并透传X-API-Version供后端识别。
识别请求中的 API 版本标识
灰度转发的前提是能准确识别当前请求属于哪个 API 版本。常见方式有三种：URL 路径（如 /v1/users、/v2/users）、请求头（如 X-API-Version: v2）、或查询参数（如 ?version=v2）。Nginx 本身不解析 JSON 或业务逻辑，所以必须依赖这些显式、可匹配的字段。
用 map 指令动态映射后端服务地址
推荐使用 map 指令将版本标识映射为上游服务地址，避免重复 if 判断。它在 server 块外定义，高效且支持正则与默认值：
map $uri $backend {
~^/v1/ http://api-v1-cluster;
~^/v2/ http://api-v2-canary;
default http://api-v1-cluster;
}
<p>upstream api-v1-cluster { server 10.0.1.10:8080; }
upstream api-v2-canary { server 10.0.1.20:8080 weight=5; } # 可加 weight 控制灰度流量比例
这样，所有以 /v2/ 开头的请求自动走灰度集群，其余走稳定集群。注意：map 匹配的是原始 $uri（已解码），不包含 query string。
结合请求头实现更灵活的灰度策略
若需按用户身份、灰度标签等做精细化分流，可读取自定义请求头：
map $http_x_gray_tag $backend {
"v2" http://api-v2-canary;
"beta" http://api-beta-cluster;
default http://api-v1-cluster;
}
然后在 location 中使用：
location /api/ {
proxy_pass $backend;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
客户端只需带上 X-Gray-Tag: v2 即可命中灰度后端。该方式与路径解耦，适合 A/B 测试或内部人员白名单场景。
保留原始路径并透传版本信息
灰度服务可能仍需知道原始请求版本，尤其当后端未剥离前缀时。可用 rewrite 清理路径，并通过 header 透传：
location ~ ^/v2/(.*)$ {
rewrite ^/v2/(.*)$ /$1 break;
proxy_pass http://api-v2-canary;
proxy_set_header X-API-Version "v2";
proxy_set_header X-Original-Path $uri;
}
这样既把 /v2/users 转为 /users 发给后端，又让后端明确知道自己处理的是 v2 请求，便于日志追踪或兼容逻辑判断。
