本文深入剖析了PWA中Service Worker注册失败与离线缓存失效的典型陷阱和实战解法：从HTTPS安全上下文、注册路径规范、生命周期状态识别，到install阶段HTML及静态资源的全量精准缓存策略，再到fetch事件中必须依赖request.destination精确分流文档请求、静态资源与API调用——每一步都直击开发者踩坑最频繁的“看似正常却离线打不开”的核心痛点，并揭示了导航预加载、304响应处理、构建产物路径对齐等易被忽视的关键细节，帮你绕过静默失败、白屏、缓存不更新等顽疾，真正落地可靠离线体验。

Service Worker 注册失败，八成是 HTTPS 或路径问题；离线缓存打不开 HTML，几乎一定是 request.destination 没判对或缓存资源不完整。

注册失败的三个硬性条件：HTTPS、localhost、路径正确

浏览器只在安全上下文中允许注册 Service Worker：https:// 或 http://localhost 可行，http://127.0.0.1、http://192.168.x.x、file:// 全部静默失败——控制台只显示 Failed to register a ServiceWorker，没堆栈也没提示。

注册路径必须相对于页面 URL，不是 JS 文件位置。比如页面地址是 /blog/article.html，想注册根目录下的 sw.js，就得写 navigator.serviceWorker.register('/sw.js')，写成 './sw.js' 或 'sw.js' 会 404。

• 检查 DevTools → Application → Service Workers 面板，Status 是 Waiting 表示新版本已安装但未激活；Redundant 表示被覆盖，通常因 sw.js 内容未变，浏览器跳过更新
• sw.js 文件本身不能被服务器加 Cache-Control: no-store 等禁止缓存头，否则注册会失败
• 注册代码必须放在 window.addEventListener('load', ...) 里，不能塞在 DOMContentLoaded 或异步加载逻辑中

install 事件里缓存 HTML 的关键：预加载 + 路径全量

只缓存 /index.html 是不够的——HTML 加载后会发起对 /app.js、/style.css、/logo.png 的请求，这些没进缓存，离线时照样报 net::ERR_FAILED。

用 cache.addAll() 最简但最脆：列表里任一资源返回非 2xx（比如 404 图片、CORS 失败的字体），整个操作就中断，一个都不缓存。适合构建后路径绝对稳定的场景，例如打包输出的 /static/js/main.a1b2c3.js。

• 路径必须以 / 开头，表示站点根目录；cache.addAll(['index.html']) 会找相对路径，大概率失败
• 不要缓存带查询参数的 URL，如 /data.json?v=1.2，不同参数算不同 key，缓存空间浪费且难以管理
• HTML 文件本身建议单独处理：用 cache.put() 手动构造 fallback 响应，避免白屏，比如 new Response('

  Offline

  ', {headers: {'Content-Type': 'text/html'}})

fetch 事件中必须区分 request.destination

event.respondWith(caches.match(event.request) || fetch(event.request)) 这种“一刀切”写法会导致严重问题：API 请求（fetch('/api/user')）也被匹配缓存，用户永远看不到新数据；POST 表单提交直接静默失败，因为缓存里没有 POST 请求的响应。

request.destination 是唯一可靠判断请求用途的字段：

• request.destination === 'document' → 页面主框架加载（地址栏输入、链接跳转），必须拦截并优先返回缓存，否则离线打不开
• request.destination === 'script' 或 'style' 或 'image' 或 'font' → 静态资源，可缓存兜底
• request.destination === 'empty' 或空字符串 → 通常是 fetch() 发起的无目标请求（如 fetch('/api')），一律走网络，不缓存

别忽略导航预加载（navigation preload）：它会让 HTML 请求绕过你的 fetch 事件。如果没显式禁用或处理，首次离线访问可能直接失败。可在 activate 事件里调用 self.registration.navigationPreload.enable()，但必须在 fetch 中主动处理 event.preloadResponse。

HTML 缓存更新失效的隐蔽原因

改了 index.html 内容，但离线还是旧版？常见原因不是缓存没更新，而是服务端返回了 304 Not Modified —— 此时 response.body 为空，cache.put(request, response) 会抛错并中断流程。

Vue/React 的 history 路由也容易踩坑：Nginx 配置了 try_files $uri $uri/ /index.html，但 SW 缓存的是旧版 /index.html，而新 JS bundle 已更新，结果 hydration 失败、白屏。

• 缓存 HTML 前必须 clone 响应并检查 response.status === 200，否则 cache.put() 会失败
• 确保 SW 缓存的 HTML 和服务端 fallback 路由指向同一份构建产物，路径和哈希需严格对齐
• 更新缓存时，activate 事件里清理旧 cache 很重要，否则多个版本共存，占用空间且逻辑混乱

离线功能真正生效，往往卡在「缓存看起来全了，但某个小资源漏掉」或者「destination 判错导致 HTML 请求根本没进缓存逻辑」——调试时盯着 Application → Cache Storage 和 Network 面板里每个请求的 initiator 和 destination 字段，比看 console 报错更管用。

理论要掌握，实操不能落！以上关于《PWAServiceWorker注册与缓存配置教程》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！