<!-- review: finished -->

<a id="stream-map"></a>

# Map

创建的变量，其值依赖于其他变量的值。

<a id="configuration-example-62"></a>

## 配置示例

```nginx
map $remote_addr $limit {
    127.0.0.1    "";
    default      $binary_remote_addr;
}

limit_conn_zone $limit zone=addr:10m;
limit_conn addr 1;
```

<a id="directives-71"></a>

## 指令

<a id="index-0"></a>

<a id="s-map"></a>

### map

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map` string $variable { ... };   |
|--------------------------------------------------------------------------------------|-----------------------------------|
| 默认值                                                                                  | —                                 |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                            |

创建一个新变量。其值依赖于第一个参数，该参数以包含变量的字符串形式指定，例如：

```nginx
set $var1 "foo";
set $var2 "bar";

map $var1$var2 $new_variable {
    default "foobar_value";
}
```

在这里，变量 `$new_variable` 的值将由两个变量 `$var1` 和 `$var2` 组成，或者如果这些变量未定义，则使用默认值。

#### NOTE
由于变量仅在使用时才会被求值，即使声明了大量的"map"变量也不会对请求处理增加额外的成本。

`map` 块内的参数指定源值与结果值之间的映射关系。

源值以字符串或正则表达式的形式指定。

字符串匹配时不区分大小写。

正则表达式应以 `~` 符号开头以进行区分大小写的匹配，或以 `~*` 符号开头以进行不区分大小写的匹配。正则表达式可以包含命名和位置捕获，后者可以与结果变量一起在其他指令中使用。

如果源值与下面描述的特殊参数之一匹配，则应以 `\` 符号作为前缀。

结果值可以包含文本、变量及其组合。

还支持以下特殊参数：

| `default` value   | 如果源值与指定的变体都不匹配，则设置结果值。当未指定 default 时，默认结果值将为空字符串。   |
|-------------------|-----------------------------------------------------|
| `hostnames`       | 指示源值可以是带有前缀或后缀掩码的主机名。此参数应在值列表之前指定。                  |

例如，

```nginx
*.example.com 1;
example.*     1;
```

以下两条记录

```nginx
example.com   1;
*.example.com 1;
```

可以合并为：

```nginx
.example.com  1;
```

| `include` file   | 包含一个文件，其中包含值。可以有多个包含。   |
|------------------|-------------------------|
| `volatile`       | 指示变量不可缓存。               |

如果源值与多个指定的变体匹配，例如掩码和正则表达式都匹配，则将选择第一个匹配的变体，优先级顺序如下：

1. 没有掩码的字符串值
2. 带前缀掩码的最长字符串值，例如 `*.example.com`
3. 带后缀掩码的最长字符串值，例如 `mail.*`
4. 第一个匹配的正则表达式（按在配置文件中的出现顺序）
5. 默认值（`default`）

<a id="index-1"></a>

<a id="s-map-hash-bucket-size"></a>

### map_hash_bucket_size

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map_hash_bucket_size` size;      |
|--------------------------------------------------------------------------------------|-----------------------------------|
| 默认值                                                                                  | `map_hash_bucket_size 32|64|128;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                            |

设置 [map](#s-map) 变量哈希表的桶大小。默认值取决于处理器的缓存行大小。有关设置哈希表的详细信息，请参见 [单独](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。

<a id="index-2"></a>

<a id="s-map-hash-max-size"></a>

### map_hash_max_size

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map_hash_max_size` size;   |
|--------------------------------------------------------------------------------------|-----------------------------|
| 默认值                                                                                  | `map_hash_max_size 2048;`   |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                      |

设置 [map](#s-map) 变量哈希表的最大大小。有关设置哈希表的详细信息，请参见 [单独](https://cn.angie.software//angie/docs/configuration/configfile.md#configure-hashes)。