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