ngx_http_sub_module 是 Nginx 官方轻量过滤模块，仅对响应体做字节流级字符串替换，适用于代理层批量修改静态文案、域名等；需编译启用，配合 proxy_pass 在 location 中配置 sub_filter，不解析 HTML、不支持大小写忽略与非 UTF-8 编码。
ngx_http_sub_module 是 Nginx 官方提供的过滤模块，可在反向代理响应体（response body）中对文本内容做简单、高效的字符串替换。它不解析 HTML 结构，仅做字节流级别的正则或固定字符串替换，适合在代理层统一处理静态文案、域名、路径等关键词批量变更，无需后端配合。
启用与基础配置要点
该模块默认不编译进 Nginx，需确认安装时启用了 --with-http_sub_module。运行时通过 sub_filter 指令定义替换规则，配合 sub_filter_types 控制生效的 MIME 类型（默认仅 text/html）。
- 替换指令必须写在 location 块内，且仅对 proxied 响应生效（需搭配 proxy_pass）
- 每条 sub_filter 只能定义一对“查找→替换”，多关键词需多行声明，顺序执行
- 使用 sub_filter_once off 可开启全局替换（默认只换首次匹配）
- 若后端返回 gzip 压缩内容，需先解压再替换——通常需关闭后端 gzip 或在 Nginx 中配置 proxy_buffering off 和 gzip off
典型应用场景与写法示例
常见于灰度发布、多环境共用一套前端资源、或合规性文案统一切换场景：
-
域名/路径迁移：
sub_filter 'https://old.example.com' 'https://new.example.com'; -
品牌词批量更新：
sub_filter '旧品牌名' '新品牌名'; sub_filter_once off; -
调试标识注入：
sub_filter '' '<!-- served by nginx-sub -->\n';（注意换行需用 \n） -
敏感路径脱敏：
sub_filter '/admin/api/' '/[redacted]/';
限制与避坑提醒
该模块轻量但能力有限，不适合复杂场景：
- 不支持嵌套标签、属性值内替换（如
<a href="xxx"></a>中的 href 值不会被触达） - 不支持大小写不敏感匹配，需自行用正则变通（如
sub_filter 'Login' 'Sign in'; sub_filter 'login' 'sign in';） - 若响应含非 UTF-8 编码（如 GBK），替换可能错位，建议统一后端输出编码为 UTF-8
- 大量 sub_filter 规则会增加响应延迟，单 location 建议控制在 10 条以内
替代方案简要对比
当 sub_filter 不满足需求时可考虑：
- ngx_http_substitutions_filter_module（第三方）：支持正则、多行匹配、大小写忽略，但需额外编译
- OpenResty + Lua：用 lua_filter 或 body_filter_by_lua* 实现任意逻辑，灵活性高，代价是运维与性能开销上升
- 后端模板层处理：更规范，但需研发介入，无法快速兜底
