Service Worker 深度解析：拦截请求、离线缓存与推送通知

1.1 一段独立于页面的 Worker#

Service Worker 本质上是一个运行在浏览器独立线程中的 JavaScript 上下文，它无法访问 window、document，因此不能直接操作 DOM。它与主线程之间通过 postMessage 通信，通过 clients API 访问受控页面。

一个常被混淆的概念：Service Worker ≠ Web Worker。Web Worker 是为计算密集型任务而生的临时线程，生命周期与页面绑定；Service Worker 则是网络代理 + 后台事件中心，页面关闭后仍能接收 push、sync 事件。

1.2 三个关键特性#

第三点尤其重要：很多人会写 setInterval(() => fetch('/heartbeat'), 60000)，结果在 Chrome 上运行良好，但 Firefox/Safari 在闲置几分钟后就会杀掉 Service Worker 进程——因为它们把 SW 视作”按需唤醒”的事件循环，而不是常驻进程。

1.3 一次完整的 fetch 拦截时序#

1
// 页面发起请求
2
fetch('/api/users/42');

这一行代码背后发生了什么？

关键点在于：Service Worker 并不是”先让网络请求飞一会儿，再拦截”，而是从源头取代了浏览器默认的网络栈。这就是为什么它能在断网时仍能返回内容——fetch 事件根本不进网络。

2.1 注册与字节级更新检测#

1
// 任何调用 SW 的页面（通常是根页面）
2
navigator.serviceWorker.register('/sw.js', {
3
  scope: '/app/',           // 受控路径前缀
4
  type: 'module',           // 现代写法，可使用 ESM
5
  updateViaCache: 'none',   // 不要用 HTTP 缓存来缓存 SW 自身
6
});

浏览器逐字节对比 sw.js 的内容（不是 HTTP 状态、不是 ETag，而是响应体的实际字节）。一旦发现不同，立即启动新的 SW 走 install 流程。

这就解释了为什么 importScripts('/cache-buster.js?ts=123') 并不会触发更新——SW 文件本身没变。

2.2 install 与 skipWaiting#

1
const CACHE = 'app-v3';
2

3
self.addEventListener('install', (event) => {
4
  event.waitUntil((async () => {
5
    const cache = await caches.open(CACHE);
6
    // 关键：precache 时全部成功才会 install 成功
7
    await cache.addAll([
8
      '/', '/styles.css', '/app.js', '/offline.html',
9
    ]);
10
    // self.skipWaiting() 表示：不要等旧页面关闭，立即进入 waiting
11
    await self.skipWaiting();
12
  })());
13
});

skipWaiting() 是一个需要谨慎使用的开关。它会让新 SW 立即进入 activated 状态，但旧 SW 控制下的页面并不会重新触发 fetch 拦截。要真正”接管”控制权，还需要在 activate 中调用 clients.claim()。

2.3 activate 与 clients.claim#

1
self.addEventListener('activate', (event) => {
2
  event.waitUntil((async () => {
3
    // 1. 清理旧版本缓存
4
    const keys = await caches.keys();
5
    await Promise.all(
6
      keys
7
        .filter((k) => k !== CACHE)
8
        .map((k) => caches.delete(k))
9
    );
10
    // 2. 立即接管所有未受控页面
11
    await self.clients.claim();
12
  })());
13
});

clients.claim() 让当前 SW 立即接管当前已打开但未被旧 SW 控制的标签页。两者配合 skipWaiting() 构成了”用户刷新前即可生效”的更新方案。

2.4 一张表看懂状态机#

3.1 经典五策略对照#

下面我们重点看两种生产中最常用也最容易写错的策略。

3.2 Stale-While-Revalidate 完整实现#

1
async function staleWhileRevalidate(request) {
2
  const cache = await caches.open(CACHE);
3
  const cached = await cache.match(request);
4

5
  // 关键：无论是否命中，都要触发后台更新
6
  const networkUpdate = fetch(request)
7
    .then((response) => {
8
      // 重要：只缓存 200 + basic/cors
9
      if (response && response.status === 200) {
10
        cache.put(request, response.clone());
11
      }
12
      return response;
13
    })
14
    .catch(() => null);
15

16
  return cached || (await networkUpdate) || Response.error();
17
}

注意三个易错点：

1. response.clone() 必不可少——response 是流，读取一次后就被消费，需要克隆后写入缓存；
2. 不要缓存非 2xx 响应——5xx、404 也会被错误缓存；
3. networkUpdate 错误吞掉——离线时 fetch reject，但我们不能让它冒泡到 waitUntil 之外。

3.3 Cache First + 后台更新的”伪 SWR”#

