fix(pwa): 新版本部署后自动刷新页面，预览站点不使用 Service Worker 缓存

.github/workflows/preview-build.yml

@@ -34,6 +34,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
       - name: Build with VitePress
+        env:
+          # 预览站点不使用 Service Worker 缓存，保证每次访问都拿到最新内容
+          PWA_SELF_DESTROYING: "true"
         run: pnpm run build
       - name: Save PR metadata
         env:

course/.vitepress/config.mts

@@ -31,6 +31,8 @@ export default withPwa(
     },
     pwa: {
       registerType: "autoUpdate",
+      // PR 预览构建时生成会自我注销的 Service Worker，避免评审时看到缓存的旧预览
+      selfDestroying: process.env.PWA_SELF_DESTROYING === "true",
       manifest: {
         name: title,
         short_name: "Zig 圣经",

course/.vitepress/theme/index.ts

@@ -1,4 +1,5 @@
 // .vitepress/theme/index.ts
+/// <reference types="vite-plugin-pwa/client" />
 import type { Theme } from "vitepress";
 import DefaultTheme from "vitepress/theme";
 
@@ -28,6 +29,13 @@ export default {
           details.removeAttribute("open");
         });
       });
+
+      // 注册 Service Worker。插件默认注入的 registerSW.js 只负责注册，新版本激活后页面不会刷新，
+      // 读者会继续看到预缓存的旧内容；改用 virtual:pwa-register 后，autoUpdate 模式会在新版本激活时自动刷新页面。
+      // 引入该模块后，插件也不再注入 registerSW.js。
+      import("virtual:pwa-register").then(({ registerSW }) => {
+        registerSW({ immediate: true });
+      });
     }
   },
   Layout() {

package.json

@@ -30,7 +30,8 @@
     "subset-font": "^2.9.0",
     "typescript": "^7.0.2",
     "vite-plugin-pwa": "^1.3.0",
-    "vitepress": "^1.6.4"
+    "vitepress": "^1.6.4",
+    "workbox-window": "^7.4.1"
   },
   "dependencies": {
     "@giscus/vue": "^3.1.1"