ServiceWorker拦截静态资源版本控制

本文深入剖析了如何在 Service Worker 中通过语义化缓存命名、精准 URL 匹配、install/activate 分阶段操作以及 skipWaiting/clients.claim 的协同控制，来可靠模拟静态资源的“版本镜像”效果——它并非 Service Worker 原生支持的快照式隔离，而是一套对 URL 一致性、缓存生命周期和激活时序极度敏感的工程实践；任何微小偏差（如路径斜杠、参数缺失、缓存名复用或激活延迟）都会导致新旧版本混用、缓存失效甚至首屏异常，堪称前端离线能力中细节决定成败的硬核课题。

不能靠 fetch 拦截实现真正的“版本镜像”——Service Worker 本身不提供资源快照式版本隔离能力，它只做缓存键匹配；所谓“镜像”，实际是通过缓存命名 + 精准 URL 匹配 + 请求参数一致性来模拟的。

缓存命名必须带语义化版本号，且每次更新需改名

Cache API 不支持同一缓存名下的原子替换，caches.open('static') 打开的是一个可变引用。若新旧版本共用同一个缓存名，cache.put() 会覆盖已有条目，但旧页面仍在使用该缓存名，极易导致混用。

• 正确做法：缓存名包含明确版本标识，如 static-v2.3.1 或 static-20260414
• install 阶段只往新缓存写，不操作旧缓存
• activate 阶段再批量清理非当前版本的缓存（如 caches.delete('static-v2.2.0')）
• 避免用时间戳以外的动态值（如哈希）作版本，否则构建产物未变时也触发重缓存，浪费带宽

预缓存 URL 必须与页面实际发起的请求 URL 完全一致

哪怕一个 trailing slash、一个查询参数、一个大小写差异，caches.match(request) 就会失败——这不是 bug，是 Cache API 的精确匹配设计。

• HTML 中写 ，预缓存数组里就必须写 '/js/app.js?v=2.3.1'
• 不要依赖相对路径：'js/app.js' 会被解析为相对于 sw.js 文件位置，而非站点根目录
• 若用 Webpack/Vite 构建，确保生成的资源清单（如 manifest.json）被读入 SW，并原样用于 cache.addAll()
• request.url 在 fetch 事件中是完整绝对 URL，匹配时别漏掉协议和域名（开发时常见 localhost vs 127.0.0.1 不一致）

fetch 事件中不能只靠 destination 判断静态资源

request.destination 在某些场景下不可靠：比如用 fetch('/api/config.json') 加了 {mode: 'no-cors'}，destination 可能是 'empty'；又或者字体文件在 Firefox 中可能返回 'font'，而 Chrome 是 'style'。

• 更稳妥的方式是结合正则匹配 URL 路径：/\.(js|css|png|jpg|woff2?|svg)$/i.test(request.url)
• 对 HTML 页面单独处理，用 request.destination === 'document' 是安全的
• 避免缓存带 credentials 的请求（如 credentials: 'include'），否则 cache.match() 因 credential mismatch 失败，除非你显式用 { ignoreSearch: false, ignoreVary: true } 控制匹配行为
• 如果资源来自 CDN，确保其 CORS 头允许缓存（Access-Control-Allow-Origin: *），否则 cache.put() 会静默失败

跳过等待（skipWaiting）和接管客户端（clients.claim）不是可选项

默认情况下，新注册的 Service Worker 会卡在 waiting 状态，直到所有受控页面关闭再激活。这意味着用户刷新页面时，仍由旧 SW 响应请求，旧缓存继续生效，“版本镜像”根本不会切换。

• 在 install 事件末尾加 self.skipWaiting()，让新 SW 跳过 waiting 直接进入 activating
• 在 activate 事件中调用 self.clients.claim()，立即接管所有已打开的 clients（包括当前页面）
• 这两步仅在需要“本次刷新即生效”时启用；生产环境若担心灰度风险，可改为按 query 参数或 header 控制是否执行
• 注意：clients.claim() 不会影响尚未加载完成的资源请求，那些仍走旧逻辑；所以关键资源最好在 HTML 中内联或预加载，减少首屏依赖 SW 的窗口期

真正难的不是写对 fetch 逻辑，而是让每个资源请求的 URL、缓存键、缓存名、激活时机四者严丝合缝——差一个字符或一毫秒，镜像就碎了。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~