1
async function cacheFirstWithRefresh(request) {
2
  const cache = await caches.open(CACHE);
3
  const cached = await cache.match(request);
4

5
  const fetchPromise = fetch(request).then((response) => {
6
    if (response.ok) cache.put(request, response.clone());
7
    return response;
8
  });
9

10
  return cached || fetchPromise;
11
}

与 SWR 的区别：用户首次访问是网络响应，之后直接拿缓存。和”先返回缓存 + 后台更新”的区别在于是否阻塞。生产中，对于带哈希指纹的构建产物（app.a3f9b2.js），这种策略最稳。

3.4 按 URL 分流：路由表设计#

1
const ROUTES = [
2
  { pattern: /^\/api\/v1\/user/, strategy: 'networkOnly' },
3
  { pattern: /^\/api\/v1\/posts/, strategy: 'staleWhileRevalidate' },
4
  { pattern: /\.(js|css|woff2?)$/, strategy: 'cacheFirst' },
5
  { pattern: /\.(png|jpg|webp|avif)$/, strategy: 'cacheFirst' },
6
  { pattern: /\.html$/, strategy: 'networkFirst' },
7
];
8

9
self.addEventListener('fetch', (event) => {
10
  const url = new URL(event.request.url);
11

12
  // 关键：只处理 GET，且同源
13
  if (event.request.method !== 'GET' || url.origin !== self.location.origin) {
14
    return;
15
  }
16

17
  for (const route of ROUTES) {
18
    if (route.pattern.test(url.pathname)) {
19
      event.respondWith(STRATEGIES[route.strategy](event.request));
20
      return;
21
    }
22
  }
23

24
  // 未匹配的请求：放行浏览器默认行为
25
});

把策略做成配置表而不是散落在事件处理器里的 if-else，是任何”中型”项目都应遵循的工程纪律。

4.1 配额与驱逐#

1
// 申请持久化存储
2
if (navigator.storage && navigator.storage.persist) {
3
  const persisted = await navigator.storage.persist();
4
  console.log('持久化授权:', persisted);
5
}
6

7
const estimate = await navigator.storage.estimate();
8
console.log(`已用 ${estimate.usage} / ${estimate.quota}`);

Chrome 在磁盘空间不足时优先清理未持久化的存储。对”必须保留”的离线资源（如离线地图瓦片），应当申请 persist() 授权。

4.2 处理 Range 请求#

视频和大型资源往往带 Range: bytes=0-1023 头。Cache Storage 默认会完整缓存整个响应，后续 Range 请求可能无法命中。

1
// 拆分缓存：把 Range 响应合并成完整资源
2
async function handleRange(request) {
3
  const cache = await caches.open('videos');
4
  const cached = await cache.match(request.url); // 注意：去掉 Range 头
5

6
  if (cached) {
7
    const blob = await cached.blob();
8
    return new Response(blob.slice(0, 1024), {
9
      status: 206,
10
      headers: { 'Content-Range': `bytes 0-1023/${blob.size}` },
11
    });
12
  }
13
  return fetch(request);
14
}

对真正的”专业级”流媒体方案，建议用 Range requests polyfill 或迁移到 MediaSource API。

4.3 清理的边界条件#

1
// ❌ 错误：把整个网站资源都放进一张缓存
2
const CACHE = 'everything-v1';
3
// 1MB 的小图片也会和 100MB 视频放一起，maxEntries 不起作用
4

5
// ✅ 正确：按类型分桶
6
const CACHES = {
7
  static: 'static-v1',     // max 100 entries
8
  images: 'images-v1',     // max 200 entries
9
  api:    'api-v1',        // max 50 entries, 7 天 TTL
10
};

分桶的好处不只是”看起来清晰”，更是让 LRU 清理互不干扰——一个 100MB 的视频清理不会拖累 5MB 的字体缓存。

5.1 VAPID 协议#

Web Push 使用 VAPID（Voluntary Application Server Identification） 让服务器能识别推送来源。你需要生成一对公私钥：

1
# 安装 web-push CLI
2
npm i -g web-push
3
web-push generate-vapid-keys
4
# 输出的 pub/sub key 用于前后端

5.2 前端订阅#

1
// 申请推送权限
2
const permission = await Notification.requestPermission();
3
if (permission !== 'granted') return;
4

5
// 订阅
6
const registration = await navigator.serviceWorker.ready;
7
const subscription = await registration.pushManager.subscribe({
8
  userVisibleOnly: true, // 必须：所有推送必须显示通知
9
  applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
10
});
11

12
// 发送到服务器
13
await fetch('/api/push/subscribe', {
14
  method: 'POST',
15
  body: JSON.stringify(subscription),
16
  headers: { 'Content-Type': 'application/json' },
17
});

userVisibleOnly: true 是强制要求——静默推送被认为是对用户的骚扰。

5.3 接收消息#

