如何通过sub_filter指令实现全站网页内容动态替换-Nginx-PHP中文网

Nginx的sub_filter指令可在响应返回前对HTML等内容做高效字符串替换，适用于关键词替换、CDN切换等场景；需启用sub_filter、设置sub_filter_once off实现全局替换，并注意gzip兼容性、编码安全及变量使用限制。

如何通过sub_filter指令实现全站网页内容动态替换

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 '' '<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 提供默认值增强健壮性