ngx_http_sub_module模块支持响应体文本的批量字符串替换，适用于CDN切换、环境标识注入等场景；需确认编译时启用--with-http_sub_module，配合sub_filter、sub_filter_once和sub_filter_types指令使用，不支持正则且对gzip压缩响应无效。
nginx 的 ngx_http_sub_module 模块可用于在响应返回客户端前，对响应体（body）中的文本内容进行简单、高效的批量字符串替换。它不依赖后端修改，适合做前端资源路径统一改写、环境标识注入、CDN 域名切换等轻量级内容干预场景。
启用 sub_filter 前提与编译检查
该模块默认不编译进官方预编译包（如 apt/yum 安装的 nginx），需确认是否已启用：
- 执行
nginx -V 2>&1 | grep -o with-http-sub-module，若输出为空，说明未启用 - 源码编译需显式添加
--with-http_sub_module - Docker 用户建议使用
nginx:alpine镜像（Alpine 版本默认包含该模块）或自定义构建
基础语法与替换规则
sub_filter 指令支持单次/多次替换，配合 sub_filter_once 和 sub_filter_types 精确控制范围：
-
sub_filter "原字符串" "新字符串";—— 替换第一个匹配项（默认） -
sub_filter_once off;—— 启用全局替换（同一行内多次出现也会替换） -
sub_filter_types text/html text/css application/javascript;—— 明确指定生效的 MIME 类型，默认仅text/html - 替换支持变量，例如
sub_filter "https://old.com" "$scheme://$host";
典型实战案例：静态资源 CDN 域名自动切换
假设原始 HTML 中引用了 https://example.com/static/，希望在生产环境自动替换为 CDN 地址 https://cdn.example.com/：
location / {
proxy_pass http://backend;
proxy_set_header Host $host;
<pre class="brush:php;toolbar:false;">sub_filter "https://example.com/static/" "https://cdn.example.com/";
sub_filter "http://example.com/static/" "https://cdn.example.com/";
sub_filter_once off;
sub_filter_types text/html text/css application/javascript;
sub_filter_last_modified on; # 保持 Last-Modified 头不变
}
注意：sub_filter 对 gzip 压缩响应无效（需先解压），因此建议在 proxy 或 upstream 层关闭 gzip（proxy_set_header Accept-Encoding ""; ），或确保后端不压缩 HTML/CSS/JS。
调试技巧与常见陷阱
替换失败？优先排查以下几点：
- 响应头中必须含
Content-Type且值匹配sub_filter_types列表（可用curl -I查看） - 响应体被 gzip 压缩 → 添加
proxy_set_header Accept-Encoding "";并在后端禁用对应路径压缩 - 大小写敏感 →
sub_filter区分大小写，如需忽略，需借助第三方模块（如ngx_http_subs_filter_module）或提前统一流量格式 - 正则不支持 → 该模块仅支持字面量替换，不支持正则表达式；复杂需求请评估使用
lua-resty-string+ OpenResty
替换效果可直接用 curl -s http://your-site/ | grep cdn 快速验证，也可开启 error_log /var/log/nginx/sub.log debug; 查看匹配日志（需编译时启用 debug 日志）。
