Nginx 模块配置中怎么配置 Map 模块实现复杂的条件变量映射-Nginx-PHP中文网

map模块是nginx内置模块，必须在http块顶层定义，用于将请求特征映射为全局变量，支持字面量、正则和default匹配，按顺序首匹配即止，常用于参数分流、动态路由和header注入。

nginx 模块配置中怎么配置 map 模块实现复杂的条件变量映射

Map 模块是 Nginx 内置的 ngx_http_map_module，无需额外编译或启用——只要标准安装就自带。它的核心作用不是直接控制请求流向，而是提前把请求特征（比如 URL、参数、Header）映射成一个可复用的变量，后续再由 if、proxy_pass、add_header 等指令消费。配置关键在于位置、语法顺序和变量生命周期。

必须写在 http 块里，不能嵌套在 server 或 location 中

map 指令只允许出现在 http{} 顶层作用域。如果误写进 server{} 或 location{}，Nginx 启动会报错：unknown directive "map"。这是因为 map 的变量解析发生在请求进入 server 处理前，属于“预处理阶段”，需要全局可见且提前加载。

正确位置：在 nginx.conf 的 http { ... } 区域内，通常放在 include mime.types; 之后、server { ... } 之前
变量名不带 $：定义时写 map $arg_version $backend_ver { ... }，目标变量名是 backend_ver，引用时才用 $backend_ver
所有 map 变量自动全局生效：一旦定义，所有 server 块都能直接使用 $backend_ver，无需重复声明

支持多种匹配方式，优先级从上到下，首匹配即止

map 不是“全部匹配”，而是按行顺序逐条判断，遇到第一个满足条件的规则就停止，后面规则不再检查。所以更精确的规则（如正则、具体字符串）要放在前面，通配或 default 放最后。

Nginx

在宝塔面板中轻松管理Nginx高性能Web服务器。提供可视化配置反向代理、负载均衡、SSL证书及HTTP缓存功能，一键优化高并发性能，助您高效搭建稳定、快速的网站运行环境。

下载

字面量匹配：直接写值，如 "v1" "cluster-a"，完全相等才命中
正则匹配：以 ~（区分大小写）或 ~*（不区分）开头，如 ~*^/api/v\d+/；支持捕获组 $1、$2，但只能在右侧值中引用，不能在 map 块内再用 $1 做二次判断
通配符 *：仅用于 hostnames 模式（需显式加 hostnames 参数），普通 map 不识别 * 通配
default 是兜底项：没有 default 且无匹配时，目标变量为空字符串，不是 null 或未定义

常用组合场景与写法示例

单一变量映射简单直接，但真实需求常需多维度交叉判断。map 本身不支持 if 嵌套，但可通过串联多个 map 实现“与”逻辑，例如先提取设备类型，再结合地区决定 CDN 节点。

按请求参数分流： map $arg_env $upstream_group { default "prod"; "dev" "dev-backend"; "staging" "staging-backend"; } 后续在 location 中用 proxy_pass http://$upstream_group;
结合 URI 和 Host 动态分组： map "$host:$request_uri" $route_key { default "default"; ~*^api.example.com:/v2/(admin|user)/ "v2-$1"; ~*^mobile.example.com:/.* "mobile"; } 注意拼接用双引号包裹，避免空格或特殊字符干扰
注入 Header 供后端识别： map $http_user_agent $device_type { default "desktop"; ~*android "mobile"; ~*iphone "mobile"; ~*windows.*phone "mobile"; } 然后在 server 块中：add_header X-Device-Type $device_type;