Service Worker 离线优先策略：构建真正可靠的 PWA

1
if ('serviceWorker' in navigator) {
2
  window.addEventListener('load', async () => {
3
    try {
4
      const registration = await navigator.serviceWorker.register('/sw.js', {
5
        scope: '/', // 控制范围
6
      });
7

8
      console.log('SW 注册成功，scope:', registration.scope);
9

10
      // 监听更新
11
      registration.addEventListener('updatefound', () => {
12
        const newWorker = registration.installing;
13
        console.log('发现新版本 SW');
14

15
        newWorker.addEventListener('statechange', () => {
16
          if (newWorker.state === 'installed') {
17
            if (navigator.serviceWorker.controller) {
18
              // 有旧版本在运行，新版本已安装但等待激活
19
              console.log('新版本已就绪，刷新页面即可更新');
20
              showUpdateNotification();
21
            } else {
22
              // 首次安装
23
              console.log('内容已缓存，可离线使用');
24
            }
25
          }
26
        });
27
      });
28
    } catch (error) {
29
      console.error('SW 注册失败:', error);
30
    }
31
  });
32
}

1
import { VitePWA } from 'vite-plugin-pwa';
2

3
export default {
4
  plugins: [
5
    VitePWA({
6
      strategies: 'injectManifest',
7
      srcDir: 'src',
8
      filename: 'sw.js',
9
      registerType: 'prompt', // 'autoUpdate' 或 'prompt'
10
      injectManifest: {
11
        globPatterns: ['**/*.{js,css,html,svg,png,woff2}'],
12
      },
13
      manifest: {
14
        name: 'My PWA App',
15
        short_name: 'MyApp',
16
        theme_color: '#4f46e5',
17
        icons: [
18
          {
19
            src: 'icon-192.png',
20
            sizes: '192x192',
21
            type: 'image/png',
22
          },
23
          {
24
            src: 'icon-512.png',
25
            sizes: '512x512',
26
            type: 'image/png',
27
          },
28
        ],
29
      },
30
    }),
31
  ],
32
};

1
// 请求队列（使用 IndexedDB）
2
class RequestQueue {
3
  constructor(dbName = 'sync-queue') {
4
    this.dbName = dbName;
5
    this.storeName = 'requests';
6
  }
7

8
  async _getDB() {
9
    return new Promise((resolve, reject) => {
10
      const request = indexedDB.open(this.dbName, 1);
11
      request.onupgradeneeded = (event) => {
12
        const db = event.target.result;
13
        if (!db.objectStoreNames.contains(this.storeName)) {
14
          db.createObjectStore(this.storeName, {
15
            keyPath: 'id',
16
            autoIncrement: true,
17
          });
18
        }
19
      };
20
      request.onsuccess = () => resolve(request.result);
21
      request.onerror = () => reject(request.error);
22
    });
23
  }
24

25
  async enqueue(requestData) {
26
    const db = await this._getDB();
27
    return new Promise((resolve, reject) => {
28
      const tx = db.transaction(this.storeName, 'readwrite');
29
      const store = tx.objectStore(this.storeName);
30
      store.add({
31
        url: requestData.url,
32
        method: requestData.method,
33
        headers: Object.fromEntries(requestData.headers),
34
        body: requestData.body,
35
        timestamp: Date.now(),
36
      });
37
      tx.oncomplete = () => resolve();
38
      tx.onerror = () => reject(tx.error);
39
    });
40
  }
41

42
  async dequeueAll() {
43
    const db = await this._getDB();
44
    return new Promise((resolve, reject) => {
45
      const tx = db.transaction(this.storeName, 'readwrite');
46
      const store = tx.objectStore(this.storeName);
47
      const request = store.getAll();
48
      request.onsuccess = () => {
49
        const items = request.result;
50
        // 清空队列
51
        store.clear();
52
        resolve(items);
53
      };
54
      request.onerror = () => reject(request.error);
55
    });
56
  }
57
}
58

59
const queue = new RequestQueue();
60

61
// 拦截 POST 请求
62
self.addEventListener('fetch', (event) => {
63
  if (event.request.method === 'POST' && event.request.url.includes('/api/')) {
64
    event.respondWith(handlePostRequest(event.request));
65
  }
66
});
67