1
self.addEventListener('push', (event) => {
2
  const data = event.data ? event.data.json() : { title: '新消息' };
3

4
  event.waitUntil(
5
    self.registration.showNotification(data.title, {
6
      body: data.body,
7
      icon: '/icon-192.png',
8
      badge: '/badge.png',
9
      data: { url: data.url }, // 透传到 notificationclick
10
      actions: [
11
        { action: 'open', title: '查看' },
12
        { action: 'dismiss', title: '忽略' },
13
      ],
14
    })
15
  );
16
});
17

18
self.addEventListener('notificationclick', (event) => {
19
  event.notification.close();
20
  if (event.action === 'open' || !event.action) {
21
    event.waitUntil(clients.openWindow(event.notification.data.url));
22
  }
23
});

5.4 常见推送坑#

6.1 注册同步任务#

1
// 主线程：提交时如果失败，注册一个 sync
2
async function submitForm(data) {
3
  try {
4
    await fetch('/api/orders', { method: 'POST', body: JSON.stringify(data) });
5
  } catch (e) {
6
    const reg = await navigator.serviceWorker.ready;
7
    await reg.sync.register('submit-order');
8
    // 提示用户：网络恢复后会重试
9
  }
10
}

6.2 SW 中重试#

1
self.addEventListener('sync', (event) => {
2
  if (event.tag === 'submit-order') {
3
    event.waitUntil(retrySubmission());
4
  }
5
});
6

7
async function retrySubmission() {
8
  const queue = await getQueuedSubmissions();
9
  for (const item of queue) {
10
    const res = await fetch('/api/orders', { method: 'POST', body: item.body });
11
    if (res.ok) await dequeue(item.id);
12
  }
13
}

6.3 Periodic Sync：受控的定时拉取#

1
// 每 24 小时唤醒一次（需用户授权）
2
const reg = await navigator.serviceWorker.ready;
3
await reg.periodicSync.register('sync-feed', { minInterval: 24 * 60 * 60 * 1000 });

注意：Periodic Sync 仍然受 Chrome 政策限制，只对已安装的 PWA 开放。这正是”PWA 应该引导用户添加到主屏幕”的原因。

7.1 Chrome DevTools 必看面板#

7.2 强制跳过等待#

1
// 临时在 DevTools 的 SW 面板点 "skipWaiting"
2
// 或在代码里：
3
self.addEventListener('install', () => self.skipWaiting());

7.3 主动更新#

1
// 页面侧
2
navigator.serviceWorker.getRegistration().then((reg) => reg.update());

7.4 七条调试军规#

1. 永远不要在 SW 里用 console.log 后指望线上看到——线上 SW 抛错你根本收不到。改为 try/catch + 上报到你的日志服务。
2. 更新 SW 后一定要清理 Service Workers 面板的 “Update on reload”——开发时打开它，生产必须关闭，否则用户每次刷新都是新 SW。
3. /sw.js 必须用 Cache-Control: no-cache——否则代理服务器会缓存旧版本，导致用户卡在老 SW。
4. 路径必须与 scope 匹配：scope: '/app/' 时 SW 文件必须在 /app/sw.js，否则注册失败。
5. 不能注册跨域 SW——scope 必须与 SW URL 同源。
6. fetch 事件中不要 return undefined——会抛 TypeError: Failed to convert value to Response。
7. <iframe> 默认不受 SW 控制——除非显式设置 navigator.serviceWorker.register 的 scope。

9.1 资源分类#

9.2 关键代码#

1
const VERSION = 'v3.1.0';
2
const CACHES = {
3
  html: `html-${VERSION}`,
4
  assets: `assets-${VERSION}`,
5
  images: `images-${VERSION}`,
6
  api: `api-${VERSION}`,
7
};
8

9
self.addEventListener('install', (event) => {
10
  event.waitUntil(
11
    caches.open(CACHES.html).then((cache) =>
12
      cache.addAll(['/offline.html', '/skeleton.html'])
13
    )
14
  );
15
  self.skipWaiting();
16
});
17

18
self.addEventListener('activate', (event) => {
19
  event.waitUntil((async () => {
20
    const keys = await caches.keys();
21
    await Promise.all(
22
      keys
23
        .filter((k) => !Object.values(CACHES).includes(k))
24
        .map((k) => caches.delete(k))
25
    );
26
    await self.clients.claim();
27
  })());
28
});
29

