[jinzhongjia]

问题

部署新版本后（包括 PR 预览），浏览器有时仍显示旧内容，过一会儿或再刷新一次才更新。

排查结果：

• 不是 Cloudflare 或 HTTP 缓存：HTML 与 sw.js 响应头均为 cache-control: public, max-age=0, must-revalidate，cf-cache-status: MISS
• 是 PWA 的 Service Worker：Workbox 预缓存了全部 82 个页面，通过 precacheAndRoute 优先从缓存读取。访问时先返回缓存中的旧页面，同时在后台安装新版本 Service Worker。插件注入的 registerSW.js 只调用 navigator.serviceWorker.register('/sw.js')，新版本激活后页面不会刷新

改动

• theme/index.ts：改用 virtual:pwa-register 注册 Service Worker。autoUpdate 模式下，新版本激活后会自动刷新页面；引入该模块后插件不再注入 registerSW.js
• package.json：新增 workbox-window 开发依赖（virtual:pwa-register 需要，版本与锁文件中已有的 7.4.1 一致）
• config.mts：selfDestroying 由环境变量 PWA_SELF_DESTROYING 控制
• preview-build.yml：预览构建设置 PWA_SELF_DESTROYING=true，预览站点生成自我注销的 Service Worker（注销自身、清空缓存并刷新页面），评审时始终拿到最新内容；生产构建不受影响

注意：injectRegister 保持默认的 auto。如果设为 false，vite-plugin-pwa 不会再自动开启 skipWaiting / clientsClaim，新版本 Service Worker 会一直处于 waiting 状态。

验证

本地用 headless Chrome 模拟“访客已有旧版本缓存 → 部署新版本 → 再次访问”：

构建	结果
main	新 Service Worker 已激活，但页面一直停留在旧内容
本 PR（生产）	先显示缓存的旧内容，约 3 秒后自动刷新为新内容
本 PR（预览，PWA_SELF_DESTROYING=true）	约 3 秒后自动刷新为新内容，之后 Service Worker 已注销

pnpm check、pnpm build（两种模式）均通过。

Summary by CodeRabbit

• New Features
  • The site now automatically registers its progressive web app service worker in the browser.
• Improvements
  • Preview builds configure the service worker to remove itself, helping prevent preview content from persisting as a cached app.

These changes improve how the site and preview builds behave when loaded in a browser.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 67d34387-fbc0-46b0-acbc-e0df015f88ff

📥 Commits

Reviewing files that changed from the base of the PR and between 321b506 and f87914e.

⛔ Files ignored due to path filters: 1

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing: 4

• .github/workflows/preview-build.yml
• course/.vitepress/config.mts
• course/.vitepress/theme/index.ts
• package.json

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

📝 Walkthrough

The VitePress theme now registers the service worker immediately in the browser. The PWA configuration reads PWA_SELF_DESTROYING to set the self-destroying option, and the preview build sets that variable to true. The package adds workbox-window as a development dependency.

Changes: PWA registration and preview behavior

Layer / File(s)	Summary
Browser service worker registration package.json, course/.vitepress/theme/index.ts	The theme dynamically imports virtual:pwa-register and calls registerSW with immediate: true. The package adds workbox-window to devDependencies.
Preview self-destroying option course/.vitepress/config.mts, .github/workflows/preview-build.yml	The PWA configuration sets selfDestroying to true only when PWA_SELF_DESTROYING equals "true". The preview build step sets that environment variable to "true".

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant BrowserTheme
  participant PWAClient as virtual:pwa-register
  participant ServiceWorker
  BrowserTheme->>PWAClient: dynamically import and call registerSW with immediate true
  PWAClient->>ServiceWorker: register service worker

Loading

Merge Risk: ⚪ Minimal · up to f8791

The change makes pages refresh after a new deployment and keeps preview sites from caching through a service worker. No concrete merge-blocking risk remains.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title accurately summarizes the main changes: automatic page refresh after deployment and disabling Service Worker caching for preview sites.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches: 💡 1

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

文档预览已部署

项目	链接
预览地址（随 PR 更新）	https://pr-402-zig-course.jinzhongjia.workers.dev
本次部署（固定版本）	https://735b3ffb-zig-course.jinzhongjia.workers.dev
对应提交	f87914e

由 Preview Deploy 自动生成，PR 每次更新后会刷新这条评论。