Pinia官方推荐的持久化方案是pinia-plugin-persistedstate，它通过注册插件并配置persist选项，自动将store状态同步至localStorage等介质，支持路径过滤、存储介质切换、key重命名及自定义序列化。
Pinia 本身不自带持久化功能，状态默认只存于内存，刷新即丢。要让数据跨页面、跨会话保留，必须借助插件实现自动同步到本地存储。目前最主流、官方推荐的方案是 pinia-plugin-persistedstate，它能“零侵入”地为指定 store 添加 localStorage（或 sessionStorage、自定义存储）支持。
基础启用：三步完成全局接入
只需安装、注册、标记，无需手写 setItem/getItem：
- 安装插件：
npm install pinia-plugin-persistedstate - 在创建 pinia 实例时注册：
pinia.use(piniaPluginPersistedstate) - 在目标 store 中开启
persist: true，例如：export const useUserStore = defineStore('user', {<br> state: () => ({ token: '', name: '' }),<br> persist: true<br>})
此时插件会自动将整个 state 序列化后存入 localStorage，key 默认为 "pinia/user"。
按需持久化：精准控制保存哪些字段
不是所有状态都需要持久化。比如临时 UI 状态（展开菜单、表单草稿）、函数或 undefined 值无法序列化，应排除。
- 用
paths明确指定仅保存关键字段：persist: { paths: ['token', 'theme', 'language'] } - 注意：paths 只支持顶层属性名，不支持嵌套路径如
profile.email；若需深层字段，得先扁平化 state 或配合partialize函数 - 敏感信息（如 token）建议搭配
storage: sessionStorage，避免多标签页共享时的潜在风险
适配不同平台：uni-app 等跨端项目专用方案
H5 用 localStorage，小程序用 uni.setStorageSync，App 用 plus.storage——这些 API 差异大，手动适配易出错。
- uni-app 推荐使用
pinia-plugin-unistorage或pinia-plugin-persist-uni - 它们会自动识别
process.env.UNI_PLATFORM，调用对应平台的存储接口，一行配置即可统一处理 - 例如：
persist: { storage: uniStorageAdapter }，无需判断环境再写分支逻辑
规避常见坑点：确保持久化稳定可靠
持久化不是“开箱即用就万事大吉”，几个关键细节决定成败：
- SSR 场景下 localStorage 不可用，插件会跳过写入，但首次客户端 hydration 可能造成状态闪烁——建议服务端预取数据，或显式设置
ssr: false - state 中含函数、Symbol、undefined、DOM 节点等非 JSON 友好值，会被
JSON.stringify静默忽略——务必保证持久化字段是纯对象/数组/字符串/数字/布尔值 - 多个 tab 同时修改同一 store 时，localStorage 不触发跨窗口事件——如需实时同步，需额外监听
storage事件并调用$patch手动更新
