Service Worker注册失败主因是协议不安全或注册时机不当；缓存策略错误、版本隔离缺失、跨域资源opaque响应及重定向处理不当是离线体验差的常见原因。

Service Worker 注册失败或不生效

最常见的原因是 Service Worker 文件路径不在 HTTPS 下（本地 file:// 协议也无效），或注册脚本没在页面加载早期执行。浏览器只允许在安全上下文（HTTPS 或 localhost）中注册 ServiceWorker，且必须确保 navigator.serviceWorker.register() 调用发生在页面 DOM 加载完成前或 DOMContentLoaded 事件中。

• 检查控制台是否报错 Uncaught DOMException: Failed to register a ServiceWorker: The URL protocol of the current page is not supported. —— 这说明协议不合法
• register() 返回的 Promise 被 reject 时，务必加 .catch() 捕获并打印错误，例如：

  navigator.serviceWorker.register('/sw.js').catch(err => console.error('SW registration failed:', err));

• 确保 sw.js 和页面同源，且响应头不含 Cache-Control: no-cache（否则 Chrome 可能拒绝解析）

缓存策略选错导致资源 stale 或反复拉取

离线体验差，往往不是没缓存，而是缓存了不该缓存的、或该更新时不更新。比如对 HTML 使用 stale-while-revalidate 策略，但没监听 fetch 事件做拦截；又或者对 API 接口用了 cache-first 却没配版本键（如 api/v1/users?ts=123），导致旧数据长期滞留。

• 静态资源（JS/CSS/图片）推荐 cache-first + 版本化文件名（如 main.a1b2c3.js），避免手动清理缓存
• HTML 文件建议用 network-first（带 fallback 到缓存），因为它是入口，需保证结构最新；可配合 navigationPreload 加速首屏：

  self.addEventListener('activate', event => { event.waitUntil(self.clients.claim()); });
  self.addEventListener('fetch', event => {
    if (event.request.destination === 'document') {
      event.respondWith(fetch(event.request).catch(() => caches.match('/offline.html')));
    }
  });

• 避免在 install 阶段无条件 caches.addAll([...]) 所有资源——大文件会阻塞安装，应分组或按需缓存

跳过等待（skipWaiting）和客户端 Claim 不触发更新

即使你发布了新版 sw.js，老版仍可能持续控制页面，直到用户关闭所有标签页——这是默认行为，目的是防止正在运行的页面被突然中断。用户刷新后看到的仍是旧逻辑，除非你主动干预。

• 新版 SW 安装后，调用 self.skipWaiting()（在 install 事件中），并配合 clients.claim()（在 activate 中），才能让新 SW 立即接管
• 但要注意：如果页面已有未完成的 fetch 请求或 IndexedDB 事务，skipWaiting() 可能被忽略；建议在 activate 中先 event.waitUntil(caches.delete('old-cache')) 清理旧缓存，再 clients.claim()
• 前端可监听 controllerchange 事件提示用户刷新：

  navigator.serviceWorker.addEventListener('controllerchange', () => {
    console.log('New SW is now controlling this page');
  });

调试 Service Worker 缓存状态很麻烦

Chrome DevTools 的 Application > Cache Storage 和 Service Workers 面板是唯一直观入口，但容易漏看细节：比如缓存键是否含 query string、Response 是否为 opaque（跨域请求无法读取）、缓存是否被 Cache-Control: no-store 绕过。

• 在 fetch 事件中加日志：

  self.addEventListener('fetch', event => {
    console.log('[SW] Fetching:', event.request.url, 'from', event.request.destination);
    event.respondWith(...);
  });

  注意：仅在 DevTools 打开时日志可见，生产环境勿留
• 用 caches.open('my-cache').keys() 在 Console 中手动查缓存项，确认 URL 是否标准化（例如是否自动去除了 trailing slash）
• 跨域字体、CDN 图片等资源若设为 no-cors，返回 Response 是 opaque 类型，无法被 caches.put() 存储——必须服务端配 Access-Control-Allow-Origin 或改用 CORS 模式请求