68
async function handlePostRequest(request) {
69
  try {
70
    const response = await fetch(request.clone());
71
    return response;
72
  } catch (error) {
73
    // 网络失败，存入队列
74
    const body = await request.text();
75
    await queue.enqueue({
76
      url: request.url,
77
      method: request.method,
78
      headers: request.headers,
79
      body,
80
    });
81

82
    // 注册后台同步
83
    await self.registration.sync.register('sync-posts');
84

85
    // 返回一个"已暂存"的响应
86
    return new Response(
87
      JSON.stringify({
88
        status: 'queued',
89
        message: '请求已暂存，网络恢复后将自动提交',
90
      }),
91
      {
92
        status: 202,
93
        headers: { 'Content-Type': 'application/json' },
94
      }
95
    );
96
  }
97
}
98

99
// 后台同步事件
100
self.addEventListener('sync', (event) => {
101
  if (event.tag === 'sync-posts') {
102
    event.waitUntil(replayQueue());
103
  }
104
});
105

106
async function replayQueue() {
107
  const requests = await queue.dequeueAll();
108

109
  for (const req of requests) {
110
    try {
111
      await fetch(req.url, {
112
        method: req.method,
113
        headers: req.headers,
114
        body: req.body,
115
      });
116
      console.log('[SW] 同步成功:', req.url);
117
    } catch (error) {
118
      // 仍然失败，重新入队
119
      await queue.enqueue(req);
120
      // 重新注册 sync
121
      await self.registration.sync.register('sync-posts');
122
      throw error; // 让浏览器知道同步失败，稍后重试
123
    }
124
  }
125

126
  // 通知页面同步完成
127
  const clients = await self.clients.matchAll();
128
  clients.forEach((client) => {
129
    client.postMessage({ type: 'SYNC_COMPLETE', count: requests.length });
130
  });
131
}

1
import { BackgroundSyncPlugin } from 'workbox-background-sync';
2
import { registerRoute } from 'workbox-routing';
3
import { NetworkOnly } from 'workbox-strategies';
4

5
const bgSyncPlugin = new BackgroundSyncPlugin('api-queue', {
6
  maxRetentionTime: 24 * 60, // 最多保留 24 小时（分钟）
7
  onSync: async ({ queue }) => {
8
    let entry;
9
    while ((entry = await queue.shiftRequest())) {
10
      try {
11
        await fetch(entry.request);
12
        console.log('[BgSync] 重发成功:', entry.request.url);
13
      } catch (error) {
14
        console.error('[BgSync] 重发失败:', error);
15
        await queue.unshiftRequest(entry);
16
        throw error;
17
      }
18
    }
19
    // 通知页面
20
    const clients = await self.clients.matchAll();
21
    clients.forEach((client) => {
22
      client.postMessage({ type: 'SYNC_COMPLETE' });
23
    });
24
  },
25
});
26

27
// 所有 POST 请求到 /api/ 的路由使用 Background Sync
28
registerRoute(
29
  ({ url, request }) =>
30
    url.pathname.startsWith('/api/') && request.method === 'POST',
31
  new NetworkOnly({
32
    plugins: [bgSyncPlugin],
33
  }),
34
  'POST'
35
);

1
let refreshing = false;
2

3
navigator.serviceWorker.addEventListener('controllerchange', () => {
4
  if (!refreshing) {
5
    refreshing = true;
6
    window.location.reload();
7
  }
8
});
9

10
async function registerSW() {
11
  const registration = await navigator.serviceWorker.register('/sw.js');
12

13
  registration.addEventListener('updatefound', () => {
14
    const newWorker = registration.installing;
15

16
    newWorker.addEventListener('statechange', () => {
17
      if (
18
        newWorker.state === 'installed' &&
19
        navigator.serviceWorker.controller
20
      ) {
21
        // 显示更新提示
22
        showUpdateBanner(newWorker);
23
      }
24
    });
25
  });
26
}
27

28
function showUpdateBanner(worker) {
29
  const banner = document.createElement('div');
30
  banner.className = 'update-banner';
31
  banner.innerHTML = `
32
    <p>新版本已就绪</p>
33
    <button id="update-btn">立即更新</button>
34
    <button id="dismiss-btn">稍后</button>
35
  `;
36
  document.body.appendChild(banner);
37

38
  document.getElementById('update-btn').addEventListener('click', () => {
39
    // 通知新 SW 跳过等待
40
    worker.postMessage({ type: 'SKIP_WAITING' });
41
    banner.remove();
42
  });
43

44
  document.getElementById('dismiss-btn').addEventListener('click', () => {
45
    banner.remove();
46
  });
47
}