Pinia状态持久化需显式声明version并启用比对机制，当localStorage中缓存version与当前配置不一致时自动跳过还原，避免解析错误；state形状不兼容变更（如删字段、改嵌套、变类型）必须升级version。

Pinia 状态持久化遇到数据格式变更时，核心不是清空旧缓存，而是让新版本代码能安全识别并跳过不兼容的缓存，避免解析失败导致白屏或报错。

必须显式声明 version 并启用比对机制

使用 pinia-plugin-persistedstate 时，需在 persist 配置中明确写入 version 字段：

• persist: { enabled: true, version: 2 }
• 插件会自动读取 localStorage 中对应 key 下的 __version__ 字段
• 若本地缓存 version 与当前配置不一致，直接跳过还原逻辑，state 使用初始值
• 不会尝试解析旧结构，彻底规避 JSON 解析错误或响应式代理异常

哪些变更需要升级 version？

只要 state 的形状（shape）发生不兼容改动，就必须提升 version 数字：

Vuejs

Vue.js 官方推荐通过 npm 进行安装，这是构建现代化前端项目最主流的方式。在终端中执行 npm install vue 即可获取最新稳定版，如需指定版本可添加 @版本号，例如 npm install vue@3.4.0。安装前请确保已配置 Node.js 环境（推荐 v18 及以上版本），并建议将 npm 镜像源切换至国内镜像以提升下载速度。对于大型项目，还可通过 npm create v

下载

• 删除字段（如移除 user.avatarUrl）
• 调整嵌套层级（如把 profile.name 拆为 profile.firstName 和 profile.lastName）
• 改变字段类型（如 count 从 number 改为 string）
• 注意：仅新增可选字段、修改默认值，通常无需升 version

可选但推荐：手动迁移旧数据

若希望用户保留部分有效信息，可在 version 不匹配时主动转换：

• 利用 onRehydrateStorage 钩子监听还原前一刻
• 检查缓存中的 version，例如发现是 1 而当前是 2，就做字段映射
• 示例：将 { name: 'Alice' } 转为 { firstName: 'Alice', lastName: '' }
• 转换完成后调用 store.$patch() 或 store.$state = 新对象，确保后续运行正常

上线前务必模拟旧缓存验证

不能只测新用户，要真实还原升级场景：

• 手动在 localStorage 写入一个 version: 1 的旧缓存字符串
• 启动新版应用，确认页面不报错、不卡死，state 正确回退到初始值
• 如有迁移逻辑，验证转换后数据是否符合预期
• 建议在测试环境灰度发布，观察实际用户行为日志