<!-- review: finished -->

<a id="http-charset"></a>

# Charset

该模块将指定的字符集添加到:samp:Content-Type 响应头字段。此外，该模块可以在某些限制条件下将数据从一种字符集转换为另一种字符集：

* 转换是单向进行的——从服务器到客户端，
* 只能转换单字节字符集，
* 或单字节字符集与 UTF-8 之间的转换。

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

## 配置示例

```nginx
include        conf/koi-win;

charset        windows-1251;
source_charset koi8-r;
```

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

## 指令

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

<a id="id3"></a>

### charset

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `charset` charset | `off`;             |
|--------------------------------------------------------------------------------------|----------------------------------------|
| 默认                                                                                   | `charset off;`                         |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

将指定的字符集添加到:samp:Content-Type 响应头字段。如果该字符集与 [source_charset](#source-charset) 指令中指定的字符集不同，则会执行转换。

参数 `off` 取消将字符集添加到:samp:Content-Type 响应头字段。

字符集可以通过变量定义：

```nginx
charset $charset;
```

在这种情况下，变量的所有可能值必须至少在配置中以 [charset_map](#charset-map)、[charset](#id3) 或 [source_charset](#source-charset) 指令的形式出现一次。对于 `utf-8`、`windows-1251` 和 `koi8-r` 字符集，只需在配置中包含 `conf/koi-win`、`conf/koi-utf` 和 `conf/win-utf` 文件。对于其他字符集，只需创建一个虚构的转换表即可，例如：

```nginx
charset_map iso-8859-5 _ { }
```

此外，可以在:samp:X-Accel-Charset\`响应头字段中设置字符集。可以使用 :ref:\`proxy_ignore_headers、[fastcgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-ignore-headers)、[uwsgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-ignore-headers)、[scgi_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-ignore-headers) 和 [grpc_ignore_headers](https://cn.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-ignore-headers) 指令禁用此功能。

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

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

### charset_map

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `charset_map` charset1 charset2  { ... }   |
|--------------------------------------------------------------------------------------|--------------------------------------------|
| 默认                                                                                   | —                                          |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                                       |

描述从一种字符集到另一种字符集的转换表。使用相同的数据构建反向转换表。字符编码以十六进制给出。在范围 80-FF 中缺失的字符用 "?" 替代。从 UTF-8 转换时，在单字节字符集中缺失的字符用 "&#XXXX;" 替代。

示例：

```nginx
charset_map koi8-r windows-1251 {
    C0 FE ; # 小 ю
    C1 E0 ; # 小 а
    C2 E1 ; # 小 б
    C3 F6 ; # 小 ц
}
```

在描述到 UTF-8 的转换表时，UTF-8 字符集的代码应在第二列给出，例如：

```nginx
charset_map koi8-r utf-8 {
    C0 D18E ; # 小 ю
    C1 D0B0 ; # 小 а
    C2 D0B1 ; # 小 б
    C3 D186 ; # 小 ц
}
```

从 `koi8-r` 到 `windows-1251`，以及从 `koi8-r` 和 `windows-1251` 到 `utf-8` 的完整转换表在分发文件 `conf/koi-win`、`conf/koi-utf` 和 `conf/win-utf` 中提供。

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

<a id="charset-types"></a>

### charset_types

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `charset_types` mime-type ...;                                                                             |
|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
| 默认                                                                                   | `charset_types text/html text/xml text/plain text/vnd.wap.wml application/javascript application/rss+xml;` |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location                                                                                     |

使模块在处理指定 MIME 类型的响应时生效，除了 `text/html` 之外。特殊值 `*` 匹配任何 MIME 类型。

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

<a id="override-charset"></a>

### override_charset

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `override_charset` `on` | `off`;       |
|--------------------------------------------------------------------------------------|----------------------------------------|
| 默认                                                                                   | `override_charset off;`                |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

确定是否应对从代理或 FastCGI/uwsgi/SCGI/gRPC 服务器接收到的响应进行转换，当这些响应已在:samp:Content-Type 响应头字段中携带字符集时。如果启用转换，则使用接收到的响应中指定的字符集作为源字符集。

#### NOTE
如果在子请求中收到响应，则始终会将响应字符集转换为主请求字符集，而不管 override_charset 指令的设置。

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

<a id="source-charset"></a>

### source_charset

| [语法](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)   | `source_charset` charset;              |
|--------------------------------------------------------------------------------------|----------------------------------------|
| 默认                                                                                   | —                                      |
| [上下文](https://cn.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server, location, if in location |

定义响应的源字符集。如果该字符集与 [charset](#id3) 指令中指定的字符集不同，则会执行转换。