Pinia 默认状态不持久，需用 pinia-plugin-persistedstate 插件实现自动存取 localStorage/sessionStorage；配置含安装、注册、启用三步，支持 paths/omit 精确控制字段，按需选存储介质，并注意安全与序列化限制。
Pinia 默认只管内存里的状态，一刷新就清空。要让登录信息、表单草稿、用户偏好这些关键数据“活下来”，就得靠持久化插件。核心是用 pinia-plugin-persistedstate，它不是黑魔法，而是把状态自动存进 localStorage 或 sessionStorage，并在页面加载时自动取出来“水合”到 store 里。
基础配置三步走
不用写一行 localStorage 操作，就能让状态自动落盘：
- 安装插件：用
pnpm add pinia-plugin-persistedstate（或 npm/yarn） - 注册插件：在
main.ts创建 Pinia 实例后调用pinia.use(piniaPluginPersistedstate) - 启用持久化：在需要保存的 store 定义中加上
persist: true
精准控制存哪些字段
不是所有 state 都该持久化。比如临时 UI 状态（弹窗开关、滚动位置）就不该留在本地，而 token、用户资料、主题设置才值得保存。用 paths 显式指定：
-
paths: ['token', 'userInfo', 'theme']—— 只存这几个字段 -
omit: ['loading', 'error']—— 排除这些字段（插件也支持 omit 写法） - 避免把整个大对象全存，既节省空间，也防止敏感临时数据意外泄露
按需选择存储介质
localStorage 和 sessionStorage 行为不同，选错会影响体验：
立即学习“前端免费学习笔记（深入）”；
-
localStorage：适合长期保存的数据，比如登录态、用户设置，关浏览器再开还在 -
sessionStorage：适合仅限当前标签页的数据，比如多步骤表单的中间状态，换标签页就清空 - 可在 persist 配置里指定：
storage: sessionStorage，或通过 strategy 自定义多个存储目标
注意安全与边界情况
持久化不是万能胶，几个关键点容易踩坑：
- Token 存 localStorage 要谨慎——建议配合 HttpOnly Cookie + refreshToken 机制，避免 XSS 直接盗取
- store 初始化时，如果 localStorage 数据损坏（如 JSON 解析失败），插件会静默跳过，state 保持初始值，不会报错中断应用
- 跨域 iframe 或无痕模式下，localStorage 可能不可用，插件会自动降级为内存存储，不抛异常
- 不要存函数、Date 对象、Map/Set 等无法被 JSON 序列化的值，否则会被忽略或转成空对象
