Service Worker fetch 拦截实现离线镜像方案

本文深入剖析了Service Worker中所谓“离线镜像”的本质局限与工程化落地要点：它并非真正的原子化版本快照，而是依赖语义化缓存命名（如static-prod-v2.3.1）、install/activate严格分阶段控制（新缓存只写不删、旧缓存延至activate清理）、以及URL完全精确匹配（含查询参数与协议路径）共同模拟出的可控缓存切换机制；同时警示避免资源哈希污染缓存名、禁用不可靠的request.destination判断、强制采用绝对路径与构建产物清单对齐——稍有偏差，轻则缓存失效，重则白屏或新旧逻辑错乱，堪称前端离线能力中最易踩坑也最需精密协同的关键实践。

Service Worker 无法实现真正的“版本镜像”，所谓镜像只是通过语义化缓存名 + 精准 URL 匹配 + 分阶段生命周期控制模拟出来的效果。硬套“镜像”概念反而容易在更新时出现资源错乱、白屏或旧 JS 执行新 HTML 的灾难性问题。

缓存名必须带可维护的语义化版本，不能用 v1/v2 这类裸数字

Cache API 没有原子替换能力，caches.open('static') 打开的是一个可变引用。如果新旧版本共用同一个名字，cache.put() 会覆盖条目，但已打开页面仍可能读到被覆盖前的响应体（尤其在 response.body 流未完全消费时）。

正确做法是让缓存名自带环境与构建标识：

• static-prod-20260428（日期型，适合每日构建）
• static-prod-v2.3.1（语义化版本，需和 package.json 对齐）
• static-prod-git commit hash（最精确，但需构建时注入）

避免用资源哈希（如 app.a1b2c3.js）直接拼进缓存名——它会导致每次构建都生成新缓存名，即使内容没变，白白浪费用户磁盘空间和带宽。

install 阶段只写新缓存，activate 阶段才删旧缓存

这是防止多版本缓存共存引发冲突的关键分界点。若在 install 中就调 caches.delete()，可能误删当前页面正在使用的缓存。

标准流程如下：

• install：调 caches.open('static-prod-v2.3.1')，然后 cache.addAll([...])，完成后调 self.skipWaiting()
• activate：先 self.clients.claim() 确保新 SW 接管所有客户端；再遍历 caches.keys()，对不匹配当前版本名的缓存调 caches.delete(key)

注意：self.clients.claim() 不是可选操作——没有它，旧页面不会触发新 SW 的 fetch 事件，离线访问依然走老逻辑。

URL 必须完全一致才能 match，连 ?v= 和末尾 / 都算不同资源

cache.match() 是精确匹配，不是模糊查找。哪怕页面请求的是 /logo.png?v=2.3.1，而你预缓存的是 /logo.png，结果就是 miss。

常见失配点：

• HTML 中写