Nginx指令map在生产环境的应用实践

组件	说明	示例
源变量 (`$variable`)	输入的变量，通常是Nginx内置变量	`$http_user_agent`(客户端浏览器标识)
新变量 (`$new_variable`)	输出的变量，根据映射规则生成	`$device_type`(设备类型)
映射规则 (`{ ... }`)	定义源变量值如何映射到新变量值	`"~*android" "mobile";`(如果UA包含"android"，则映射为"mobile")
默认值 (`default`)	当无任何规则匹配时使用的值	`default "unknown";`

2. 基本语法与参数

map指令的基本语法如下：

map $source_variable $new_variable {
    key1    value1;
    key2    value2;
    ...     ...;
    default value_default;
}

它支持三个重要参数：

default：指定当没有匹配项时使用的默认值。
hostnames：允许使用通配符（如 *.example.com）来匹配域名，此参数必须放在映射列表的最前面。
include：允许引入外部文件，便于管理大量的映射规则。

3. 匹配优先级

当源变量可能匹配多个规则时，Nginx 会按照以下优先级顺序选择第一个匹配的值：

精确字符串匹配（无通配符）
最长的前缀通配符匹配（例如 *.example.com）
最长的后缀通配符匹配（例如 mail.*）
按配置顺序的第一个正则表达式匹配
默认值 default

二. 关键特性与最佳实践

作用域与性能：map指令只能配置在 http块内 。它的一个重要性能优势是延迟计算，即只有在配置中实际使用了 $new_variable时，映射操作才会执行，对未使用该变量的请求没有性能开销。
规则顺序：由于正则匹配按配置顺序进行，建议将最常用或最精确的匹配条件放在前面，以提高效率。
谨慎使用正则表达式：虽然功能强大，但复杂的正则表达式可能影响性能，请合理使用。

三. 生产环境实战案例汇总

1. 流量调度与路由

基于源IP的路由与灰度发布：将特定来源IP的请求导向新版本服务器进行验证。

map $remote_addr $backend_svr {
    "27.38.x.255" "new_gateway";
    "116.30.x.170" "new_gateway";
    default       "old_gateway";
}
# 在 server 或 location 块中：proxy_pass http://$backend_svr;

基于Cookie的多环境分流：通过Cookie（如cl_env_num=test-14）将测试流量分发到不同的后端环境。

map $cookie_cl_env_num $cl_backend_map {
    default    "1.1.1.1:80";
    test-14    upstream_test-14;
    # ... 其他环境映射
}
upstream upstream_test-14 {
    server 2.2.2.2:80;
}

2. 请求过滤与权限控制

限速白名单：结合 geo和 map指令，对非白名单IP进行限速。

geo $whiteiplist {
    default 1;
    127.0.0.1 0;
    10.0.0.0/8 0;
}
map $whiteiplist $limit {
    1 $binary_remote_addr; # 受限客户端用其IP作为限速键
    0 "";                  # 白名单IP限速键为空，不受限制
}
# 在 location 块中：limit_req_zone $limit zone=rate_limit:10m rate=1r/s;

基于参数的访问控制：例如，若请求参数中不包含有效的uin，则返回403 。

map $cookie_uin $limit_key {
    default  0;
    ""       1;  # uin 为空时设置限制标志
    "-"      1;  # uin 为减号时设置限制标志
}
# 在 location 块中：if ($limit_key = 1) { return 403; }

3. 请求头处理与上下文传递

设备类型识别：根据User-Agent判断设备类型，并将信息传递给后端服务。

map $http_user_agent $device_type {
    "~*iphone"  "ios";
    "~*android" "android";
    default     "pc";
}
# 在代理位置中：proxy_set_header X-Device-Type $device_type;

环境识别：根据访问的域名（Host）自动识别并传递当前环境（测试或生产）。

map $host $env {
    "test.example.com" "test";
    "prod.example.com" "prod";
    default            "unknown";
}
# 在代理位置中：proxy_set_header X-Env $env;

安全的动态跨域配置：根据请求来源动态设置允许跨域的域名，比通配符*更安全。

map $http_origin $allow_origin {
    "~http://www.example.com" "http://www.example.com";
    "~http://m.example.com"   "http://m.example.com";
    default                   "deny";
}
# 在 location 块中：add_header Access-Control-Allow-Origin $allow_origin;

4. 日志优化与调试

条件日志记录：避免记录静态资源等不必要的请求日志，减少磁盘I/O 。

map $request_uri $loggable {
    "~^/api/"   1; # 记录API请求
    "~^/static/" 0; # 不记录静态资源请求
    default      1;
}
# 在 server 或 http 块中：access_log /var/log/nginx/access.log combined if=$loggable;

四. 进阶技巧与注意事项

动态配置的局限与解决方案：标准的Nginx map指令是静态配置，修改后需要重载配置(nginx -s reload)才能生效。如果业务场景需要极高的动态性（如映射关系频繁变化），可以考虑基于Nginx的增强版本（如OpenNJet），它们提供了API支持动态更新映射关系，而无需重启服务。
常见误区：
- 在map块内部，不能直接引用在正则表达式中定义的命名捕获变量（如$1），否则会报unknown variable错误。
- 如果源变量的值包含特殊字符（如~），需要使用``进行转义。