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 | |
sub_filter <pattern> <replacement>;:字符串替换,可写多条,按顺序应用;sub_filter_once off;:替换所有出现处(默认on只替换第一处);sub_filter_types:只对指定 MIME 类型生效,默认只有text/html。
二、注入脚本与样式
1 | |
on在这里正合适:</head>、</body>只注入一次;- replacement 里可写变量(如
$host),实现按域名差异化注入; - 注入内容较长时建议放独立片段文件,用
include管理(配合第 9 篇)。
三、与压缩的关系
sub_filter 作用于响应体。如果上游返回的是 gzip/br 压缩内容,替换会失效或出错:
1 | |
处理办法:
- 让上游对 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 上下文,避免破坏结构 |
参考链接
- Nginx 官方文档:ngx_http_sub_module ——
sub_filter、sub_filter_once、sub_filter_types; - Nginx 官方文档:ngx_http_gzip_module —— 与压缩的配合;
- Nginx 官方文档:ngx_http_gunzip_module —— 解压上游压缩响应。
小结
sub_filter做响应体字符串替换,可多条、可配 MIME 类型;sub_filter_once on只换第一处,注入脚本时好用;off换全部;- 上游压缩会让替换失效,先解压或不压缩;
- 只支持字符串、不支持正则,别对二进制内容开。
系列导航
Nginx 工程实践 -- 22. 边缘改写 sub_filter
https://bubao.github.io/posts/a2b3c4d5.html
