Nginx 的 sub_filter 指令可对代理响应体进行实时字符串替换，需满足 Content-Type 匹配、响应未压缩、缓冲足够等条件，支持动态变量如 $scheme 和 $host，但仅精确匹配、不支持正则。
Nginx 的 sub_filter 指令可以在反向代理场景中，对后端返回的响应体（如 HTML、CSS、JS）进行实时字符串替换，从而将硬编码的绝对 URL（例如 https://old.example.com/static/）动态改写为当前代理域名下的路径（如 /static/ 或 https://new.example.com/static/），避免资源 404 或混合内容问题。
启用 sub_filter 的基本前提
要让 sub_filter 生效，必须满足几个关键条件：
- 响应 Content-Type 必须匹配
sub_filter_types中指定的 MIME 类型（默认只处理text/html，需显式添加text/css、application/javascript等） - 响应不能被压缩（gzip/brotli），否则 Nginx 无法解析明文内容；需在 proxy 配置中关闭后端的压缩或在 Nginx 中用
proxy_buffering off+sub_filter_last_modified off配合处理 -
sub_filter是逐块处理的，不支持跨 buffer 边界匹配，长标签或换行较多时建议调大proxy_buffers
典型配置：将后端域名替换为当前请求域名
适用于后端返回 HTML 中大量含 https://backend.example.com/ 的链接，希望统一映射到代理入口域名：
location / {
proxy_pass https://backend.example.com/;
proxy_set_header Host backend.example.com;
<pre class="brush:php;toolbar:false;"># 启用 sub_filter 并扩展支持类型
sub_filter 'https://backend.example.com/' '$scheme://$host/';
sub_filter 'http://backend.example.com/' '$scheme://$host/';
sub_filter_types text/html text/css application/javascript;
sub_filter_once off; # 替换全部匹配项，非仅第一个
# 关键：禁用后端 gzip，或主动解压（需编译时含 gunzip 模块）
proxy_http_version 1.1;
proxy_set_header Accept-Encoding "";
gunzip on; # 若启用了 gunzip 模块，可自动解压再过滤
}
注意：$scheme 和 $host 是运行时变量，Nginx 会实时展开为当前请求的协议与主机名，实现真正的“动态修正”。
处理相对路径误写为根路径的场景
有些后端模板错误地将资源写成 /static/js/app.js（本意是相对当前路径），但部署在子路径（如 /app/）下时应变为 /app/static/js/app.js。此时可用嵌套 sub_filter 修正：
location /app/ {
proxy_pass https://backend.internal/;
proxy_redirect off;
<pre class="brush:php;toolbar:false;"># 先把所有 /static/ 替换为 /app/static/
sub_filter '/static/' '/app/static/';
sub_filter '/css/' '/app/css/';
sub_filter '/js/' '/app/js/';
sub_filter_types text/html text/css application/javascript;
sub_filter_once off;
# 确保响应未压缩且缓冲足够
proxy_buffering on;
proxy_buffers 8 256k;
proxy_busy_buffers_size 512k;
}
这种写法适合灰度迁移或路径重映射，无需修改后端代码。
注意事项与常见陷阱
sub_filter 功能轻量但边界敏感，实际使用中需避开几个高频坑：
- 不支持正则表达式，仅字符串精确匹配；大小写敏感，必要时用多条指令覆盖不同写法
- HTML 属性值中的 URL（如
url = "https://" + host）无法识别 - 若后端返回
Content-Encoding: gzip且 Nginx 未解压，sub_filter完全不生效 —— 建议在后端关闭 gzip，或启用gunzip on（需确认模块已编译） - 替换后可能破坏 HTML 结构（如截断属性值），建议在
sub_filter后加sub_filter_last_modified off避免干扰缓存头
它不是万能的资源重写方案，但对于静态 HTML 页面和简单前端应用，是零代码改造下最直接有效的代理层地址修正手段。
