Nginx的sub_filter指令可在响应返回前对HTML等内容做高效字符串替换，适用于关键词替换、CDN切换等场景；需启用sub_filter、设置sub_filter_once off实现全局替换，并注意gzip兼容性、编码安全及变量使用限制。
Nginx 的 sub_filter 指令可在响应返回客户端前，对 HTML 内容做简单、高效的字符串替换，适合实现全站关键词替换、CDN 域名切换、调试标识注入等轻量级动态改写需求。它不依赖后端，纯由 Nginx 在内存中完成，性能开销极小，但需注意其局限性（如不支持正则、仅作用于响应体、受缓冲和编码影响）。
启用 sub_filter 并设置基础替换规则
在 location 或 server 块中启用替换功能：
- 必须开启
sub_filter，语法为sub_filter old_string new_string; - 默认只替换第一个匹配项，添加
sub_filter_once off;可全局替换所有出现位置 - 需确保响应类型为
text/html，可配合sub_filter_types扩展支持类型（如text/css、application/javascript）
示例配置：
location / {
proxy_pass https://backend;
sub_filter '<head>' '<head><meta name="generator" content="nginx-sub-filter">';
sub_filter 'http://old-cdn.example.com/' 'https://new-cdn.example.com/';
sub_filter_once off;
sub_filter_types text/html text/css application/javascript;
}
处理 gzip 压缩与响应缓冲的兼容问题
sub_filter 仅作用于未压缩的明文响应体。若上游返回 gzip 响应，Nginx 默认不会解压，导致替换失效：
- 方案一：禁止上游返回压缩（在
proxy_set_header Accept-Encoding "";），让后端返回明文 - 方案二：在 Nginx 端解压再替换（需编译时启用
--with-http_gunzip_module），并配置gunzip on; - 注意响应缓冲：若响应过大或分块传输（chunked），需确保
sub_filter能捕获完整 body；可通过proxy_buffering off;或调大proxy_buffers提高命中率
安全替换与常见避坑点
直接替换易引发 HTML 结构破坏或 XSS 风险，需谨慎设计：
- 避免替换 HTML 标签内属性值（如
href="xxx"中的xxx），除非确认上下文安全；优先替换标签间文本内容 - 中文、特殊符号需确保编码一致（推荐统一使用 UTF-8），避免因编码错位导致替换失败或乱码
-
sub_filter不支持正则表达式，无法做模式匹配（如替换所有邮箱、手机号）；复杂需求建议改用ngx_http_substitutions_filter_module（第三方模块）或后端处理 - 替换内容含引号、斜杠等字符时，注意 Nginx 配置文件本身的转义规则（如双引号内用
\"）
结合变量实现条件化替换（Nginx 1.9.2+）
新版 Nginx 支持在 sub_filter 中使用变量（需开启 sub_filter_last_modified off; 以禁用缓存干扰）：
- 例如根据请求头注入不同环境标识：
sub_filter 'window.APP_ENV = "dev";' 'window.APP_ENV = "$http_x_env";'; - 变量值需来自可信来源（如内部 header、map 映射），避免直接反射用户输入
- 注意变量为空时可能导致空替换，可用
map提供默认值增强健壮性
