ngx_http_map_module模块概述-CSDN博客

本文链接：https://blog.csdn.net/weixin_43114209/article/details/147906609

一、模块概述

模块名称：ngx_http_map_module
引入版本：早期版本即有支持，0.9.0 起支持多个源变量，0.9.6 起支持正则，1.0.4 起支持不区分大小写正则，1.11.0 起映射值中可引用其它变量，1.11.7 起支持 volatile（禁用缓存）。
功能：声明一个 map 块，指定“源变量 → 目标变量”映射规则。只在目标变量真正被使用时才进行计算，无额外开销。
应用场景：根据 Host、User-Agent、请求 URI、Cookie 等信息，将一组可能的输入值映射为统一的内部标识、开关、分流标记等。

二、示例配置

# 按 Host 映射到不同的站点编号
map $http_host $site_id {
    hostnames;           # 启用通配符主机名匹配
    default   0;         # 未匹配时返回 0

    example.com   1;
    *.example.com 1;
    example.org   2;
    *.example.org 2;
    .example.net  3;     # 简写：前缀或后缀通配符
    wap.*         4;
}

# 按 User-Agent 判断是否为移动端
map $http_user_agent $is_mobile {
    default        0;            # 默认非移动
    "~Opera Mini"  1;            # 区分大小写正则
    "~*Mobile|Android" 2;        # 不区分大小写正则
}

三、核心指令

1. `map`

map <source> $<dest> {
    [hostnames];
    [volatile];
    [include <file>];

    [default  <value>];
    [<string>      <value>]
    [<pattern>     <value>]
    [~ <regex>     <value>]
    [~*<regex>     <value>];
}

上下文：http
功能：创建一个新变量 $<dest>，其值由 <source>（可为文本或变量）的不同取值决定。
参数说明：
- <source>：要映射的源，可以是普通字符串、变量或它们的组合（1.11.0+）。
- hostnames：启用主机名通配符（*.example.com、example.*、简写 .example.com）。
- volatile（1.11.7+）：禁用缓存，每次访问均重新计算。
- include <file>：载入外部文件，支持多次包含。
- default <value>：当所有规则均不匹配时的默认值（未指定时默认为空串）。
- <string> <value>：与源字符串忽略大小写精确匹配。
- ~ <regex> <value>：区分大小写正则匹配（0.9.6+）。
- ~* <regex> <value>：不区分大小写正则匹配（1.0.4+）。
匹配优先级（遇多重匹配时按以下顺序取第一项）：
1. 精确字符串（无通配符）
2. 前缀通配符（最长匹配，如 *.example.com）
3. 后缀通配符（最长匹配，如 mail.*）
4. 正则（按出现顺序）
5. default
性能：所有非正则映射都通过哈希表快速查询；正则仅在无哈希命中时按定义顺序逐一测试。

2. `map_hash_bucket_size`

map_hash_bucket_size <size>;

上下文：http
功能：设置用于存储 map 映射哈希表的桶大小（以字节计），通常为 CPU 缓存行大小（32/64/128）。
默认：自动根据处理器缓存行尺寸选择。
使用场景：极端高性能调优时可微调。

3. `map_hash_max_size`

map_hash_max_size <size>;

上下文：http
功能：设置哈希表的最大可用槽位数，决定最多可存储多少映射键。
默认：2048
说明：超过该值时会触发重建或扩容，需与 bucket_size 一同配置以获得最佳性能。

四、实践与注意事项

延迟计算
- Map 变量仅在被引用（如日志、下游模块使用）时才实际计算，对不使用的映射无运行时开销。
规则顺序
- 推荐将更常用或精确度更高的规则放在前面，以减少不必要的正则或通配符匹配。
文件包含
- 当映射规则很多时，可将 <key> <value> 行拆分到独立文件，通过多次 include 保持主配置简洁。

可组合变量

1.11.0+ 支持在映射值中引用其他变量，如：

map $arg_user $backend {
    ... 
    default  backend_$arg_user;  # 运行时拼接
}

缓存控制
- 对于频繁变动的源值，可使用 volatile 关闭缓存；大多数场景下不建议使用，因会增加哈希查找及正则匹配开销。
调优哈希表
- 对于大型映射表，可适当增大 map_hash_max_size 并调整 map_hash_bucket_size，以减少冲突和内存占用。