Nginx 工程实践 -- 22. 边缘改写 sub_filter

有时不想改后端代码,只想在网关层对响应"动点手脚":给所有 HTML 注入一段统计脚本、把旧的下载域名替换成新域名、在页面底部加公告。ngx_http_sub_module 提供的 sub_filter 就是干这个的——对响应体做字符串替换。

flowchart LR
    A["上游响应体"] --> B{"sub_filter_types
类型匹配?"} B -->|"是"| C["按 sub_filter 规则替换"] B -->|"否"| D["原样返回"] C --> E["客户端拿到改写后的内容"]

一、基本配置

1
2
3
4
5
6
7
location / {
proxy_pass http://backend;

sub_filter 'http://old.example.com' 'https://new.example.com';
sub_filter_once off;
sub_filter_types text/html;
}
  • sub_filter <pattern> <replacement>;:字符串替换,可写多条,按顺序应用;
  • sub_filter_once off;:替换所有出现处(默认 on 只替换第一处);
  • sub_filter_types:只对指定 MIME 类型生效,默认只有 text/html。

二、注入脚本与样式

1
2
3
4
5
6
7
8
location / {
proxy_pass http://backend;

sub_filter '</head>' '<script src="/stats.js"></script></head>';
sub_filter '</body>' '<div id="notice">系统维护公告</div></body>';
sub_filter_once on;
sub_filter_types text/html;
}
  • on 在这里正合适:</head>、</body> 只注入一次;
  • replacement 里可写变量(如 $host),实现按域名差异化注入;
  • 注入内容较长时建议放独立片段文件,用 include 管理(配合第 9 篇)。

三、与压缩的关系

sub_filter 作用于响应体。如果上游返回的是 gzip/br 压缩内容,替换会失效或出错:

1
2
3
4
5
6
7
location / {
proxy_pass http://backend;

# 让上游不要压缩,或由 Nginx 先解压
proxy_set_header Accept-Encoding "";
sub_filter 'foo' 'bar';
}

处理办法:

  • 让上游对 Nginx 不压缩(proxy_set_header Accept-Encoding "";),再由 Nginx 按需重新压缩;
  • 或在 Nginx 侧先解压再替换(gunzip 模块,适用于上游固定压缩的场景);
  • 注意:对已压缩内容直接替换会得到乱码或替换失败。

四、适用场景

场景说明
域名迁移批量替换页面里的旧链接
统计注入在 </head>/</body> 注入脚本
公告/水印页面底部插入统一公告
A/B 文案替换特定字符串做文案实验
去掉敏感字段抹掉响应体里的内部信息

五、常见坑

坑说明
对 JSON/API 生效sub_filter_types 默认只处理 html,按需显式指定
上游压缩导致替换失败先解压或不压缩,再替换
只替换了第一处默认 sub_filter_once on,按需 off
正则需求sub_filter 只支持字符串替换,不支持正则
二进制内容别对图片/字体开 sub_filter_types,会损坏内容
注入脚本被转义注意 HTML 上下文,避免破坏结构

参考链接

  1. Nginx 官方文档:ngx_http_sub_module —— sub_filter、sub_filter_once、sub_filter_types;
  2. Nginx 官方文档:ngx_http_gzip_module —— 与压缩的配合;
  3. Nginx 官方文档:ngx_http_gunzip_module —— 解压上游压缩响应。

小结

  • sub_filter 做响应体字符串替换,可多条、可配 MIME 类型;
  • sub_filter_once on 只换第一处,注入脚本时好用;off 换全部;
  • 上游压缩会让替换失效,先解压或不压缩;
  • 只支持字符串、不支持正则,别对二进制内容开。

系列导航


Nginx 工程实践 -- 22. 边缘改写 sub_filter
https://bubao.github.io/posts/a2b3c4d5.html
作者
一念
发布于
2026年11月21日
许可协议