Nginx的map指令可基于请求头动态生成变量实现后端路由分流；需定义在http块中，支持正则匹配、多头组合、嵌套map及default兜底，配合proxy_pass轻量高效完成灰度与环境路由。

Nginx 的 map 指令能根据请求头（如 User-Agent、Authorization、自定义 Header）动态生成变量，再结合 proxy_pass 实现后端路由分流——无需重写逻辑，轻量高效。

一、基础语法：用 map 提取并映射请求头值

map 必须定义在 http 块中，不能放在 server 或 location 内。它将源变量（如 $http_x_backend_route）按规则映射为新变量（如 $backend_upstream）：

示例：根据自定义请求头 X-Backend-Route 路由到不同 upstream

http {
    map $http_x_backend_route $backend_upstream {
        default                backend_default;
        "v2"                   backend_v2;
        "legacy"               backend_legacy;
        ~^canary-\d+\.\d+$     backend_canary;
    }
<pre class="brush:php;toolbar:false;">upstream backend_default { server 10.0.1.10:8080; }
upstream backend_v2      { server 10.0.1.20:8080; }
upstream backend_legacy  { server 10.0.1.30:8080; }
upstream backend_canary  { server 10.0.1.40:8080; }

server {
    listen 80;
    location / {
        proxy_pass http://$backend_upstream;
        proxy_set_header Host $host;
    }
}

}

二、匹配多种请求头：组合使用 $http_* 变量

可同时读取多个请求头，用空格分隔或嵌套 map。常见组合方式：

Skill Weave Chains — 技能链路由引擎

开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。

下载

• 优先匹配 X-Env，缺失时 fallback 到 User-Agent 中的关键词
• 用正则捕获版本号：~*Mozilla.*Firefox/(\d+)\. → 提取主版本用于路由
• 大小写不敏感匹配：用 ~* 开头，如 ~*mobile 匹配 Mobile 或 mobile

注意：$http_ 后接小写带下划线的 header 名（如 X-Api-Key → $http_x_api_key）

三、安全与健壮性处理

避免因非法输入导致路由失败或暴露内部结构：

• 始终设置 default 值，防止未匹配时变量为空引发 502
• 对敏感 header（如 Authorization）做白名单校验，不直接用于路由，建议先用 map 解析 token 类型再决策
• 禁用空格/换行等非法字符干扰：Nginx 自动忽略 header 中的前后空格，但建议在应用层清洗
• 测试时用 curl -H "X-Backend-Route: v2" http://example.com 验证路由是否生效

四、进阶技巧：多级 map 与条件组合

单个 map 不支持“且”逻辑，可通过嵌套 map 实现组合判断：

map $http_x_env $env_level {
    dev     1;
    staging 2;
    prod    3;
    default 0;
}
<p>map $http_user_agent $ua_type {
~<em>mobile  mobile;
~</em>tablet  tablet;
default   desktop;
}</p><p>map "$env_level:$ua_type" $final_backend {
"1:mobile"   backend_dev_mobile;
"2:mobile"   backend_staging_mobile;
"3:desktop"  backend_prod_web;
default      backend_default;
}</p>

关键点："$env_level:$ua_type" 将两个变量拼成复合键，实现二维路由策略。