nginx的sub_filter指令用于响应返回前对文本内容做精确字符串替换，不支持正则，需配合sub_filter_types指定mime类型、proxy_set_header accept-encoding ''禁用后端压缩，并注意流式处理限制。
Nginx 的 sub_filter 指令用于在响应返回给客户端前，对 HTML（或其他文本）内容做简单字符串替换，常用于动态修改页面中的 URL、文案或环境标识。它不支持正则，只做精确字符串匹配与替换，适合轻量级内容改写。
启用 sub_filter 的基本配置
该功能默认不启用，需显式开启 sub_filter 并配合 sub_filter_types 指定 MIME 类型：
-
sub_filter必须成对使用：一个定义要查找的字符串，一个定义替换后的字符串 -
sub_filter_types默认只处理text/html，若需处理 JS、CSS 或 JSON，需手动添加，例如：sub_filter_types text/css application/javascript application/json; - 建议开启
sub_filter_once off;（默认为 on），否则每行只替换第一次匹配项
常见替换场景与写法示例
比如将所有 http://old.example.com 替换为 https://new.example.com：
location / {
sub_filter 'http://old.example.com' 'https://new.example.com';
sub_filter_types text/html text/css application/javascript;
sub_filter_once off;
proxy_pass https://backend;
proxy_set_header Accept-Encoding '';
}
注意：proxy_set_header Accept-Encoding '' 是关键——禁用后端压缩（如 gzip），否则 Nginx 无法解压并处理原始文本内容。
注意事项与限制
sub_filter 是流式处理，按 chunk 进行，不缓存整个响应体，因此：
- 不能跨 chunk 匹配（如关键词被切在两个数据块中间，会失效）
- 不支持正则表达式、大小写忽略、或条件替换
- 仅适用于
proxy_pass或fastcgi_pass等代理/后端响应，不作用于静态文件（root/alias） - 若后端返回
Content-Encoding: gzip且未被 Nginx 解压，则替换无效
调试技巧
遇到替换不生效时，可逐步确认：
- 用
curl -I检查响应头是否含Content-Encoding: gzip，若有，确保加了proxy_set_header Accept-Encoding ''; - 用
curl -s查看原始响应内容，确认待替换字符串确实存在且拼写完全一致（包括空格、引号、大小写） - 临时把
sub_filter_types设为*（Nginx 1.19.6+ 支持）快速验证 MIME 类型是否匹配 - 开启
error_log调试级别（debug）可查看 sub_filter 处理日志（需编译时启用--with-debug）
