Pinia 状态持久化需自动同步机制：加载时从 localStorage 恢复，变更时自动写回；推荐 useLocalStorage 处理独立配置项，pinia-plugin-persistedstate 管理整 Store；注意 SSR、数据类型及多标签页同步限制。

让 Pinia 状态在页面刷新后不丢失，关键不是手动存取，而是建立自动同步机制。核心就两点：加载时从 localStorage 读取并恢复，变更时自动写回。推荐优先用成熟方案，避免重复造轮子。

用 useLocalStorage 处理单个字段

适合主题色、播放模式、语言偏好等独立配置项。轻量、直观、类型安全。

• 安装 VueUse：npm install @vueuse/core
• 在 Store 或组件中直接绑定：const theme = useLocalStorage('app-theme', 'light')
• 后续所有对 theme.value 的读写，都会自动与 localStorage 同步
• 修改即生效：theme.value = 'dark' → 立刻存入；刷新页面 → 自动读取赋值

用 pinia-plugin-persistedstate 管理整个 Store

适合用户信息、购物车、表单草稿等需整体持久化的场景。声明式配置，省心可靠。

• 安装插件：npm install pinia-plugin-persistedstate
• 在 main.ts 中注册：pinia.use(piniaPluginPersistedState)
• 在 Store 定义中开启：persist: true（整 state 持久化）
• 如只需部分字段，可细化：persist: { paths: ['token', 'userInfo'] }

精细化控制常见需求

插件支持灵活配置，覆盖多数实际场景：

• 换用 sessionStorage：persist: { storage: sessionStorage }
• 自定义存储 key：persist: { key: 'my_user_data' }
• 加密存储（需配合自定义序列化器）：serializer: { serialize: encrypt, deserialize: decrypt }
• 注意：paths 只支持顶层字段名，不支持 profile.name 这类嵌套路径

注意事项与避坑点

自动同步虽方便，但需留意运行环境和数据结构限制：

• 服务端渲染（SSR）时 localStorage 不可用，插件会跳过写入，首次 hydration 可能有闪烁 —— 建议搭配 ssr: false 或预取逻辑
• state 中不能含函数、Symbol、undefined、DOM 节点等非 JSON 友好值，否则会被 JSON.stringify 忽略
• 多标签页同时修改同一状态时，localStorage 不触发跨窗口事件 —— 如需实时同步，需额外监听 storage 事件并调用 $patch