nginx map指令需置于http块顶层，实现单输入首匹配的全局变量映射；支持$arg_xxx、$http_xxx等源变量，配合proxy_pass等指令可实现动态路由、请求标记与访问控制。
配置 Nginx 的 map 指令实现变量映射，核心是理解它“预处理、单输入、首匹配、全局生效”的行为特征。它不执行动作，只产出变量；不能写在 server 或 location 里，也不能嵌套逻辑，但配合其他指令就能支撑分流、标记、路由等关键场景。
必须放在 http 块顶层
map 只允许出现在 http { } 区域内，通常加在 include mime.types; 后、server { } 前。写错位置会直接报错：unknown directive "map"。
- 正确示例：
http {<br> include mime.types;<br> map $arg_env $upstream_group {<br> default "prod";<br> "dev" "dev-backend";<br> }<br> server { ... }<br>} - 目标变量名不带
$：定义时写map $arg_env $upstream_group，引用时才用$upstream_group - 所有 map 定义的变量自动全局可见，任意 server 或 location 都可直接使用
匹配规则按顺序首中即止
map 不是“全量匹配”，而是从上到下逐行判断，遇到第一个满足条件的规则就立即赋值，后续规则不再检查。因此顺序很关键。
- 精确字符串（如
"v1"）放前面 - 正则表达式用
~（区分大小写）或~*（不区分），如~*^/api/v\d+/ - 捕获组（如
(?<ver>v\d+)</ver>）可在右侧值中用$ver引用，但不能在 map 内部再次用于条件判断 - 通配符
*在普通 map 中无效；如需域名通配，得加hostnames参数且只能用于$host类变量 - 务必设置
default，否则无匹配时变量为空字符串，容易引发 proxy_pass 解析失败等问题
常用源变量与典型用途
map 的能力取决于你选哪个内置变量作为输入。常见可靠源变量包括：
-
$arg_xxx：提取 URL 参数，如$arg_version、$arg_token -
$http_xxx：读取请求头，如$http_user_agent、$http_referer、$http_x_region -
$cookie_xxx：读取 Cookie 值，如$cookie_session_id -
$realip_remote_addr：经set_real_ip_from还原后的客户端真实 IP，适合做地域/内外网分类 -
$host:$request_uri：拼接复合键，用于路径+域名联合判断（注意加引号）
组合其他指令扩展能力
map 本身不做重写、不校验类型、不调用外部数据，但可以和 set、if、proxy_pass、add_header 等自然衔接：
- 在 location 中用
proxy_pass http://$upstream_group;实现后端动态路由 - 用
add_header X-Route $upstream_group;注入调试信息到响应头 - 配合
if ($upstream_group = "dev-backend") { return 403; }做简单访问控制（注意 if 在 location 中才安全） - 多维逻辑靠串联 map：先用一个 map 根据
$host输出策略组名，再用另一个 map 结合$uri和该组名做二级映射
