如何通过 sub_filter 指令在分发缓存内容时动态修正 HTML 中的资源版本指纹-Nginx-PHP中文网

Nginx sub_filter可在缓存层动态注入资源版本指纹，需启用模块、禁用压缩、扩展MIME类型、关闭单次替换；推荐安全边界匹配（如替换'src="/js/app.js"'为带?v=参数版本），并配合缓存策略拦截无指纹请求。

如何通过 sub_filter 指令在分发缓存内容时动态修正 html 中的资源版本指纹

Nginx 的 sub_filter 指令可以在缓存分发环节（如 CDN 边缘节点或反向代理层）对 HTML 响应体做实时文本替换，从而动态注入或修正资源链接中的版本指纹（例如 ?v=20260509 或 .v20260509.js），无需改动后端代码或前端构建流程。

这个操作的核心目标是：让每次发布后，HTML 中引用的 JS/CSS 等资源自动带上新指纹，避免浏览器或中间缓存命中旧文件，同时防止无指纹的原始 URL 被缓存穿透到源站。

必须满足的基础条件

模块已启用：确认 Nginx 编译时包含 ngx_http_sub_module（主流发行版默认内置，但需在配置中显式使用才生效）

响应未压缩：sub_filter 对 gzip 压缩后的响应无效。应在 location 块中设置：

proxy_set_header Accept-Encoding "";
gunzip on;  # 若后端返回 gzip，则解压后再处理

MIME 类型明确声明：默认只处理 text/html，若 HTML 中内联了 JS/CSS 或含 SVG 引用，需扩展：
```
sub_filter_types text/html application/javascript text/css image/svg+xml;
```
允许多次替换：默认 sub_filter_once on，只替换第一个匹配项。必须设为：
```
sub_filter_once off;
```

推荐的指纹注入方式

✅ 追加查询参数型（最常用、兼容性好）

适用于 <script src="/js/app.js"></script>、等格式。

使用精确前缀匹配，避免误改 API 路径（如 /api/xxx）：

sub_filter 'src="/js/' 'src="/js/?v=20260509';
sub_filter 'href="/css/' 'href="/css/?v=20260509';
sub_filter 'src="/img/' 'src="/img/?v=20260509';

更通用的做法是结合 Nginx 变量（如 $msec 毫秒时间戳）生成动态值：
```
sub_filter 'src="/' 'src="/?v=$msec';
sub_filter 'href="/' 'href="/?v=$msec';
```
注意：这种写法会把 src="/js/app.js" 变成 src="/?v=1746824760123js/app.js —— ❌ 错误！
正确做法是匹配完整路径片段，或改用更安全的边界模式（见下文）。

✅ 替换后缀型（适合构建时已支持 `.vxxx.js` 格式）

若前端构建支持输出带哈希后缀的文件（如 app.v20260509.js），可统一替换路径：

sub_filter '.js' '.v20260509.js';
sub_filter '.css' '.v20260509.css';
sub_filter_once off;

优点：不破坏已有查询参数；缺点：需确保原始路径不含其他 .js 字符串（如注释里有 // end.js 就会被误改）。

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

下载

✅ 安全边界匹配（推荐用于生产）

用更长、更唯一的上下文提高准确性，例如：

sub_filter 'src="/js/app.js"' 'src="/js/app.js?v=20260509"';
sub_filter 'href="/css/main.css"' 'href="/css/main.css?v=20260509"';

虽然配置略多，但几乎零误伤，适合关键业务页面。

配合缓存策略防穿透

所有带指纹的资源 URL（如 /js/app.js?v=20260509）应被 CDN 或代理层缓存，且设置较长 Cache-Control: public, max-age=31536000

原始无指纹 URL（如 /js/app.js）必须不被缓存或直接拦截：

location ~ ^/(js|css|img)/ {
    if ($args = "") {
        return 403;  # 或重定向到带指纹版本
    }
}

同时隐藏源站 ETag，避免因内容替换后校验失败导致缓存失效：
```
proxy_hide_header ETag;
add_header Cache-Control "no-cache";
```

不复杂但容易忽略

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

如何通过 sub_filter 指令在分发缓存内容时动态修正 HTML 中的资源版本指纹