Nginx sub_filter 可在响应返回路径上实时重写 HTML 资源链接注入版本指纹（如?v=20241105或.v20241105.js），无需修改后端代码或构建配置；需启用ngx_http_sub_module、确保响应为text/html且未压缩，并配合sub_filter_types、sub_filter_once off及防重复注入等策略，协同缓存层拦截无指纹请求以防止缓存穿透。
使用 Nginx 的
在缓存层动态注入资源版本指纹（如
或
），可有效防止缓存穿透——即用户绕过 CDN 或反向代理直接请求源站，导致未带指纹的原始 URL 被缓存并长期生效。关键在于：不修改后端代码、不依赖构建时硬编码，而是在响应返回路径上实时重写 HTML 中的资源链接。
确保 sub_filter 基础能力可用
Nginx 默认不启用
，需确认已加载
（主流发行版通常内置，但需显式启用）。在 location 块中配置前，注意以下前提：
响应内容类型必须是
（默认匹配），若需处理其他类型（如
），需用
显式声明
不支持正则，仅做简单字符串替换；若需更灵活匹配（如不同哈希长度、多格式路径），建议搭配
和多次规则，或改用
+ Lua
响应体必须未被压缩（gzip 已启用时，
失效），因此需在 gzip 前执行替换——通常把
放在
的 location 中，或使用
配合条件判断
注入查询参数型指纹（如 ?v=xxx）
适用于静态资源路径固定、只需追加版本参数的场景。例如将
替换为
：
在 proxy_pass 后的 location 中添加：
版本号建议通过 Nginx 变量动态生成，例如用
（需
或
预定义）或外部脚本输出的文件内容（配合
或
）
注意避免重复追加：原 HTML 若已含
，应先清除旧参数再注入新值，此时单靠
难以安全处理，推荐前置统一入口（如模板中只写无参路径）
重写路径型指纹（如 .v20241105.js）
更符合现代
前端
部署习惯（Content Hash），需匹配带扩展名的资源路径并插入版本标识：
面向设计的AXUI前端框架表单
面向设计的AXUI前端框架表单是一款包含表格、列表、弹窗等的AXUI前端框架表单下载。
下载
立即学习
“
前端免费学习笔记（深入）
”；
示例规则：
注意引号闭合和上下文（
或
），避免误替换内联脚本或注释中的字符串
为提升准确性，可结合
（Nginx 1.13.8+），让响应头
与注入版本对齐，辅助下游缓存决策
若资源路径含子目录（如
），需写完整匹配串，或拆分为多条规则覆盖常见路径前缀
防穿透的关键协同配置
仅注入指纹不够，还需阻断未带指纹的原始请求直达源站：
在缓存层（如 CDN 或 Nginx 缓存 proxy）设置：对不含
或
的静态资源请求，直接 403 或重定向到带指纹的 URL（用
+
）
源站 Nginx 可增加
（仅限非高并发场景，避免 if 性能损耗），或由上游网关统一拦截
所有缓存策略（
）应基于带指纹的完整 URL，确保同一资源不同版本各自独立缓存，互不影响
sub_filter?v=20241105.v20241105.jssub_filterngx_http_sub_moduletext/htmlapplication/xhtml+xmlsub_filter_typessub_filtersub_filter_once offlua-resty-httpsub_filtersub_filtergzip offgzip_vary off/js/app.js/js/app.js?v=20241105sub_filter '/js/app.js' '/js/app.js?v=20241105';
sub_filter '/css/main.css' '/css/main.css?v=20241105';
sub_filter_once off;$date_gmtlog_formatmapincludeset_by_lua_file?v=sub_filtersub_filter '.js"' '.v20241105.js"';
sub_filter '.css"' '.v20241105.css"';
sub_filter_once off;"'sub_filter_last_modified onLast-Modified/static/js/a.jsv=.v\d+return 302rewriteif ($args !~ v=) { return 403; }proxy_cache_valid