Nginx 的 sub_filter 指令可在反向代理响应返回前动态替换 HTML 响应体中的字符串，用于修正后端生成的绝对路径以适配前端访问上下文，但要求响应未压缩、Content-Type 匹配且不跨 chunk 匹配。
使用 Nginx 的 sub_filter 指令可以在反向代理响应返回客户端前，动态替换 HTML 内容中的字符串，从而修正后端服务生成的绝对路径（如 href="/css/app.css" 或 src="https://api.example.com/data"），使其适配前端访问的域名或路径上下文。这在前后端分离、多环境部署或嵌入式集成场景中非常实用。
确保 sub_filter 生效的基本前提
Nginx 默认不会对压缩响应（如 gzip）执行替换，且 sub_filter 仅作用于响应体（body），不处理响应头或二进制内容。需确认以下几点：
- 后端返回的 Content-Encoding 必须为
identity（即未启用 gzip/brotli 压缩），或在 Nginx 中显式关闭压缩：gzip off; - 响应 Content-Type 必须匹配
sub_filter_types设置，默认只处理text/html，若需处理 JS/CSS，需补充：sub_filter_types text/css text/javascript; -
sub_filter是逐块处理流式响应的，不支持正则、不保证跨 chunk 匹配，长文本或换行可能中断匹配 —— 建议后端输出格式化较规范的 HTML
基础用法：替换静态绝对路径前缀
例如后端返回 href="/static/js/main.js"，但你希望用户通过 https://myapp.com/subpath/ 访问，则需将所有 /static/ 替换为 /subpath/static/：
location /subpath/ {
proxy_pass https://backend/;
proxy_set_header Host $host;
<pre class="brush:php;toolbar:false;"># 关键配置
sub_filter '/static/' '/subpath/static/';
sub_filter_once off; # 替换全部匹配项（默认只替换第一个）
sub_filter_types text/html text/css text/javascript;
sub_filter_last_modified off; # 避免因替换导致 Last-Modified 失效问题（可选）
# 禁用压缩以确保 sub_filter 可见原始文本
gzip off;}
立即学习“前端免费学习笔记（深入）”；
处理协议 + 域名类绝对 URL
若后端硬编码了完整 URL，如 src="https://api.internal/v1/users"，而你需要指向代理后的网关地址（如 https://myapp.com/api/v1/users），可用：
sub_filter 'https://api.internal/' 'https://myapp.com/api/'; sub_filter 'http://api.internal/' 'https://myapp.com/api/';
注意：sub_filter 区分大小写且不支持通配符。若存在混合协议或子域名，建议统一后端输出相对路径，或配合 proxy_redirect 处理重定向响应头中的 Location 字段（sub_filter 不处理响应头）。
安全与性能注意事项
sub_filter 是纯文本替换，无 HTML 解析能力，因此：
- 避免替换可能出现在属性值以外的位置（如误改注释、JS 字符串、JSON 内容），可加引号限定上下文：
sub_filter 'href="/' 'href="/subpath/'; - 大量替换或大响应体会影响代理吞吐量，生产环境建议结合缓存（
proxy_cache）减少重复处理 - 对于现代 SPA 应用，更推荐让前端构建时通过
publicPath或运行时配置生成相对路径，而非依赖代理层修补
