linux下nginx启用substitution需先确认模块：内置sub_filter（nginx -v查with-http-sub-module）或第三方subs_filter（查with-http-substitutions-module），再按对应语法配置，注意gzip、mime类型及大小写等限制。
Linux 下 Nginx 启用 substitution 模块替换响应内容，核心分两步：确认或编译安装模块，再配置生效。官方默认不带该功能，必须显式启用；而且要注意区分 内置 sub_filter 和 第三方 subs_filter 两个不同模块——前者简单但能力有限，后者支持正则、多次替换等高级特性。
确认当前 Nginx 是否已启用 substitution 模块
先查是否已编译进内核：
- 运行
nginx -V 2>&1 | grep -o with-http-sub-module—— 若有输出，说明启用了内置ngx_http_sub_module - 运行
nginx -V 2>&1 | grep -o with-http-substitutions-module—— 若有输出，说明已集成第三方ngx_http_substitutions_filter_module - 若两者都无输出，需手动编译添加；若只有一者，就按对应模块的语法配置
启用内置 sub_filter（无需额外编译）
适用于基础字符串替换，如注入环境标识、改 CDN 地址等。注意它默认只处理 text/html 类型，且仅替换首次匹配：
- 在
location块中添加：sub_filter '旧文本' '新文本'; - 允许全文替换：
sub_filter_once off; - 扩展 MIME 类型支持（比如 JS/CSS）：
sub_filter_types text/html text/css application/javascript; - 禁用源站 gzip（否则无法替换）：
proxy_set_header Accept-Encoding '';（配合proxy_pass使用时）
启用第三方 subs_filter（需重新编译 Nginx）
适合需要正则、多轮替换、跨行处理等场景（注意：仍不支持跨行匹配）。步骤如下：
- 下载模块源码：
git clone https://github.com/yaoweibin/ngx_http_substitutions_filter_module - 重新编译 Nginx，关键参数加：
--add-module=/path/to/ngx_http_substitutions_filter_module - 配置示例：
subs_filter 'https?://old\.domain' 'https://new.cdn' gi;（g=全局，i=忽略大小写） - 支持链式调用，多个
subs_filter指令会顺序执行
常见问题与避坑点
实际部署时容易卡在这几个地方：
-
gzip 冲突：sub_filter 类模块只处理未压缩响应。务必在 upstream 或 proxy_pass 前关闭压缩：
proxy_set_header Accept-Encoding '';，或后端关 gzip -
MIME 类型限制：默认不处理 JS/CSS，必须显式用
sub_filter_types或subs_filter_types添加 -
变量引用：替换值中可写
$host、$server_addr等变量，但不能在被搜索的原文中用变量 -
大小写敏感性：内置
sub_filter不区分大小写；第三方subs_filter默认区分，加i标志可忽略
