Nginx 可通过 map 指令结合 $arg_* 或 $args 实现基于 query string 的动态 upstream 路由，推荐使用 map 而非 if+set，因其声明式、高性能且线程安全。
可以通过 Nginx 的 map 指令将请求 URL 中的 query string 参数提取并映射为变量，再结合 proxy_pass 实现动态 upstream 路由。关键在于用 $args 或更精确的 $arg_* 获取参数，并确保 map 块在 http 块中定义、变量作用域正确。
使用 $arg_* 直接匹配单个参数
当路由仅依赖一个明确的 query 参数（如 ?env=prod）时，直接用内置变量 $arg_env 最简洁。Nginx 会自动解析所有 query 参数为 $arg_ 变量，值为空字符串表示参数不存在。
示例配置：
http {
# 定义 upstream 分组
upstream backend_prod {
server 10.0.1.10:8080;
}
upstream backend_staging {
server 10.0.2.20:8080;
}
upstream backend_dev {
server 10.0.3.30:8080;
}
<pre class="brush:php;toolbar:false;"># 利用 $arg_env 映射目标 upstream 名称
map $arg_env $backend_upstream {
default backend_prod;
"prod" backend_prod;
"staging" backend_staging;
"dev" backend_dev;
}
server {
listen 80;
location /api/ {
proxy_pass http://$backend_upstream;
proxy_set_header Host $host;
}
}
}
访问 /api/?env=staging 就会转发到 backend_staging。注意：map 值必须是合法的 upstream 名称，不能带协议或端口。
从 $args 提取复杂参数组合
若需基于多个参数联合判断（如 ?region=cn&version=v2），$arg_* 不够灵活，可改用 $args（完整 query string）配合正则匹配。
示例：按 region + version 组合选择 upstream
map $args $backend_upstream {
default backend_prod;
<pre class="brush:php;toolbar:false;">~*region=cn(&|$).*version=v1 backend_cn_v1;
~*region=cn(&|$).*version=v2 backend_cn_v2;
~*region=us(&|$).*version=v1 backend_us_v1;
~*region=us(&|$).*version=v2 backend_us_v2;
}
upstream backend_cn_v1 { server 192.168.1.100:8080; } upstream backend_cn_v2 { server 192.168.1.101:8080; } upstream backend_us_v1 { server 192.168.2.100:8080; } upstream backend_us_v2 { server 192.168.2.101:8080; }
说明：
- 正则中的
~*表示不区分大小写匹配 -
(&|$)确保参数边界准确（避免region=cnabc被误匹配） - 顺序重要：先写更具体的规则，避免被 default 或宽泛规则覆盖
安全与健壮性建议
动态路由易受恶意参数干扰，需主动防御：
- 拒绝非法参数值：在 map 中显式列出允许值，未匹配项走 default（如 fallback upstream 或返回 400）
-
限制参数长度和字符集：可用
if ($arg_env ~ "[^a-z0-9_-]") { return 400; }预检（注意 if 在 location 中慎用，优先用 map+正则） -
避免空 upstream 引发 502：default 必须指向一个真实存在的 upstream；或用
proxy_next_upstream error timeout增强容错 -
调试技巧：临时加
add_header X-Upstream $backend_upstream;查看实际路由结果
替代方案对比：set + if vs map
有人倾向用 set 和 if 在 location 内做判断，但这是反模式：
-
if在 location 中不可嵌套，逻辑复杂时难以维护 -
set无法在 if 块外赋值，变量作用域受限 -
map是声明式、无副作用、线程安全的，且在 server 启动时预编译，性能更好
因此，只要涉及基于变量的条件映射，map 是 Nginx 官方推荐且最可靠的方式。