30
self.addEventListener('fetch', (event) => {
31
  const { request } = event;
32
  if (request.method !== 'GET') return;
33

34
  const url = new URL(request.url);
35
  if (url.origin !== self.location.origin) return;
36

37
  // HTML
38
  if (request.mode === 'navigate') {
39
    event.respondWith(networkFirstWithOffline(request, CACHES.html));
40
    return;
41
  }
42

43
  // 静态资源
44
  if (/\.(js|css|woff2?)$/.test(url.pathname)) {
45
    event.respondWith(cacheFirst(request, CACHES.assets));
46
    return;
47
  }
48

49
  // 图片
50
  if (/\.(png|jpg|webp|avif)$/.test(url.pathname)) {
51
    event.respondWith(cacheFirst(request, CACHES.images));
52
    return;
53
  }
54

55
  // API
56
  if (url.pathname.startsWith('/api/')) {
57
    if (url.pathname.startsWith('/api/stock/')) return; // 不处理
58
    event.respondWith(staleWhileRevalidate(request, CACHES.api, 60 * 60));
59
    return;
60
  }
61
});
62

63
async function networkFirstWithOffline(request, cacheName) {
64
  const cache = await caches.open(cacheName);
65
  try {
66
    const response = await Promise.race([
67
      fetch(request),
68
      new Promise((_, reject) =>
69
        setTimeout(() => reject(new Error('timeout')), 3000)
70
      ),
71
    ]);
72
    if (response.ok) cache.put(request, response.clone());
73
    return response;
74
  } catch (e) {
75
    const cached = await cache.match(request);
76
    return cached || (await cache.match('/offline.html'));
77
  }
78
}

9.3 效果数据#

接入该方案后，模拟弱网（Slow 3G）下：

• 二次访问 LCP 从 4.2s → 0.9s
• 离线/弱网提交订单成功率从 38% → 94%
• 推送消息打开率提升 17%

数据来自线上真实业务（脱敏后），具体指标因业务而异。

缓存相关#

1. 不要缓存 Set-Cookie 响应，否则破坏会话。
2. 不要缓存 Vary: * 响应，Cache Storage 不会按请求头区分。
3. Cache-Control: no-store 的资源仍然可以被 caches.put——SW 不遵守 HTTP 缓存头。
4. 大于 5MB 的单条资源建议用 IndexedDB 而不是 Cache Storage。
5. 写缓存时务必 response.clone()，否则主流程会读到空 body。

更新相关#

6. SW 文件首行加版本注释也能触发更新（因字节变了），但用构建工具注入哈希更规范。
7. importScripts 引用的资源不会触发 SW 更新。
8. iOS 上 navigator.serviceWorker 只在主屏启动时才存在。
9. PWA 升级到新版本后，首次刷新仍由旧 SW 响应——这是浏览器设计。

调试相关#

10. DevTools 的 “Bypass for network” 不会绕过 SW。
11. 隐身模式下注册 SW 会在窗口关闭后清理。
12. SW 中 XMLHttpRequest 已废弃，请用 fetch。
13. SW 脚本不能用动态 import() 引入外部 URL（仅允许同源）。
14. event.respondWith 必须在 fetch 事件同步调用。

推送相关#

15. iOS 必须 PWA 模式（添加到主屏）才能收到推送。
16. 服务器推送时必须加密负载（aesgcm），否则浏览器拒收。
17. 推送消息 TTL 默认为 4 周，过期即丢。
18. pushsubscriptionchange 事件必须处理，否则用户换设备后订阅失效。
19. 同一 Service Worker 不能同时绑定 VAPID 旧/新两套 key——需重新订阅。

性能相关#

20. 预缓存超过 50 个文件会让首屏 install 阻塞 1-2 秒，建议分阶段。
21. caches.keys() 是 O(n) 调用，每多 1 个桶就多 1 次磁盘 IO。
22. SW 中使用 Map/Set 等大对象会泄漏到主线程——SW 被回收时这些内存才会释放。
23. 写完缓存后不要调用 response.blob()——它会消耗 body 的可读流。

安全相关#

24. SW scope 默认只控制同源子路径。
25. SW 内的 fetch 默认带 Cookie，但不带 HTTP 认证头。
26. 收到推送时先校验 server key，否则任何持有 endpoint 的人都能伪造推送。
27. 不要在 SW 中处理用户隐私数据——它对浏览器扩展可见。

协议相关#

28. caches.match 默认带 ignoreSearch: false，即 ?a=1 和 ?a=2 视为不同。
29. clients.openWindow 只能打开同 origin URL。
30. Background Sync 在 Safari 16.4+ 仍不支持，需做能力检测。

延伸阅读#

• MDN: Service Worker API
• Google: Service Worker 生命周期
• Web Push 协议 RFC 8030
• VAPID 规范 RFC 8292
• Workbox 官方文档
• Background Sync 提案
• 本博客《Service Worker 离线优先策略》 — 入门篇
• 本博客《浏览器缓存策略深度解析》 — HTTP 缓存层
• 本博客《Web Worker 多线程》 — 与 SW 互补的计算线程

Happy hacking —— 写一个能离线跑得起来的 Web，比想象中更难，也更有价值。