如何配置Vite PWA实现页面加载自动更新+定期检查弹窗提示

核心思路 #

通过拆分页面初始化阶段和应用运行阶段的更新逻辑，达成两个目标：

• 页面首次/重新加载时，自动获取并激活最新版本（无需用户交互）
• 应用运行期间，定期检查更新但仅通过按钮提示用户手动触发更新

具体实现步骤 #

1. 调整VitePWA配置 #

保持registerType: 'prompt'，同时配置workbox确保Service Worker本身能及时获取最新版本：

// vite.config.ts
export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'prompt',
      workbox: {
        skipWaiting: false,
        clientsClaim: false,
        // 配置资源缓存策略，兼顾加载速度和新鲜度
        runtimeCaching: [
          {
            urlPattern: ({ url }) => url.origin === self.location.origin,
            handler: 'StaleWhileRevalidate',
            options: {
              cacheName: 'app-resources',
              cacheableResponse: { statuses: [200] },
            },
          },
        ],
      },
    }),
  ],
});

2. 修改useRegisterSW逻辑 #

在页面初始化时立即检查并激活新版本，运行阶段保持定期检查但仅触发用户提示：

const {
  needRefresh: [needRefresh],
  updateServiceWorker,
} = useRegisterSW({
  immediate: true,
  onRegisteredSW: async (swUrl, r) => {
    if (!r) return;

    // 页面加载阶段：自动检查并激活最新版本
    const checkInitialUpdate = async () => {
      if ('connection' in navigator && !navigator.onLine) return;

      const resp = await fetch(swUrl, {
        cache: 'no-store',
        headers: { 'cache-control': 'no-cache' },
      });

      if (resp?.status === 200) {
        const newWorker = await r.update();
        if (newWorker) {
          // 监听新SW激活状态，激活后刷新页面
          newWorker.addEventListener('statechange', () => {
            if (newWorker.state === 'activated') {
              window.location.reload();
            }
          });
          // 发送消息触发skipWaiting，让新SW立即接管
          newWorker.postMessage({ type: 'SKIP_WAITING' });
        }
      }
    };

    // 先执行初始化检查
    await checkInitialUpdate();

    // 运行阶段：定期检查更新，仅提示用户手动操作
    setInterval(async () => {
      if (r.installing || !navigator.onLine) return;

      const resp = await fetch(swUrl, {
        cache: 'no-store',
        headers: { 'cache-control': 'no-cache' },
      });

      if (resp?.status === 200) {
        await r.update();
        // 依赖needRefresh状态触发前端提示，不自动更新
      }
    }, 60 * 1000);
  },
});

3. 配置Service Worker的skipWaiting监听 #

如果使用自定义Service Worker文件，需要添加消息监听来处理激活指令：

// src/sw.ts
self.addEventListener('message', (event) => {
  if (event.data?.type === 'SKIP_WAITING') {
    self.skipWaiting();
  }
});

若使用VitePWA默认生成的SW，无需额外配置，默认已支持该消息处理。

关键细节说明 #

• 页面初始化自动更新：用户打开页面时无正在进行的操作，此时自动更新并刷新不会影响体验，确保用户每次打开都用最新版本
• 运行时手动提示：定期检查到更新后，仅通过needRefresh状态触发前端提示，让用户选择合适时机更新，避免打断操作或丢失数据
• 缓存策略：StaleWhileRevalidate策略保证用户快速加载缓存资源的同时，后台静默获取最新版本，平衡性能与新鲜度

内容的提问来源于stack exchange，提问作者mtnair