如何配置vite-plugin-pwa实现iOS中WKWebView的自动更新

使用Vite + React开发PWA，通过vite-plugin-pwa生成manifest和Service Worker，已设置registerType: "autoUpdate"，期望新版本部署后自动更新。该功能在桌面浏览器正常，但在iPhone的WKWebView中无法自动更新，必须手动卸载重装才能获取新版本。

当前Vite-PWA配置如下：

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { VitePWA, VitePWAOptions } from "vite-plugin-pwa";

const manifestForPlugin: Partial<VitePWAOptions> = {
  registerType: "autoUpdate",
  manifest: {
    name: "App",
    short_name: "App",
    description: "An App, V1.0.0",
    theme_color: "#dc2625",
    background_color: "#dc2625",
    start_url: "/",
    display: "standalone",
    orientation: "portrait",
    icons: [
      {
        src: "./vite.svg", // path to your app's logo
        sizes: "192x192",
        type: "image/png",
        purpose: "any maskable",
      },
    ],
  },
};

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), VitePWA(manifestForPlugin)],
});

1. 优化Service Worker缓存策略 #

WKWebView对Service Worker的缓存处理存在特殊限制，需显式配置缓存更新规则，确保新版本SW能被检测到。在VitePWA配置中添加workbox选项：

const manifestForPlugin: Partial<VitePWAOptions> = {
  // 保留原有配置
  registerType: "autoUpdate",
  manifest: { /* 原有manifest配置 */ },
  workbox: {
    globPatterns: ['**/*.{js,css,html,ico,png,svg}'],
    runtimeCaching: [
      {
        urlPattern: /^https?.*/,
        handler: 'NetworkFirst',
        options: {
          cacheName: 'runtime-cache',
          expiration: {
            maxEntries: 50,
            maxAgeSeconds: 7 * 24 * 60 * 60, // 缓存7天
          },
          cacheableResponse: {
            statuses: [0, 200],
          },
        },
      },
    ],
    skipWaiting: true,
    clientsClaim: true,
  },
};

• skipWaiting: true：让新Service Worker立即激活，无需等待所有客户端页面关闭
• clientsClaim: true：新SW激活后立即接管所有打开的客户端页面

2. 添加主动更新检测逻辑 #

在React入口文件（如App.tsx）中手动添加SW更新检测，确保WKWebView能触发更新：

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    if ('serviceWorker' in navigator) {
      navigator.serviceWorker.register('/sw.js')
        .then(registration => {
          // 监听更新可用事件
          registration.addEventListener('updatefound', () => {
            const newWorker = registration.installing;
            if (newWorker) {
              newWorker.addEventListener('statechange', () => {
                if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
                  // 自动刷新页面应用新版本，也可替换为用户提示
                  window.location.reload();
                }
              });
            }
          });

          // 每小时主动检查一次更新
          const updateInterval = setInterval(() => {
            registration.update();
          }, 3600000);

          return () => clearInterval(updateInterval);
        })
        .catch(err => console.error('Service Worker注册失败:', err));
    }
  }, []);

  // 组件渲染内容
  return <div>Your App Content</div>;
}

export default App;

3. 调整iOS原生WKWebView缓存策略 #

若PWA嵌入在iOS原生App的WKWebView中，需在原生代码中配置缓存规则，避免SW和资源被缓存：

let configuration = WKWebViewConfiguration()
// 禁用持久化缓存
configuration.websiteDataStore = WKWebsiteDataStore.nonPersistent()

// 或者设置请求缓存策略为重新验证
let appURL = URL(string: "your-app-url")!
let request = URLRequest(url: appURL, cachePolicy: .reloadRevalidatingCacheData)

let webView = WKWebView(frame: view.bounds, configuration: configuration)
webView.load(request)
view.addSubview(webView)

同时确保服务器返回sw.js和manifest.json时，设置HTTP响应头：Cache-Control: no-cache, no-store, must-revalidate，强制客户端每次请求都验证资源有效性。

4. 更新manifest版本号 #

每次部署新版本时，手动递增manifest中的version字段，辅助客户端识别版本变化：

manifest: {
  // 原有配置
  version: "1.0.1", // 每次更新递增版本号
},

5. 监听页面可见性触发更新 #

WKWebView在App后台时可能终止Service Worker，导致更新检测失效。添加页面可见性监听，在App回到前台时主动检查更新：

useEffect(() => {
  const checkForUpdateOnVisible = () => {
    if (document.visibilityState === 'visible' && 'serviceWorker' in navigator) {
      navigator.serviceWorker.getRegistration().then(registration => {
        registration?.update();
      });
    }
  };

  document.addEventListener('visibilitychange', checkForUpdateOnVisible);
  return () => document.removeEventListener('visibilitychange', checkForUpdateOnVisible);
}, []);

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