Pinia 默认不支持持久化，需借助 pinia-plugin-persistedstate 插件实现；安装后全局注册，再在 store 中配置 persist 选项（如 true、paths 或 omit），可指定 storage（localStorage/sessionStorage）、调试及数据迁移钩子，并注意仅支持顶层字段、避免敏感信息明文存储及确保 state 可序列化。
Pinia 本身不带持久化能力，状态默认只存在内存里，页面一刷新就清空。要让 token、用户信息、主题设置等关键数据“留下来”，得靠插件自动存到 localStorage 或 sessionStorage。目前最成熟、官方推荐的方案是 pinia-plugin-persistedstate，配置简单，基本三步就能跑起来，不用手动写 setItem / getItem。
安装并全局注册插件
先装插件：
- npm install pinia-plugin-persistedstate（或 pnpm add、yarn add）
然后在创建 Pinia 实例的地方注册它，通常在 main.ts 或 main.js 中：
- 引入插件：
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate' - 调用
pinia.use(piniaPluginPersistedstate)
这一步做完，插件就已就绪，后续只需在具体 store 中声明持久化需求即可。
在 Store 中启用持久化
不是所有 store 都需要持久化，只在你明确想“记住”的 store 里加 persist 配置：
- 全量保存（简单场景）：
persist: true—— 插件会把整个state序列化后存进localStorage，key 默认为"pinia/你的storeID" - 按字段保存（推荐）：
persist: { paths: ['token', 'theme', 'language'] }—— 只存指定顶层字段，避免误存函数、undefined 或临时 UI 状态（如isMenuOpen） - 排除字段（等效写法）：
persist: { omit: ['loading', 'error'] }
选择存储位置和自定义行为
localStorage 和 sessionStorage 行为不同，选错会影响体验：
- localStorage：适合长期保留的数据，比如登录凭证、用户偏好，关浏览器再开还在
- sessionStorage：适合单标签页生命周期的数据，比如多步骤表单中间态，换标签页即清空
可在 persist 中指定：
storage: sessionStorage- 或更灵活地用
strategies数组，支持多目标、自定义 key、不同字段存不同地方
另外可加 debug: true 查看持久化过程是否出错；用 beforeHydrate / afterHydrate 钩子做数据迁移或清洗（比如旧版本字段名变了，加载前先转换）。
注意事项和常见避坑
持久化不是“开个开关”就万事大吉，几个关键点要注意：
- 嵌套字段不能直接用
paths: ['profile.email']，只支持顶层属性名；深层字段需提前扁平化，或配合partialize函数处理 - 敏感信息（如 token）慎用
localStorage，建议改用sessionStorage降低跨标签页泄露风险 - 函数、Symbol、undefined、Date 对象等无法被
JSON.stringify正常序列化，插件会跳过或报错，务必确保state中只含可序列化值 - 首次加载时，插件会从存储中“水合（hydrate）”数据覆盖初始 state，所以初始值应设为合理默认值（如
token: ''），而非依赖本地已有数据
