如何用 Service Worker 实现“离线即走”的静态资源静默更新策略

如何用 Service Worker 实现“离线即走”的静态资源静默更新策略

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

“离线即走”听起来很理想，但它的目标其实很具体：不是让应用在断网时直接闪退，而是确保用户即便在无网或信号极差的环境下，也能瞬间打开页面，看到一个功能完整的界面。更关键的是，当网络恢复后，所有更新都在后台悄无声息地完成——不弹窗、不刷新、不打断用户手头的任何操作。要实现这种“无感”体验，核心在于Service Worker的精准调度：在安装和激活阶段完成资源的预取与版本切换，同时在拦截请求时，对静态资源执行严格的Cache First策略，并借助skipWaiting()和clients.claim()来消除新旧版本交替时的任何延迟。

install 阶段必须调用 event.waitUntil() + caches.open().addAll()

静默更新的基石，其实在安装阶段就已经奠定。所有核心的静态资源——HTML、CSS、Ja vaScript、关键图标——必须在Service Worker安装的那一刻，就全部预取并存入新的缓存。这一步绝不能偷懒留到用户请求时再做，否则第一次离线访问就会遭遇失败。

• 缓存版本号（例如caches.open('static-v2')中的v2）必须随着每次构建而改变。如果版本号不变，浏览器会认为没有更新，直接跳过整个安装过程。
• addAll()方法里的资源路径列表必须绝对精确。这里有个常见的坑：在Service Worker作用域内，相对路径（如./main.js）很可能解析失败，稳妥的做法是一律使用从根目录开始的绝对路径（如/main.js）。
• 在addAll()成功后，务必立即调用self.skipWaiting()。少了这一步，新的Service Worker会一直处于“等待”状态，直到用户关闭所有相关标签页，更新也就无从谈起了。

activate 阶段要清理旧缓存 + 调用 clients.claim()

安装新版本后，旧缓存如果不清除，不仅会白白占用存储空间，还可能引发更隐蔽的问题：假如旧的缓存名（比如static-v1）依然存在，而拦截请求的逻辑又没有做好版本判断，就可能错误地读取到过期的资源。

• 通过caches.keys()获取所有缓存名称，然后用.filter(name => !name.startsWith('static-v'))这类条件或白名单进行比对，只保留当前版本的缓存。
• caches.delete()是异步操作，必须包裹在event.waitUntil()中，否则清理过程可能会被意外中断。
• 调用self.clients.claim()是让新Service Worker立即接管所有已打开页面的关键。这确保了“离线即走”体验的连贯性，避免了页面因被旧Worker控制而出现的短暂白屏或功能不一致。

fetch 事件里对静态资源强制 Cache First，且禁止 fallback 到 network

所谓“静默”，精髓就在于用户毫无感知。如果在fetch事件中，为缓存未命中写了诸如|| fetch(request)这样的网络回退逻辑，那么在断网时，这个回退请求必然会失败，从而导致页面报错或降级——这就不再是静默，而是把问题直接暴露给了用户。

• 策略应仅应用于明确的静态资源。可以通过正则匹配请求URL的后缀来实现：request.url.match(/\.(js|css|html|png|svg|woff2)$/i)。
• 响应必须且只能来自caches.match(request)，不进行任何fetch()尝试。如果匹配不到缓存，直接返回一个404响应或预置的离线页面即可。
• 注意避免在caches.match之前对请求对象进行request.clone()。克隆操作会消耗请求体的流（stream），可能导致后续如果真的需要fetch时，无法再读取请求体。

构建流程必须生成内容哈希并注入 SW 脚本

仅仅依赖手动修改的缓存版本号（如static-v2）是远远不够的。如果文件内容没变但版本号变了，会造成无效的缓存更新；反之，如果内容变了但版本号忘了改，用户又会一直读到旧文件。真正可靠的依据，是文件内容本身。

• 在Webpack或Vite等构建工具中，启用contenthash配置，生成像main.a1b2c3d4.js这样带哈希的文件名。
• 将这份哈希化后的、精确的资源列表（不要用通配符）注入到Service Worker脚本中。这通常可以通过workbox-webpack-plugin的InjectManifest模式，或在构建后替换脚本模板中的变量（如ASSETS_TO_CACHE）来实现。
• 切忌使用cache.addAll(['/'])这种模糊的方式。它不仅严重依赖服务器的目录索引配置，而且你完全无法控制到底缓存了哪些文件，粒度太粗，极易出错。

最后，还有一个极其重要却常被忽略的细节：Service Worker的作用域（scope）。它的默认作用域是其脚本文件所在的目录。如果把sw.js放在/assets/目录下，那么它就只能控制/assets/下的请求。因此，必须将Service Worker脚本放在网站的根目录，并且在注册时显式指定作用域：na vigator.serviceWorker.register('/sw.js', { scope: '/' })。否则，连HTML文件本身都无法被缓存，“离线即走”也就成了空中楼阁。