sub_filter可在Nginx反向代理层对HTML等文本响应实时替换字符串，用于动态注入版本号（如$v_msec）解决缓存更新问题，但需禁用gzip/分块、显式配置sub_filter_types，并规避跨buffer边界与重复注入风险。
在 Nginx 反向代理场景中，sub_filter 可以在响应体返回给客户端前，对 HTML 内容做实时字符串替换。结合版本号注入，能有效解决前端静态资源（如 js、css）因浏览器或 CDN 缓存导致的更新不及时问题——无需修改源站代码，纯代理层干预。
确保 sub_filter 基础能力可用
Nginx 默认不启用 sub_filter 的完整功能，需确认以下几点：
- 使用的是开源版 Nginx（≥1.9.4）或 Tengine（支持更稳定），OpenResty 也兼容；
-
sub_filter指令仅作用于text/html和text/css等明确 MIME 类型的响应，默认不处理压缩内容； - 若后端启用了
gzip，必须在 Nginx 代理层先解压再替换，即开启sub_filter_once off并配置gzip_disable "msie6";或统一禁用后端 gzip（推荐在 proxy 层控制压缩）； - 需启用
sub_filter_types *或显式列出text/html application/javascript text/css等类型。
动态注入资源版本号（时间戳或哈希）
单纯写死版本号（如 ?v=1.0.0）无法实现“动态”，真正实用的方式是结合 Nginx 变量生成实时标识：
- 用
$msec（毫秒级时间戳）实现每秒级更新：sub_filter '<script src="/app.js">' '<script src="/app.js?v=$msec">';</script> - 更稳妥的做法是用
$date_gmt或自定义 Map 变量映射构建版本（如从文件修改时间或环境变量读取）； - 若需统一管理多个资源，可配合正则式替换（需开启
sub_filter_last_modified on+sub_filter_once off），例如：sub_filter 'src="/' 'src="/?v=$msec&';
注意：该方式会匹配所有src="/xxx"，需评估是否影响其他路径（如 API 接口）。
规避常见陷阱与增强可靠性
sub_filter 行为敏感，稍有不慎就会失效或污染内容：
立即学习“前端免费学习笔记（深入）”；
- HTML 必须是未压缩、未分块（chunked）传输；若后端返回
Transfer-Encoding: chunked，Nginx 需设proxy_buffering on并合理配置proxy_buffer_size和proxy_buffers，确保完整接收后再处理； - 替换内容不能跨 buffer 边界（默认 buffer 小），建议增大：
proxy_buffer_size 128k;proxy_buffers 4 256k;proxy_busy_buffers_size 256k; - 避免重复注入：启用
sub_filter_once off可多次匹配，但需确保正则或字符串足够精确，否则可能把v=123替换成v=1718...&v=1718...； - 不建议对内联
<script></script>或 base64 资源做替换，优先聚焦外链src和href属性。
替代方案对比：什么情况下不该用 sub_filter
虽然轻量，但 sub_filter 不是万能解法：
- 若页面大量使用动态模板（如 Vue/React 的 SSR 输出），HTML 结构不稳定，正则易误伤；
- 需要按资源哈希精准打标（如 Webpack 的
[contenthash]），sub_filter无法读取构建产物信息，此时应由构建流程输出版本 manifest，并由后端或 Lua 脚本注入； - 高并发下频繁字符串扫描有轻微性能开销，QPS 极高时建议改用
ngx_http_sub_module的二进制匹配优化版，或迁移到 OpenResty + Lua 实现更灵活的 DOM 级操作。
