sub_filter_once off 可实现响应体中所有匹配项的全局替换，而非仅首次出现位置；需配合 sub_filter_types 指定 MIME 类型、禁用 gzip 或启用 gunzip、确保 Content-Type 正确且响应未超 buffer 限制。
使用 Nginx 的 sub_filter_once off 可以让 sub_filter 对响应体中**所有匹配项**进行替换，而不仅限于首次出现的位置。这是实现页面内关键词全局替换的关键配置。
sub_filter_once off 的作用机制
默认情况下，Nginx 的 sub_filter 只替换每个响应块（buffer）中**第一个匹配项**，且受流式传输影响，可能漏掉后续内容。
启用 sub_filter_once off 后，Nginx 会对整个响应体（在内存 buffer 范围内）逐个查找并替换**所有符合条件的字符串**，前提是：
- 响应头中包含
Content-Type: text/html或其他被sub_filter_types显式允许的类型 - 响应未被压缩（gzip/br 等），或已配置
sub_filter与压缩模块兼容（通常需禁用压缩或使用gunzip on） - 响应体大小未超过
sub_filter内部 buffer 限制（默认约 1MB，可通过sub_filter_buffer_size调整）
启用全局替换的最小完整配置
以下是一个可直接用于 server 或 location 块的典型示例：
location / {
proxy_pass http://backend;
proxy_set_header Accept-Encoding ""; # 防止后端返回 gzip，避免 sub_filter 失效
<pre class="brush:php;toolbar:false;">sub_filter "<title>My Site</title>" "<title>Our Site</title>";
sub_filter "Copyright 2023" "Copyright 2024";
sub_filter_types text/html text/css text/javascript application/javascript;
sub_filter_once off;
# 若后端强制返回 gzip，可添加解压（需启用 ngx_http_gunzip_module）
# gunzip on;
}
注意：sub_filter 是按顺序执行的，多个规则会依次应用；若存在重叠或嵌套替换，需注意先后顺序。
常见陷阱与绕过方案
实际使用中容易遇到以下问题：
-
压缩响应导致失效：Nginx 默认不处理 gzip 编码响应。必须通过
proxy_set_header Accept-Encoding ""告知后端不压缩，或启用gunzip on（需编译时含--with-http_gunzip_module） -
大文件截断替换：超大 HTML（如 >1MB）可能因 buffer 不足跳过部分替换。可增大缓冲：
sub_filter_buffer_size 2m; -
HTML 标签内属性值被误替换：sub_filter 是纯字符串替换，不解析 HTML 结构。例如替换
src="logo.png"中的logo可能破坏路径。建议使用更精确的匹配模式（如加空格或引号边界），或改用 Lua 模块做 DOM 级处理 -
响应头缺失 Content-Type：若后端未返回
Content-Type，Nginx 默认按text/plain处理，而该类型不在默认sub_filter_types列表中。务必显式声明所需类型
验证是否生效的快速方法
部署后可通过 curl 直接检查原始响应和替换效果：
curl -s http://your-domain/ | grep -o "Copyright 2024" curl -s -H "Accept-Encoding: identity" http://your-domain/ | head -20
确保请求未带 Accept-Encoding: gzip，并观察返回内容中目标关键词是否全部更新。也可在浏览器开发者工具的 Network → Response 标签中查看最终 HTML 源码。
