ngx_http_sub_module

### 功能 `ngx_http_sub_module` 是 Nginx 提供的一个过滤器模块，可以用于修改网站响应内容中的字符串，例如替换网页中的某些文本内容。这个模块支持在 `http`、`server` 和 `location` 上下文中使用，并且主要通过 `sub_filter` 指令来实现字符串替换功能。它可以用于过滤敏感词、修改页面中的链接或资源路径等场景[^2]。 然而，`ngx_http_sub_module` 的一个限制是它不支持正则表达式替换，而第三方模块 `ngx_http_substitutions_filter_module` 则弥补了这一不足，允许使用正则表达式进行更灵活的替换操作。 ### 配置与安装 在使用 `ngx_http_sub_module` 之前，需要确认 Nginx 是否已经编译并启用了该模块。可以通过运行 `nginx -V` 命令来查看当前 Nginx 的编译参数。如果输出中包含 `--with-http_sub_module`，则表示该模块已被启用[^1]。 如果模块未启用，则需要重新编译 Nginx，并在编译参数中添加 `--with-http_sub_module`，以启用该模块的支持。 ### 使用方法 #### 1. 基本使用 `ngx_http_sub_module` 主要通过以下指令进行配置： - `sub_filter <search_string> <replace_string>`：定义需要替换的字符串。 - `sub_filter_once <on|off>`：控制是否只替换第一个匹配项（`on`）或替换所有匹配项（`off`）。 - `sub_filter_types <mime_types>`：指定哪些 MIME 类型的内容需要进行替换，默认只替换 `text/html` 类型。 - `sub_filter_last_modified <on|off>`：控制是否允许修改响应头中的 `Last-Modified` 字段。 以下是一个基本的配置示例，将页面中所有的 `http://127.0.0.1:8080` 替换为 `https://$host`： ```nginx location / { sub_filter 'http://127.0.0.1:8080' 'https://$host'; sub_filter_once on; } ``` #### 2. 多次替换 如果需要替换多个不同的字符串，可以在同一个 `location` 块中多次使用 `sub_filter` 指令。例如，同时替换链接和图片路径： ```nginx 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; } ``` #### 3. 替换非 HTML 内容 默认情况下，`sub_filter` 仅对 `text/html` 类型的响应内容生效。如果希望对其他 MIME 类型（如 `text/plain` 或 `application/xml`）也进行替换，可以使用 `sub_filter_types` 指令指定： ```nginx location / { sub_filter 'old_string' 'new_string'; sub_filter_types text/plain application/xml; } ``` #### 4. 替换所有匹配项 如果希望替换所有匹配的字符串而不仅仅是第一个匹配项，可以将 `sub_filter_once` 设置为 `off`： ```nginx location / { sub_filter 'old_string' 'new_string'; sub_filter_once off; } ``` #### 5. 修改响应头中的 `Last-Modified` 字段 当启用 `sub_filter_last_modified` 时，Nginx 会修改响应头中的 `Last-Modified` 字段，以反映内容修改后的时间： ```nginx location / { sub_filter 'old_string' 'new_string'; sub_filter_last_modified on; } ``` ### 注意事项 - `ngx_http_sub_module` 仅支持简单的字符串替换，不支持正则表达式匹配。如果需要更复杂的替换逻辑，可以考虑使用第三方模块 `ngx_http_substitutions_filter_module`。 - 替换操作会对性能产生一定影响，尤其是在大文件或高并发场景下。因此，建议仅在必要时启用该功能。 - 替换操作会影响响应内容的大小，可能导致 `Content-Length` 头部字段不准确。Nginx 会自动处理这种情况，但某些客户端可能会受到影响。