核心是让新版本代码安全跳过不兼容缓存而非清空旧数据；需在 persist 配置中显式声明 version，插件自动比对 localstorage 中的 version 字段，不匹配则跳过还原、使用初始 state；每次不兼容变更（删字段、改嵌套、变类型）都必须升级 version；可选手动迁移：通过 onrehydratestorage 或 reducer 钩子做版本转换并 replacestate；上线前须模拟旧缓存验证。
状态持久化遇到数据格式变更，核心是避免旧缓存解析失败导致页面报错或白屏。关键不是“清掉旧数据”，而是让新版本代码能识别并安全跳过不兼容的缓存。
启用插件的 version 字段
使用 pinia-plugin-persistedstate 或 vuex-persistedstate 时，必须在 persist 配置中显式声明 version：
- Pinia 示例：
persist: { enabled: true, version: 2 } - Vuex 示例：
plugins: [createPersistedState({ key: 'my-app', version: 2 })] - 插件会自动读取 localStorage 中对应 key 下的
__version__字段，与当前配置比对 - 不匹配时，直接跳过还原逻辑，state 使用初始值，不会尝试解析旧结构
结构变更后要同步更新 version 值
每次 store 的 state 形状发生不兼容改动，都必须提升 version 数字：
- 删除字段（如移除
user.avatarUrl）→ version 从 1 升到 2 - 嵌套层级调整（如把
profile.name拆成profile.firstName和profile.lastName）→ version 升到 3 - 类型变更（如
count从 number 改为 string）→ 也需升 version - 注意：仅修改默认值、新增可选字段，通常无需升 version
手动迁移旧数据（可选但推荐）
如果希望用户保留部分有效数据，可在 version 不匹配时主动做一次转换：
- 监听 persist 插件的
onRehydrateStorage（Pinia）或reducer（Vuex）钩子 - 检查当前缓存的 version，若为 1 且当前是 2，则对旧数据做字段映射或清理
- 例如：把
{ name: 'Alice' }转为{ firstName: 'Alice', lastName: '' } - 转换完成后，再调用
store.replaceState()或返回新对象，确保后续正常运行
上线前验证旧缓存行为
不要只测“新用户”，务必模拟真实升级场景：
- 本地 localStorage 手动写入一个 version=1 的旧缓存字符串
- 启动新版应用，确认页面不报错、不卡死，state 正确回退到初始值
- 如有手动迁移逻辑，验证转换后数据是否符合预期
- 建议在测试环境部署后，用灰度流量观察实际用户行为日志
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
