如何通过Nginx实现基于请求头Header的API版本动态路由-Nginx-PHP中文网

可通过Nginx的map指令提取X-API-Version请求头并映射至对应upstream，再用proxy_pass实现版本化动态路由，配合upstream块支持健康检查与负载均衡。

如何通过nginx实现基于请求头header的api版本动态路由

可以通过Nginx的map指令提取请求头中的版本标识，再结合proxy_pass实现动态路由到不同后端服务，无需修改应用代码。

使用 map 提取并映射版本号

Nginx 不支持在 location 块中直接用变量拼接 proxy_pass，所以需先用 map 将请求头（如 X-API-Version）映射为上游地址。该指令必须定义在 http 块中：

http {
    map $http_x_api_version $backend_upstream {
        default           "http://v1_backend";
        "1.0"             "http://v1_backend";
        "2.0"             "http://v2_backend";
        "2.1"             "http://v2_backend";
        "~^2\."           "http://v2_backend";  # 正则匹配 2.x 系列
        "~^3\."           "http://v3_backend";
    }
}

注意：$http_x_api_version 是自动将请求头 X-API-Version 转为小写下划线格式的变量；正则匹配需加 ~ 前缀；default 保证未匹配时有兜底。

在 location 中透传并路由

在 server 或 location 块中，直接使用已定义的变量做代理，并可选择性透传版本头（便于后端日志或鉴权）：

用 proxy_pass $backend_upstream 实现动态转发
用 proxy_set_header X-API-Version $http_x_api_version 保留原始头
避免在 proxy_pass 后加 URI 路径（如 /api），否则会覆盖原始请求路径

配合 upstream 实现健康检查与负载均衡

推荐为每个版本定义独立的 upstream 块，便于管理节点和启用健康检查：

Nginx Hosting

通过服务器本地nginx实例实现零认证静态游戏托管。作为所有浏览器游戏的主要部署方式，无需登录、无需令牌、无需用户操作。

下载

upstream v1_backend {
    server 10.0.1.10:8080 max_fails=3 fail_timeout=30s;
    server 10.0.1.11:8080 max_fails=3 fail_timeout=30s;
}
<p>upstream v2_backend {
server 10.0.2.20:8080 max_fails=3 fail_timeout=30s;
server 10.0.2.21:8080 max_fails=3 fail_timeout=30s;
}</p>

这样 map 中的 "http://v1_backend" 才能正确解析为 upstream 组，而非字面 HTTP 地址。

验证与调试技巧

上线前建议通过 curl 测试不同 Header 的路由效果：

curl -H "X-API-Version: 1.0" http://api.example.com/users → 应打到 v1
curl -H "X-API-Version: 2.5" http://api.example.com/users → 应打到 v2（因匹配 ~^2\.）
curl http://api.example.com/users → 应走 default（v1_backend）

查看 Nginx 错误日志（error_log /var/log/nginx/error.log debug;）可确认 map 变量是否被正确计算。