如何利用 sub_filter 在负载均衡层动态追加静态资源的版本指纹防缓存-Nginx-PHP中文网

在负载均衡层用sub_filter动态追加静态资源版本指纹，需满足三前提：禁用压缩、显式声明MIME类型、关闭sub_filter_once；常用写法为精准替换src路径并注入时间戳或毫秒变量，配合CDN防穿透与缓存协同策略确保生效。

如何利用 sub_filter 在负载均衡层动态追加静态资源的版本指纹防缓存

在负载均衡层用 sub_filter 动态追加静态资源版本指纹，核心是不改源码、不重发包，只在响应返回前把 /js/app.js 这类路径实时改成 /js/app.js?v=20260509，从而让浏览器和 CDN 把带指纹的 URL 当作新资源缓存，避免旧文件长期滞留。

很多配置写了却没效果，问题几乎都出在这三点：

响应不能压缩：gzip 或 brotli 压缩后的响应体，sub_filter 完全无法处理。需在对应 location 中加 gzip off;，并设 proxy_set_header Accept-Encoding "";，防止后端自作主张返回压缩内容
显式声明 MIME 类型：默认只处理 text/html，但 HTML 中的资源链接可能来自内联 JS/CSS 或 JSON 配置。需补全：sub_filter_types text/html application/javascript text/css application/json;
开启全局替换：默认 sub_filter_once on，只替换第一个匹配项。页面里多个 src="/js/app.js" 就会漏掉。务必设为 sub_filter_once off;

目标是把 src="/js/app.js" → src="/js/app.js?v=20260509"，而不是破坏结构或误改其他内容：

用时间戳变量（稳定且每日唯一）：sub_filter 'src="/js/' 'src="/js/?v=20260509'; —— 适合灰度发布或按日更新
用毫秒级变量（更细粒度）：sub_filter 'src="/' 'src="/?v=$msec'; —— 需配合 sub_filter_once off，确保所有 src="/ 开头的路径都被处理
避免踩坑示例：sub_filter 'src="/' 'src="/?v=$time_iso8601'; 会把 src="/js/app.js" 变成 src="/?v=2026-05-09T15:20:30+00:00js/app.js，明显错位。原因在于它在 "/ 后直接插值，没保留原路径

光加指纹不够，还得让没指纹的原始请求进不了缓存层，否则用户直连源站仍会缓存 /js/app.js：

在 CDN 或反向代理层设置规则：对不带 ?v= 的静态资源请求（如 /js/.*\.(js|css|png)$），直接拒绝或 302 跳转到带指纹的 URL
源站响应头中禁用 ETag 干扰：proxy_hide_header ETag; + add_header Cache-Control "no-cache";，避免因 HTML 被替换后内容变更但缓存头未刷新，导致脏读
若使用变量（如 $app_version），建议通过 map 指令从上游 Header 或 Cookie 提取，便于按环境/灰度开关控制

别只看配置，要实测响应体：

用 curl -H "Accept-Encoding: identity" http://your-domain/index.html 获取未压缩原始响应，搜索是否已注入 ?v=
检查响应头中 Content-Type 是否匹配你配置的 sub_filter_types，比如内联 JS 要求 application/javascript
打开浏览器开发者工具 → Network → 找 JS/CSS 请求，确认请求 URL 已含指纹，且状态码为 200（非 304）