Nginx Map模块配置与使用指南

什么是Nginx Map模块

Nginx的map模块(ngx_http_map_module)允许您创建变量映射，根据一个变量的值来定义另一个变量的值。这是一个非常强大的功能，可以用于重定向、条件配置、请求处理等多种场景。

基本配置语法

map $variable_to_check $new_variable {
    default   default_value;
    value1    result1;
    value2    result2;
    ...
    ~regex    regex_result;
}

典型使用场景

1. 基本键值映射

map $http_host $site_root {
    default       /var/www/default;
    example.com   /var/www/example;
    test.com      /var/www/test;
}

2. 正则表达式匹配

map $uri $is_static {
    default       0;
    ~*\.(jpg|png|css|js)$  1;
}

3. 多条件映射

map $arg_show $show_debug {
    default     0;
    ""          0;
    "true"      1;
    "1"         1;
    "on"        1;
    "yes"       1;
}

实际应用示例

示例1：根据用户IP设置不同限制

map $remote_addr $limit {
    default          "";
    192.168.1.1      "";
    10.0.0.0/8       $binary_remote_addr;
}

limit_req_zone $limit zone=mylimit:10m rate=10r/s;

示例2：根据User-Agent重定向

map $http_user_agent $redirect_uri {
    default                "";
    "~*MSIE [1-6]\."      "/upgrade-browser.html";
    "~*Android.*Chrome"   "/android-chrome.html";
}

示例3：简化复杂的if条件

map $request_method $is_write_method {
    default       0;
    POST          1;
    PUT           1;
    DELETE        1;
    PATCH         1;
}

server {
    if ($is_write_method) {
        # 处理写请求的逻辑
    }
}

高级用法

1. 包含外部映射文件

map $http_host $backend {
    include /etc/nginx/conf.d/host-backend.map;
}

host-backend.map文件内容：

example.com    backend1;
test.com      backend2;

2. 嵌套map使用

map $http_cookie $session_id {
    default     "";
    "~*sessionid=(?<session>[a-zA-Z0-9]+)"  $session;
}

map $session_id $user_role {
    default     "guest";
    "admin123"  "admin";
    "user456"   "user";
}

3. 使用变量作为map的输入

map $http_x_forwarded_for $real_ip {
    default         $remote_addr;
    "~^(\d+\.\d+\.\d+\.\d+)"  $1;
}

性能优化建议

1. 将map放在http块中：这样map只会在Nginx启动时编译一次，而不是每个请求都编译
2. 合理使用正则表达式：简单的字符串匹配比正则表达式更高效
3. 限制映射数量：过多的映射项会影响性能
4. 使用default值：确保所有情况都有返回值

常见问题解决

问题1：map不生效

• 检查map块是否放在http上下文中
• 确保引用的变量名正确
• 验证default值是否设置

问题2：正则表达式不匹配

• 使用~区分大小写匹配，~*不区分大小写
• 确保正则语法正确
• 考虑使用capture groups提取特定部分

问题3：变量值为空

• 检查输入变量是否确实有值
• 确保没有语法错误
• 添加debug日志查看变量值

总结

Nginx的map模块是一个非常灵活的工具，可以大大简化配置复杂度，提高配置的可读性和维护性。通过合理使用map，您可以实现复杂的条件逻辑而无需使用多个if语句，这在Nginx配置中是非常重要的性能优化手段。