# ngx\_http\_charset\_module

* [示例配置](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#example_configuration)
* [指令](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#directives)
  * [charset](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#charset)
  * [charset\_map](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#charset_map)
  * [charset\_types](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#charset_types)
  * [override\_charset](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#override_charset)
  * [source\_charset](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#source_charset)

`ngx_http_charset_module` 模块将指定的字符集添加到 **Content-Type** 响应头域。此外，该模块可以将数据从一个字符集转换为另一个字符集，但也存在一些限制：

* 转换工作只能是从服务器到客户端
* 只能转换单字节字符集
* 或转为/来自 UTF-8 的单字节字符集。

## 示例配置 <a href="#example_configuration" id="example_configuration"></a>

```
include        conf/koi-win;

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

## 指令 <a href="#directives" id="directives"></a>

### charset

| -       | 说明                                  |
| ------- | ----------------------------------- |
| **语法**  | **charset** `charset` \| `off`;     |
| **默认**  | charset off;                        |
| **上下文** | http、server、location、location 中的 if |

将指定的字符集添加到 **Content-Type** 响应头域。如果此字符集与 [source\_charset](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#source_charset) 指令指定的字符集不同，则执行转换。

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

可以使用一个变量来定义字符集：

```
charset $charset;
```

在这种情况下，变量的值至少要在 [charset\_map](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#charset_map)、[charset](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#charset) 或 [source\_charset](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#source_charset) 其中一个指令配置一次。对于 `utf-8`、`windows-1251` 和 `koi8-r` 字符集，将 `conf/koi-win`、`conf/koi-utf` 和 `conf/win-utf` 文件包含到配置中就足够了。对于其他字符集，只需制作一个虚构的转换表即可，例如：

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

另外，可以在 **X-Accel-Charset** 响应头域中设置一个字符集。可以使用[proxy\_ignore\_headers](/nginx-docs/he-xin-gong-neng/http/ngx_http_proxy_module.md#proxy_ignore_headers)、[fastcgi\_ignore\_headers](/nginx-docs/he-xin-gong-neng/http/ngx_http_fastcgi_module.md#fastcgi_ignore_headers)、[uwsgi\_ignore\_headers](/nginx-docs/he-xin-gong-neng/http/ngx_http_uwsgi_module.md#uwsgi_ignore_headers) 和 [scgi\_ignore\_headers](/nginx-docs/he-xin-gong-neng/http/ngx_http_scgi_module.md#scgi_ignore_headers) 指令禁用此功能。

### charset\_map

| -       | 说明                                            |
| ------- | --------------------------------------------- |
| **语法**  | **charset\_map** `charset1 charset2 { ... }`; |
| **默认**  | ——                                            |
| **上下文** | http                                          |

描述转换表，将一个字符集转换到另一个字符集。反向转换表也使用相同的数据构建。字符代码是十六进制格式。不在 80-FF 范围内的字符将被替换为 `?`。当从 UTF-8 转换时，一个字节字符集中丢失的字符将被替换为 `&#XXXX;`。

示例：

```
charset_map koi8-r windows-1251 {
    C0 FE ; # small yu
    C1 E0 ; # small a
    C2 E1 ; # small b
    C3 F6 ; # small ts
    ...
}
```

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

```
charset_map koi8-r utf-8 {
    C0 D18E ; # small yu
    C1 D0B0 ; # small a
    C2 D0B1 ; # small b
    C3 D186 ; # small ts
    ...
}
```

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

### charset\_types

| -      | 说明                                                            |
| ------ | ------------------------------------------------------------- |
| **语法** | **charset\_types** `mime-type ...`;                           |
| **默认** | charset\_types text/html text/xml text/plain text/vnd.wap.wml |

application/javascript application/rss+xml;| |**上下文**|http、server、location| |**提示**|该指令在 0.7.9 版本中出现|

除了 `text/html` 之外，还可以使用指定了 MIME 类型的响应中的模块处理。特殊值 `*` 可匹配任何 MIME 类型（0.8.29）。

> 直到 1.5.4 版本，`application/x-javascript` 被作为默认的 MIME 类型，而不是`application/javascript`。

### override\_charset

| -       | 说明                                   |
| ------- | ------------------------------------ |
| **语法**  | **override\_charset** `on` \| `off`; |
| **默认**  | override\_charset off;               |
| **上下文** | http、server、location、location 中的 if  |

当应答已经在 **Content-Type** 响应头域中携带字符集时，确定是否应该对从代理或 FastCGI/uwsgi/SCGI 服务器接收的应答执行转换。如果启用转换，则在接收到的响应中指定的字符集将用作源字符集。

> 应该注意的是，如果在子请求中接收到响应，则始终执行从响应字符集到主请求字符集的转换，而不管 `override_charset` 指令如何设置。

### source\_charset

| -       | 说明                                  |
| ------- | ----------------------------------- |
| **语法**  | **source\_charset** `charset`;      |
| **默认**  | ——                                  |
| **上下文** | http、server、location、location 中的 if |

定义响应的源字符集。如果此字符集与 [charset](/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md#charset) 指令中指定的字符集不同，则执行转换。

## 原文档

<http://nginx.org/en/docs/http/ngx_http_charset_module.html>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_charset_module.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.