Nginx的sub_filter指令可实时替换HTML响应内容，需配合sub_filter_once off、sub_filter_types及gunzip on等指令生效，适用于域名切换、环境标识注入等轻量定制场景。
Nginx 的 sub_filter 指令可以在响应返回给客户端前，对 HTML 内容做实时字符串替换，无需改动后端代码或静态资源文件，适合做轻量级内容定制、环境标识注入、CDN 域名切换等场景。
基础用法与生效前提
sub_filter 默认只处理 text/html 类型的响应，且仅对当前 location 块中 proxy_pass 或 fastcgi_pass 返回的内容生效。它不递归处理子请求（如内嵌 iframe、AJAX 返回），也不修改缓存中的内容（除非配合 sub_filter_once off 多次替换）。
- 必须开启
sub_filter_once off才能替换页面中所有匹配项（默认只替换第一个） - 需显式设置
types { text/html; }或使用sub_filter_types *支持其他 MIME 类型（如application/json） - 若后端启用了 gzip，需先在 Nginx 中
gunzip on解压后再替换，否则对压缩流无效
常见实用替换场景
典型用途包括：将开发环境 API 地址替换成线上地址、在页面底部插入调试信息、统一替换品牌名称、修正第三方 CDN 资源路径。
-
域名/路径迁移：
sub_filter 'https://dev.example.com/api' 'https://api.example.com/v2'; -
注入环境标识：
sub_filter '' '<script>window.ENV="staging";</script>'; -
多语言文案微调：
sub_filter '免费试用' '限时体验';（注意编码一致，建议 UTF-8）
注意事项与避坑点
替换不是正则匹配，只支持字面量字符串；大小写敏感；不能跨标签或跨行匹配（HTML 压缩后易失效）。若页面含动态 JS 渲染内容，sub_filter 无法干预 DOM 后续行为。
- 避免替换过长或带特殊字符的字符串，容易因空格、换行、HTML 实体（如
- 启用
sub_filter_last_modified on可保留原始响应的Last-Modified头，避免缓存异常 - 调试时可临时加
add_header X-Subfilter-Status "active";确认规则是否命中
完整配置示例
以下配置实现：代理到上游服务，将所有 dev-api.example.com 替换为 api.example.com，并在
