map指令必须在http块顶层定义，不能放server或location中；它基于源变量值映射新变量，供proxy_pass等指令使用，匹配从上到下、首个成功即终止，且必须设default分支。
map 指令必须在 http 块顶层定义，不能放在 server 或 location 里
这是最常踩的坑：很多人把 map 写进 server 块里，Nginx 启动直接报错 unknown directive "map"。因为 map 是变量映射指令，属于变量预处理阶段，只允许出现在 http 上下文中。
正确做法是打开 /etc/nginx/nginx.conf（或你 include 的全局配置文件），在 http { ... } 块内顶部附近添加：
map $arg_token $backend_cluster {
default "default_backend";
"~^dev_[a-f0-9]{8}$" "dev_cluster";
"~^staging_[a-z0-9]{6}$" "staging_cluster";
"abc123" "canary_v1";
"xyz789" "canary_v2";
}
注意几点：
-
$arg_token是 Nginx 内置变量，自动提取 URL 查询参数中的token（即?token=xxx） - 匹配顺序从上到下，第一个匹配成功即终止；
default必须存在，否则未匹配时变量为空，可能导致 upstream 名非法 - 正则匹配必须用
~^开头（区分大小写），~*^才不区分；正则中不能有空格，否则语法错误 - 右侧值是纯字符串，不是引用 upstream 名——它只是给后续
proxy_pass提供一个变量值
upstream 块名必须和 map 输出值严格一致
map 输出的是字符串，而 proxy_pass 要求后端目标是合法的 upstream 名或地址。如果你写 proxy_pass http://$backend_cluster;，那 $backend_cluster 的值就必须是已定义的 upstream 块名。
所以必须提前在 http 块里声明对应 upstream：
upstream default_backend {
server 10.0.1.10:8080;
server 10.0.1.11:8080;
}
<p>upstream dev_cluster {
server 10.0.2.5:8080;
}</p><p>upstream staging_cluster {
server 10.0.3.20:8080 weight=3;
server 10.0.3.21:8080;
}</p><p>upstream canary_v1 {
server 10.0.4.100:8080;
}</p><p>upstream canary_v2 {
server 10.0.4.101:8080;
}</p>
关键细节：
- upstream 名不能含短横线（
-）或下划线以外的符号；但map输出值可以含下划线（如dev_cluster），只要和 upstream 名完全一致即可 - 如果误把
proxy_pass http://$backend_cluster/;指向一个未定义的 upstream（比如拼错成dev_cluser），Nginx 不会启动，报错invalid number of arguments in "proxy_pass" directive或更隐蔽的no resolver defined（因尝试 DNS 解析该字符串） - 不建议在
map中输出 IP+端口（如"10.0.2.5:8080"），那样就绕过了 upstream 的健康检查、负载均衡等能力
location 中 proxy_pass 必须用变量且不带 URI 后缀
分流生效的关键一步是让 proxy_pass 真正使用变量。常见错误是：
- 写成
proxy_pass http://$backend_cluster/;—— 末尾斜杠会触发 URI 重写，导致后端收到的 path 被截断 - 写成
proxy_pass http://$backend_cluster$request_uri;—— 这样虽能透传，但会破坏 Nginx 的请求体缓存与代理缓冲逻辑，且无法利用 upstream 的 keepalive
正确写法只有一个：
server {
listen 80;
server_name api.example.com;
<pre class="brush:php;toolbar:false;">location / {
proxy_pass http://$backend_cluster;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# 其他必要 header...
}}
说明：
- 必须不带路径后缀（即不能有
/或/api），否则 Nginx 会按 rewrite 规则处理，不再走 upstream 分流逻辑 - 变量形式的
proxy_pass会自动继承当前 location 的 URI，无需手动拼接$request_uri - 所有 upstream 都要配置一致的
keepalive和max_conns，否则高并发下容易出现连接耗尽
调试 map 匹配结果要用 log_format + $backend_cluster 变量
线上分流不生效？别急着改配置，先确认 map 是否真的命中了。Nginx 不提供 map 调试开关，但你可以把它打到 access log 里看：
log_format debug_log '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'token="$arg_token" cluster="$backend_cluster"';
<p>access_log /var/log/nginx/debug.log debug_log;</p>
然后 curl 测试：
curl 'http://api.example.com/?token=abc123'
查日志就能看到真实匹配结果：
127.0.0.1 - - [10/Jul/2024:14:22:33 +0800] "GET /?token=abc123 HTTP/1.1" 200 123 "-" "curl/7.68.0" token="abc123" cluster="canary_v1"
常见干扰点：
-
$arg_token对大小写敏感，?TOKEN=abc不会命中（Nginx 默认只认小写参数名） - 如果用了
rewrite或try_files提前改变了请求，$arg_token可能被覆盖或清空 - 浏览器或代理可能缓存了 301/302 重定向，导致你以为没生效，其实是旧响应被缓存了——务必加
curl -v看真实响应头
真正难的不是写对语法，而是确保整个请求链路里没有其他模块篡改了 $arg_token 或 $backend_cluster 的值。每次加新模块（比如 auth_request、lua-resty-waf），都要重新验证日志输出。
