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* 实现任意逻辑，灵活性高，代价是运维与性能开销上升
• 后端模板层处理：更规范，但需研发介入，无法快速兜底