nginx 的 map 指令是实现动态后端分配最轻量、高效且可维护的方式，支持基于域名、请求头、url 路径、查询参数及 http 方法等变量映射后端，需在 http 块顶层定义并设 default 值，配合 upstream 和 proxy_pass 完成精准路由。
Nginx 的 map 指令是实现动态后端分配最轻量、高效且可维护的方式。它不依赖 if 判断或重写逻辑，而是在请求处理早期将某个输入变量（如域名、路径、请求头、参数等）映射为一个目标后端标识，再由 proxy_pass 直接引用该变量完成转发。
基于域名（$host）动态选后端
适合多子域名共用同一 Nginx 实例的场景，比如 app1.example.com → 服务 A，api.example.com → 服务 B。
-
map必须写在http { }块顶层 - 使用
$host或$http_host（后者含端口，更严谨） - 每个值对应一个已定义的 upstream 名或直连地址
map $host $backend {
default "127.0.0.1:8001";
app1.example.com "127.0.0.1:8001";
app2.example.com "127.0.0.1:8002";
api.example.com "127.0.0.1:8003";
}
在 server 中使用：
location / {
proxy_pass http://$backend;
proxy_set_header Host $host;
}
基于请求头（如 $http_x_tenant_id）做灰度或租户路由
适用于按租户 ID、灰度标记等做精细化分流。
- 请求头名自动转为小写下划线格式：
X-Tenant-ID→$http_x_tenant_id - 支持字符串精确匹配和正则匹配（用
~开头） - 必须设
default，否则未匹配时变量为空，导致 502
map $http_x_tenant_id $backend_upstream {
default backend_default;
"tenant-a" backend_a;
"tenant-b" backend_b;
~^canary-.*$ backend_canary;
}
配套 upstream 声明（名称必须完全一致）：
upstream backend_default { server 10.0.1.10:8080; }
upstream backend_a { server 10.0.1.20:8080; }
upstream backend_canary { server 10.0.1.30:8080; }
转发时直接引用：
location / {
proxy_pass http://$backend_upstream;
}
基于 URL 路径（$uri）或查询参数（$arg_token）分流
-
$uri是解码后的路径（不含 query string），更安全；$request_uri含参数，适合带参路由 -
$arg_xxx可提取 GET 参数，如?token=abc123→$arg_token - 正则匹配需加
~，注意转义点号、括号等特殊字符
示例（按 token 分流）：
map $arg_token $backend_cluster {
default "default_backend";
"v1-release" "prod_v1";
"v2-beta" "beta_v2";
~^dev_[a-f0-9]{8}$ "dev_cluster";
}
基于 HTTP 方法实现读写分离
把 GET/HEAD/OPTIONS 发往只读集群，POST/PUT/DELETE 发往主写集群：
map $request_method $backend {
default "read_pool";
GET "read_pool";
HEAD "read_pool";
OPTIONS "read_pool";
POST "write_pool";
PUT "write_pool";
PATCH "write_pool";
DELETE "write_pool";
}
搭配 upstream 物理隔离：
upstream read_pool {
server 10.0.1.10:8080 weight=3;
server 10.0.1.11:8080 max_fails=2;
}
upstream write_pool {
server 10.0.1.20:8080;
}
转发时确保结尾带 /（避免路径拼接错误）：
location /api/ {
proxy_pass http://$backend/;
}
不复杂但容易忽略
