如何通过 sub_filter 指令实现在代理层动态修正 HTML 内的绝对资源访问链接-Nginx-PHP中文网

Nginx 的 sub_filter 指令可动态替换 HTML 响应体中的绝对 URL，解决资源路径错位等问题；需启用 sub_filter_once off、处理 Content-Encoding、设置 sub_filter_types，并注意匹配精度与顺序。

如何通过 sub_filter 指令实现在代理层动态修正 html 内的绝对资源访问链接

可以通过 Nginx 的 sub_filter 指令在反向代理响应时，对 HTML 响应体中的绝对 URL 进行动态替换，从而解决资源路径错位、跨域加载失败或 CDN 切换等场景下的静态资源访问问题。关键在于正确启用替换、处理响应头限制、注意匹配精度和编码兼容性。

Nginx 默认不修改响应体，需显式开启并配合相关指令：

设置 sub_filter 规则，如 sub_filter "https://old.example.com/" "https://new.cdn.com/";
必须启用 sub_filter_once off;（默认为 on），否则只替换首个匹配项
确保后端返回的 Content-Encoding 为 identity（即未压缩）；若后端返回 gzip，需在 proxy 配置中加 proxy_set_header Accept-Encoding ""; 或用 gunzip on; 解压后再处理
添加 sub_filter_types text/html text/css application/javascript;，显式声明支持处理的 MIME 类型（默认仅 text/html）

HTML 中需修正的典型绝对资源路径包括：

HTML Text Extract

从HTML页面（URL、文件或标准输入）中提取主体内容文本，去除导航、页脚、广告和模板文本。可直接传递给readability_check或其他文本工具。

下载

→ 替换域名部分
<script src="/static/js/app.js"></script> → 虽为相对路径，但若需补全为带 CDN 域名的绝对路径，可先用 sub_filter "/static/" "https://cdn.example.com/static/";
url(/images/logo.png)（CSS 内）→ 需包含 text/css 在 sub_filter_types 中，并注意括号和引号的转义（实际匹配时不需转义，sub_filter 是字面量匹配）
避免过度替换：用更精确的模式，例如匹配 src="https://old.com/ 而非宽泛的 https://old.com/，减少误伤文本内容

当需多处修正（如同时改 JS、CSS、图片域名），可链式使用多个 sub_filter：

按从长到短、从具体到宽泛的顺序书写规则，防止前序替换影响后续匹配（例如先替换 https://api.old.com/v2/，再替换 https://api.old.com/）
每个 sub_filter 独立生效，Nginx 会按配置顺序依次执行，无需额外启用开关
若涉及大小写混杂的 URL（如部分小写、部分大写），sub_filter 区分大小写；如需忽略，需借助第三方模块（如 ngx_http_substitutions_filter_module），原生不支持

替换是否生效常因响应头或缓存干扰而难以察觉：

用 curl -H "Accept-Encoding: identity" -I http://your-proxy/ 检查响应头是否含 Content-Encoding: identity 和正确的 Content-Type
临时关闭浏览器缓存或使用 curl -s http://your-proxy/ | grep "cdn.example.com" 直接查看原始响应体
在 location 块中加 add_header X-Subfilter-Status "active"; 辅助确认配置已加载
若页面含内联 JS 或 base 标签（如），需单独处理该标签，否则会影响所有相对路径解析

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索前端的入门与实战技巧！