> For the complete documentation index, see [llms.txt](https://docshome.gitbook.io/nginx-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docshome.gitbook.io/nginx-docs/he-xin-gong-neng/http/ngx_http_sub_module.md).

# ngx\_http\_sub\_module

* [示例配置](/nginx-docs/he-xin-gong-neng/http/ngx_http_sub_module.md#example_configuration)
* [指令](/nginx-docs/he-xin-gong-neng/http/ngx_http_sub_module.md#directives)
  * [sub\_filter](/nginx-docs/he-xin-gong-neng/http/ngx_http_sub_module.md#sub_filter)
  * [sub\_filter\_last\_modified](/nginx-docs/he-xin-gong-neng/http/ngx_http_sub_module.md#sub_filter_last_modified)
  * [sub\_filter\_once](/nginx-docs/he-xin-gong-neng/http/ngx_http_sub_module.md#sub_filter_once)
  * [sub\_filter\_types](/nginx-docs/he-xin-gong-neng/http/ngx_http_sub_module.md#sub_filter_types)

`ngx_http_sub_module` 模块是一个过滤器，它通过替换指定的字符串来修改响应数据。

默认不构建此模块，可在构建时使用 `--with-http_sub_module` 配置参数启用。

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

```
location / {
    sub_filter '<a href="http://127.0.0.1:8080/'  '<a href="https://$host/';
    sub_filter '<img src="http://127.0.0.1:8080/' '<img src="https://$host/';
    sub_filter_once on;
}
```

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

### sub\_filter

| -       | 说明                                    |
| ------- | ------------------------------------- |
| **语法**  | **sub\_filter** `string replacement`; |
| **默认**  | ——                                    |
| **上下文** | http、server、location                  |

设置要替换的字符串（`string`）和要替换成的字符串（`replacement`）。要替换的字符串匹配忽略大小写。要替换的字符串（1.9.4）和要替换成的字符串可以包含变量。可以在一个配置级别指定几个 `sub_filter` 指令（1.9.4）。当且仅当在当前级别上没有定义 `sub_filter` 指令时，这些指令才从上级继承。

### sub\_filter\_last\_modified

| -       | 说明                                             |
| ------- | ---------------------------------------------- |
| **语法**  | **sub\_filter\_last\_modified** `on` \| `off`; |
| **默认**  | sub\_filter\_last\_modified off;               |
| **上下文** | http、server、location                           |
| **提示**  | 该指令在 1.5.1 版本中出现                               |

允许在替换期间保留原始响应中的 **Last-Modified** 头字段，用于响应缓存。

默认情况下，在处理期间修改响应的内容时，将删除头字段。

### sub\_filter\_once

| -       | 说明                                   |
| ------- | ------------------------------------ |
| **语法**  | **sub\_filter\_once** `on` \| `off`; |
| **默认**  | sub\_filter\_once on;                |
| **上下文** | http、server、location                 |

只查找一次要替换的每个字符串或重复查找。

### sub\_filter\_types

| -       | 说明                                      |
| ------- | --------------------------------------- |
| **语法**  | **sub\_filter\_types** `mime-type ...`; |
| **默认**  | sub\_filter\_types text/html;           |
| **上下文** | http、server、location                    |

除了 **text/html** 之外，还指定在其他 MIME 类型的响应中启用字符串替换。特殊值 `*` 匹配任何 MIME 类型（0.8.29）。

## 原文档

* <http://nginx.org/en/docs/http/ngx_http_sub_module.html>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.