Nginx sub_filter可在缓存层动态注入资源版本指纹，需启用模块、禁用压缩、扩展MIME类型、关闭单次替换；推荐安全边界匹配（如替换'src="/js/app.js"'为带?v=参数版本），并配合缓存策略拦截无指纹请求。
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>、<link href="/css/main.css"> 等格式。
- 使用精确前缀匹配，避免误改 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就会被误改）。
✅ 安全边界匹配（推荐用于生产）
用更长、更唯一的上下文提高准确性，例如：
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";
不复杂但容易忽略
