Service Worker 拦截实现静态资源本地镜像存储方法

本文深入解析了如何利用 Service Worker 实现静态资源的“伪版本镜像”缓存策略，强调其本质并非真正的快照隔离，而是通过语义化缓存命名（如 static-v2.3.1）、install/activate 严格分阶段操作（安装时只写新缓存、激活时才安全清理旧缓存并调用 clients.claim()），以及 URL 精确匹配（协议、域名、路径、参数全一致）三者协同模拟出稳定可靠的版本化缓存行为；同时揭露了常见陷阱——如复用缓存名导致运行中页面读取混合内容、动态哈希或时间戳引发无效重缓存、相对路径解析偏差、跨域资源静默失败，以及误用 request.destination 判断资源类型等，并给出正则匹配 URL 后缀等更鲁棒的实践方案，助你构建真正健壮、可维护的离线优先 Web 应用。

Service Worker 无法实现真正的“版本镜像”——它不保存资源快照，也不隔离不同版本的缓存内容；所谓镜像，是靠缓存命名 + 精确 URL 匹配 + 分阶段生命周期控制共同模拟出来的行为。

缓存名必须带语义化版本号，不能复用同一名称

Cache API 的 caches.open('static') 返回的是一个可变引用，不是只读快照。如果新旧版本共用 'static' 这个名字，cache.put() 会直接覆盖已有条目，而正在运行的老页面仍可能从该缓存中读取被覆盖后的混合内容，造成 JS 执行错乱或样式丢失。

正确做法是让缓存名自带明确版本标识：

• static-v2.3.1 或 static-20260414 —— 推荐，人类可读、构建可控
• 避免仅用哈希（如 static-abc123）作版本：构建产物未变时哈希也可能变，触发无意义重缓存，浪费带宽和用户存储空间
• 不要用时间戳以外的动态值（比如 Date.now()）——开发时反复刷新会导致每秒一个新缓存，快速占满 Storage Quota

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

安装阶段（install）的核心任务是把新版资源写进新缓存，**绝不能碰旧缓存**。否则还没激活就删了老缓存，已打开的页面立刻离线失败。

激活阶段（activate）才是安全清理窗口：

• 调用 caches.keys() 获取所有缓存名
• 用 .filter(name => name !== CACHE_NAME) 筛出非当前版本的缓存
• 对每个匹配项调用 caches.delete(name)
• 最后务必加 self.clients.claim()，让新 SW 立即接管所有客户端（否则要等用户关掉再重开页面）

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

caches.match(request) 是精确匹配：协议、域名、路径、查询参数、大小写、尾部斜杠，缺一不可。哪怕 HTML 中写了 ，预缓存数组里漏掉 ?v=2.3.1，匹配就失败。

常见坑点：

• 相对路径如 'js/app.js' 会被解析为相对于 sw.js 文件位置，不是站点根目录 → 统一用绝对路径 '/js/app.js'
• 开发时 localhost 和 127.0.0.1 被视为不同源 → request.url 在 fetch 事件里是完整 URL，匹配前别漏掉协议和 host
• CDN 资源若没配 Access-Control-Allow-Origin: *，cache.put() 会静默失败（尤其字体、JSON 等跨域资源）

fetch 拦截别依赖 request.destination 判断资源类型

request.destination 在某些场景下不可靠：比如 fetch('/api/config.json', {mode: 'no-cors'}) 可能返回 'empty'；Firefox 加载 woff2 字体时 destination 是 'font'，Chrome 却是 'style'。靠它做静态资源路由容易漏判或误判。

更稳妥的方式是正则匹配 URL 路径：

const isStaticResource = /\.(js|css|png|jpg|jpeg|gif|svg|woff2?|ttf|eot)$/i.test(request.url);

HTML 页面可以单独用 request.destination === 'document'，这个是规范保证安全的；其他一律建议走 URL 路径判断。

真正难处理的其实是带 credentials: 'include' 的请求：Cache API 默认会因 credential mismatch 拒绝匹配，除非你显式传 { ignoreSearch: false, ignoreVary: true } ——但这类请求本就不该进静态缓存，直接放行更稳妥。

今天关于《Service Worker 拦截实现静态资源本地镜像存储方法》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！