ServiceWorker实现离线应用教程详解

本文深入解析了使用 JavaScript Service Worker 构建可靠离线应用的核心实践与常见陷阱：从注册失败的根源（路径、scope、HTTPS及时机）到缓存策略的精准分层（install预缓存静态资源 vs fetch运行时处理动态请求），再到关键编码规范（必须用 event.respondWith() 而非 return）、调试技巧（离线模拟、缓存命中验证、手动清理旧缓存），以及缓存策略选型对用户体验的隐性影响——帮你避开“看似正常却离线失效”的坑，真正实现稳定、可维护、用户无感的离线体验。

Service Worker 注册失败的常见原因

注册不成功，八成是路径或作用域问题。navigator.serviceWorker.register() 的第一个参数必须是相对于站点根目录的路径（比如 "/sw.js"），不能写成 "./sw.js" 或 "sw.js"。另外，Service Worker 只能控制其脚本所在路径及子路径下的页面——如果 sw.js 放在 /assets/sw.js，它默认只能接管 /assets/ 下的页面，得用 scope 选项显式设为 "/" 才能覆盖整个站点。

还要确认当前环境：必须是 HTTPS（本地 localhost 除外），且页面已完全加载后再调用注册（避免在 document.write 或未就绪的 DOM 中执行）。

• 检查浏览器控制台是否有 Failed to register a ServiceWorker 错误，点开看具体提示
• 打开 Application → Service Workers 面板，确认状态是否为 “activated” 而非 “waiting” 或 “red”
• 首次注册后刷新页面不会立即生效，需关掉所有标签页再重开，或勾选 “Update on reload” 强制更新

缓存静态资源时如何区分 runtime 和 install 时机

install 事件适合预缓存确定不变的资源（如 HTML、CSS、JS、图标），用 caches.open().addAll() 一次性写入；fetch 事件则处理运行时请求（比如 API 响应、用户上传的图片），需要手动 event.respondWith() 并决定是否缓存、缓存多久。

混用这两类逻辑容易导致离线时拿不到动态内容，或者缓存爆炸。例如把用户头像 URL 直接塞进 install 列表，下次头像更新就永远看不到新图。

• 预缓存清单建议用构建工具生成（如 Workbox 的 generateSW），避免手写漏项
• API 请求别盲目缓存，加判断：只缓存 GET 请求，忽略带 Authorization 或 cookie 的敏感请求
• 用 caches.match(event.request) 查缓存前，先用 new URL(event.request.url).origin === location.origin 过滤跨域请求，防止意外拦截 CDN 或第三方资源

fetch 事件中 return 与 event.respondWith() 的区别

在 fetch 事件监听器里，不能直接 return fetch(...)，必须用 event.respondWith() 包裹响应 Promise。否则浏览器会忽略你的逻辑，走默认网络请求——这会导致离线时白屏，因为没拦截到请求。

常见错误写法：self.addEventListener('fetch', e => { if (e.request.url.endsWith('.png')) return caches.match(e.request); }) —— 这里 return 只是退出函数，不是响应请求。

• 正确写法是：e.respondWith(caches.match(e.request).then(r => r || fetch(e.request)))
• 注意 respondWith() 内部 Promise 必须 resolve 一个 Response 对象，不能是 null 或 undefined，否则报 TypeError: Failed to execute 'respondWith' on 'FetchEvent'
• 想跳过缓存直连网络？仍需 e.respondWith(fetch(e.request))，不能省略包裹

调试离线行为时最该盯住的三个地方

离线效果不理想，往往不是代码写错，而是测试方式不对。重点看这三处：

• Chrome DevTools 的 Application → Service Workers 面板右上角勾选 “Offline”，再刷新——别只关 WiFi，那可能还走本地 DNS 缓存或 HTTP/2 推送
• Network 面板里每个请求的 “Size” 列显示 (from ServiceWorker) 才算真命中缓存；若显示 (from disk cache) 或空白，说明没走 SW
• 在 Console 里手动执行 caches.keys().then(keys => keys.forEach(k => caches.delete(k))) 清掉旧缓存，再重新 install，避免旧版本 SW 持续干扰

缓存策略看似简单，但 cache-first、network-first、stale-while-revalidate 的取舍，取决于资源更新频率和用户体验容忍度——这些细节不会报错，但会悄悄让离线体验变味。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。