版本更新时应按需清理旧数据并平滑过渡：校验localStorage字段兼容性后迁移备份；Service Worker需skipWaiting并主动update；Pinia/Vuex持久化要设version并配置migration；HTML启用文件哈希与版本号比对触发缓存清除。
版本更新时旧数据残留是前端常见问题，尤其当 localStorage、sessionStorage 或 Service Worker 缓存了过期结构的数据，轻则页面白屏、功能异常，重则触发 JS 报错中断渲染。核心思路不是“清空一切”，而是“按需清理+平滑过渡”。
识别并清除冲突的持久化数据
很多报错源于用户本地存了旧版字段（比如新版要求 user.profile.avatarUrl，但旧数据只有 user.avatar）。可主动检测并迁移：
- 在应用启动时读取 localStorage 中的关键数据，用 try-catch + schema 校验判断是否兼容；
- 若校验失败，先备份旧数据（如存为 user_v1_backup），再清空对应 key；
- 避免直接 localStorage.clear() —— 它会误删登录态、偏好设置等其他业务数据。
Service Worker 更新必须解绑旧实例
Service Worker 的缓存机制极强，即使 HTML 已更新，旧 SW 仍可能拦截请求并返回过期资源。部署新版本后务必强制更新：
- 在新 SW 脚本中调用 self.skipWaiting()，让新脚本立即激活；
- 主应用加载时检查 navigator.serviceWorker.controller 是否为 null 或旧版本，若存在旧控制权，执行 navigator.serviceWorker.getRegistration().then(r => r?.update())；
- 开发阶段可在 Chrome DevTools → Application → Service Workers 中勾选 Bypass for network 或点击 Unregister 手动清理。
Pinia / Vuex 持久化状态需版本感知
使用 pinia-plugin-persistedstate 等插件时，若 store 结构变更（如删除字段、嵌套层级调整），旧缓存会解析失败。解决方案：
- 在 persist 配置中启用 version 字段，例如：version: 2；
- 插件会自动对比存储中的 version 值，不匹配时跳过还原，避免解析报错；
- 配合 migration 函数，在 version 升级时做字段映射（如把 theme 拆成 theme.mode 和 theme.color）。
静态资源缓存与 HTML 版本联动
HTML 文件本身被强缓存（如 Cache-Control: max-age=31536000），会导致用户长期卡在旧壳子中，加载不到新版 JS/CSS。关键措施：
- 构建时启用文件名哈希（filenameHashing: true），确保 JS/CSS 文件路径随内容变化；
- HTML 中通过内联 script 注入当前构建版本号（如 window.__APP_VERSION__ = "v2.3.1-abc123"）；
- 启动时比对 localStorage 中记录的版本，不一致则清空相关缓存并刷新，而非静默加载旧逻辑。
