从 vite-plugin-pwa 迁移
适用于已使用 vite-plugin-pwa 的 Vite + Vue 3 或 Vite + React 19 应用。迁移前先确认 Vite 8、框架版本和部署路径符合兼容范围，并盘点线上已有的 worker URL、scope、manifest ID 和注册用户；已投产的 worker 切换需要单独的迁移与回滚方案。
配置对应关系
| 原有做法 | PWA Platform 做法 |
|---|---|
VitePWA({ manifest }) | pwa({ identity, install, policy, topology }) |
workbox.globPatterns | PwaPolicy.resources 中的 asset 规则 |
workbox.runtimeCaching | 只对明确的公共读取使用 v3 运行时缓存；私有接口不能直接照搬 |
navigateFallback | offlineFallback 与导航资源规则 |
registerType: "prompt" | updateWaiting + applyUpdate() |
registerType: "autoUpdate" | 无直接对应；平台要求用户确认接管 |
virtual:pwa-register | 框架绑定提供 register()，由应用主动调用 |
迁移步骤
- 记录现有线上注册和资源缓存行为，特别是已有运行时缓存、离线页和更新提示。
- 在 Vite 配置中移除
VitePWA()，删除virtual:pwa-register引用；两个插件不应同时生成 worker 和 manifest。 - 按身份与策略配置写平台配置。策略路径相对
mountPath，不是直接复制原插件的 glob。 - 接入Vite + Vue或Vite + React绑定，并显式调用
register()。 - 用安装与更新替代原来的自动接管或自建版本轮询提示。
- 用生产构建及预览验证，再在目标环境完成上线前检查和 worker 切换演练。
当前插件只在生产构建中提供 virtual:pwa-config 和平台 worker；按接入示例替换页面入口后，vite dev 无法加载该虚拟模块。本地验证请使用 vite build + vite preview，离线和更新行为还需在目标部署环境复核。旧项目若把带指纹的运行时配置文件放在产物根目录，需要先调整产物路径，让可预缓存的文件落入明确的路径前缀，再写相应的 asset 规则。
迁移时以本站的当前包状态与公共读取规则为准。已有 worker 的 URL、scope 和 manifest ID 涉及浏览器身份，必须在目标业务项目制定迁移与回滚方案，不能直接照搬新项目的配置示例。