Nginx 的 sub_filter 指令可动态为 HTML 中静态资源 URL 追加版本参数实现防缓存，需关闭 sub_filter_once、指定 sub_filter_types、禁用压缩，并推荐用精准路径匹配和 map 动态生成版本号。
使用 Nginx 的 sub_filter 指令可以在代理响应返回给客户端前，对 HTML 内容进行字符串替换，从而动态为静态资源（如 <script></script>、、src 或 href）追加版本参数（如 ?v=20241105），实现无需修改源站代码的防缓存控制。
启用 sub_filter 并配置基础替换规则
Nginx 默认不启用 sub_filter 的全局匹配和多次替换能力，需显式开启：
- 设置
sub_filter_once off：允许多次匹配同一响应体中的多个资源路径； - 设置
sub_filter_types text/html（可扩展为text/css application/javascript等，但注意响应头Content-Type必须匹配）； - 确保源站响应未压缩（即禁用
gzip或gzip_static），否则sub_filter无法处理压缩后的内容； - 若使用 HTTPS 反向代理，需确认后端返回的是明文 HTML（非 chunked 编码异常或流式响应干扰解析）。
精准匹配并重写静态资源 URL
避免误替换无关内容，推荐用正则风格的固定模式匹配（Nginx 1.19+ 支持 sub_filter 正则，旧版需靠多条普通替换模拟）：
- 例如将
src="/js/app.js"替换为src="/js/app.js?v=20241105"，可写为：sub_filter 'src="/js/app.js"' 'src="/js/app.js?v=20241105"'; - 更通用的做法是匹配所有以
.js或.css结尾的相对路径：sub_filter 'src="/' 'src="/?v=20241105';❌（太粗暴，易出错）
推荐结合变量 + 更安全的锚点，如：sub_filter 'src="/js/' 'src="/js/?v=20241105';（仅改 js 目录下资源） - 对
同理处理href属性。
动态生成版本号（避免硬编码）
硬写时间戳无法自动更新，可用 Nginx 内置变量或 Lua 辅助提升灵活性：
- 使用
$date_gmt或$date_local（需配合sub_filter+map预生成）； - 更可靠方式：通过
map定义一个每日更新的版本变量：
map $date_gmt $cache_bust {
~^(\d{4})-(\d{2})-(\d{2}) $1$2$3;
default "00000000";
}
然后在 location 中：sub_filter 'src="/js/' "src=\"/js/?v=$cache_bust\""; - 若需构建级精确控制（如 Git commit hash），建议由 CI 注入到 Nginx 配置模板中，或通过 Lua + shared dict 实现运行时版本同步。
注意事项与常见问题
sub_filter 是文本替换，不是 DOM 解析，因此有天然限制：
- 只作用于响应体，不修改 HTTP 头（如
ETag、Cache-Control），需额外配置响应头强化缓存策略； - 若 HTML 中资源路径含查询参数（如
src="a.js?t=1"），直接追加&v=xxx会导致语法错误，应先用sub_filter去除旧参数或统一标准化路径； - 不适用于内联脚本中的动态加载（如
import('/mod.js')），这类需前端逻辑配合； - 高并发下频繁替换可能轻微增加 CPU 开销，建议仅对关键 HTML 响应启用，避开 API 或二进制响应。
