Nginx sub_filter模块支持对后端响应文本做轻量级字符串替换，需配置sub_filter、sub_filter_types、sub_filter_once等指令，注意响应未压缩、编码一致及缓冲区限制。
Nginx 的 sub_filter 模块可用于在响应返回给客户端前，对后端返回的 HTML（或其他文本）内容做简单字符串替换。它不解析 HTML 结构，仅执行正则或字面量匹配替换，适合轻量级动态改写，比如替换域名、插入脚本、修改文案等。
启用 sub_filter 并配置基础替换
该模块默认编译进大多数官方 Nginx 版本（需确认未被禁用）。使用前确保在 http、server 或 location 块中开启：
- 用
sub_filter指令定义原始字符串和替换字符串，支持变量和正则（需加sub_filter_once off和sub_filter_types配合） - 必须设置
sub_filter_types明确指定哪些 MIME 类型允许处理（默认只处理text/html） - 若要全局替换（不止首次出现），需关闭单次替换：
sub_filter_once off
示例：将后端返回的 example.com 全局替换为 myapp.local：
location / {
proxy_pass https://backend;
sub_filter 'example.com' 'myapp.local';
sub_filter_types text/html text/css application/javascript;
sub_filter_once off;
sub_filter_last_modified off; # 避免因替换导致 Last-Modified 失效
}
处理动态值与变量插值
sub_filter 本身不支持正则捕获组重用，但可结合 Nginx 变量实现部分动态性：
- 用
$host、$scheme等内置变量构造替换值，如sub_filter 'http://old.com' '$scheme://$host'; - 注意：变量仅在运行时展开，不能用于
sub_filter的匹配模式（即左侧必须是静态字符串） - 若需更灵活的模式匹配（如替换所有绝对路径），建议配合
sub_filter+ 正则语法（Nginx 1.9.4+ 支持sub_filter的正则模式，用斜杠包围，如sub_filter /https?:\/\/[^\/"]+/ '$scheme://$host';）
注意事项与常见陷阱
该模块行为受响应特性影响较大，实际使用需留意：
-
响应必须是流式且未压缩：若后端启用了
gzip或br，Nginx 默认不会解压再处理，需在 upstream 中禁用压缩，或由 Nginx 自己压缩（设proxy_set_header Accept-Encoding "";） - 字符编码需一致：替换内容应与响应编码（如 UTF-8）兼容，避免乱码；不建议用于含二进制或非文本响应
- 无法处理 chunked transfer encoding 的边界问题：Nginx 按缓冲区切片处理，跨块的字符串可能无法匹配，慎用于长文本或不确定分块策略的场景
- 性能开销低但不可忽略：对大响应体（如 >1MB HTML）做全局替换会增加内存与 CPU 开销，建议搭配缓存或限制作用范围
调试与验证技巧
快速确认 sub_filter 是否生效：
- 用
curl -I查看响应头是否含X-Original-Content-Length（Nginx 添加的调试头，需开启sub_filter_last_modified off才稳定出现） - 临时添加
add_header X-SubFilter-Status "active";辅助判断配置是否加载 - 用
curl -s http://your-nginx/ | grep -o "目标关键词"直接检查输出结果 - 查看 error log 中是否有
subfilter: no memory to process等警告，说明缓冲区不足，可调大sub_filter_buffer_size（默认 1M）
