nginx 动态路由需 map 提取特征、预定义 upstream 分组、location 中用变量驱动 proxy_pass;map 必须在 http 块顶层,proxy_pass 需写为 http://$upstream_name/ 形式,并设 default 值防 502。

在 Nginx 中用变量实现后端节点的动态路由,关键不是写死 upstream 名称,而是让 proxy_pass 的目标能随请求上下文实时变化——这依赖 map 提前提取特征、upstream 预定义分组、以及 location 中用变量驱动转发三者配合。
用 map 提取并映射路由判据
map 指令在请求解析早期执行,开销极低,适合做轻量级路由决策。它能把任意请求头、参数、甚至空值,映射为一个确定字符串变量,供后续 proxy_pass 使用。
- 按自定义标头分流:比如读取
X-Env决定走哪个集群 - 支持嵌套降级逻辑:先看
X-Canary-ID是否存在,再 fallback 到User-Agent - 必须设置
default值,否则未匹配时变量为空,proxy_pass $upstream_name会失败返回 502 - 映射结果需与
upstream名完全一致(建议全小写+下划线,避免大小写或拼写差异)
定义多个 upstream 实现逻辑隔离
每个 upstream 块代表一个独立后端集群,可配置差异化策略,互不影响:
- 开发集群可加 IP 白名单、详细日志,不参与生产流量
- 灰度集群用
weight控制流量比例,例如 8:2 分流 - 生产集群启用
slow_start和keepalive,提升稳定性与复用率 - 所有
server行都可带max_fails和fail_timeout,实现基础故障剔除
在 location 中完成变量代理与路径重写
proxy_pass 必须写成 http://$upstream_name/ 形式(带协议前缀和结尾斜杠),Nginx 才能识别为变量转发;同时可在转发前用 rewrite 或 proxy_set_header 调整 URI 或注入上下文。
- 路径重写常用于标准化入口,比如把
/api/v1/user改成/user再转发 - 可结合
proxy_set_header X-Route-To $upstream_name,方便后端记录路由路径 - 若需 fallback 行为(如主集群不可用时切到备用),需额外配
proxy_next_upstream+backupserver
注意变量作用域与生效时机
map 块必须放在 http 块顶层,不能嵌套在 server 或 location 内;变量一旦被 map 定义,即可在任意 location 中引用。但变量值在请求进入时即确定,不会在 rewrite 后重新计算——如需基于重写后的 URI 路由,应把判断逻辑前置或改用 Lua。











