如何用 Service Worker 拦截网络请求实现秒开的离线缓存体验-js教程-PHP中文网

实现秒开离线缓存的关键是立即调用event.respondWith()、精准匹配URL（注意查询参数）、Response流必须clone后双用、activate阶段彻底清理旧缓存。

如何用 service worker 拦截网络请求实现秒开的离线缓存体验

能实现秒开的离线缓存，关键不在“缓存什么”，而在于“什么时候用缓存”和“怎么避免缓存失效导致白屏”。

fetch 事件里必须第一时间调用 `event.respondWith()`

不调用或延迟调用，浏览器会走默认网络请求流程，缓存就完全没机会生效。常见错误是先做 URL 过滤、再判断缓存，结果漏掉 event.respondWith() 或放在条件分支外层。

正确做法是：所有 fetch 监听器开头就包裹 event.respondWith()，内部再做逻辑分支：

self.addEventListener('fetch', event => {
  // ✅ 第一行就声明响应方式
  event.respondWith(
    (async () => {
      const url = new URL(event.request.url);
      // 只对 HTML 页面走缓存优先
      if (url.pathname === '/' || url.pathname.startsWith('/page/')) {
        const cached = await caches.match(event.request);
        if (cached) return cached;
      }
      // 其他请求照常 fetch
      return fetch(event.request);
    })()
  );
});

不要在 if 外部写 return fetch(...)，否则未命中缓存的页面请求仍会走网络，失去离线能力
注意 event.request.destination，避免对 script、style 等资源误判为页面请求
本地开发时，localhost 允许 HTTP，但上线必须 HTTPS，否则注册直接失败

`caches.match()` 匹配不到静态资源？检查 URL 和缓存键一致性

缓存成功但匹配失败，90% 是因为请求 URL 和缓存时存的 URL 不一致。比如缓存了 /styles/main.css，但页面请求的是 /styles/main.css?v=2，caches.match() 默认不忽略查询参数。

解决方法分场景：

预缓存静态资源（install 阶段）：确保 cache.addAll() 里的路径和页面实际请求路径完全一致，包括尾部斜杠、大小写、查询参数
运行时缓存动态资源：用 new Request(url, { ignoreSearch: true }) 构造匹配请求，或在 caches.match() 传第二个参数：caches.match(request, { ignoreSearch: true })
调试技巧：在 DevTools 的 Application → Cache Storage 里手动展开缓存，确认存进去的 key 是什么格式

Response 流只能读一次，缓存前必须 `clone()`

这是最隐蔽的坑：你 fetch 到一个 Response，直接 return response 给浏览器，再想 response.json() 或塞进 cache，会报 TypeError: Failed to execute 'json' on 'Response': body stream already read。

根本原因是 Response.body 是 ReadableStream，消费一次就关闭。所以只要需要“既返回给页面，又存进缓存”，就必须克隆：

fetch(event.request)
  .then(networkResponse => {
    // ✅ 克隆一份用于缓存
    const toCache = networkResponse.clone();
    // 返回原始响应给页面
    event.respondWith(networkResponse);
    // 异步缓存克隆体
    caches.open('v1-dynamic').then(cache => cache.put(event.request, toCache));
  });

不要对 networkResponse 调用 .text()、.json()、.arrayBuffer() 后再缓存，那已经消耗流了
clone() 不是深拷贝，只是创建新流指针，开销很小，但必须做
如果只缓存不返回（比如后台同步），可以不 clone；但凡要“一鱼两吃”，必 clone

激活阶段清理旧缓存不彻底，导致资源错乱

缓存版本升级后，旧缓存不删干净，可能让新 Service Worker 读到过期的 CSS 或 JS，页面样式错乱或脚本报错，且用户刷新也无效。

关键点是：清理逻辑必须在 activate 事件里，且用 event.waitUntil() 包裹整个 Promise 链：

self.addEventListener('activate', event => {
  const currentCaches = ['v1-static', 'v1-dynamic'];
  event.waitUntil(
    caches.keys().then(keys => {
      return Promise.all(
        keys.map(key => {
          if (!currentCaches.includes(key)) {
            return caches.delete(key); // ✅ 必须 return，否则 Promise.all 不等它
          }
        })
      );
    })
  );
});