Pinia 默认不持久化状态,需通过 pinia-plugin-persistedstate 插件实现;安装后在 main.ts 中注册,再于 store 中配置 persist 选项(如 paths 或 storage),注意字段可序列化、避免嵌套路径及敏感信息存储安全。

Pinia 默认不保存状态到本地,页面一刷就清空。要让 token、用户信息、主题设置这类数据“留下来”,得靠 pinia-plugin-persistedstate 插件自动存进 localStorage 或 sessionStorage——不用手写 setItem/getItem,三步就能配好。
安装并全局注册插件
在项目中安装插件:
- npm install pinia-plugin-persistedstate(或 pnpm add / yarn add)
然后在创建 Pinia 实例的地方(通常是 main.ts)注册它:
- 导入插件:import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
- 调用:pinia.use(piniaPluginPersistedstate)
这一步做完,插件就已就绪,后续只需在具体 store 中声明需求即可。
在 Store 中启用持久化
不是所有 store 都需要持久化,只在目标 store 定义里加 persist 配置:
- persist: true —— 全量保存整个 state,key 默认为 "pinia/你的storeID"
- persist: { paths: ['token', 'theme', 'language'] } —— 只存指定顶层字段,推荐用法,避免误存函数、undefined 或临时 UI 状态
- persist: { omit: ['loading', 'error'] } —— 排除不需要的字段,效果等同于 paths 白名单
按场景选存储位置和高级配置
localStorage 和 sessionStorage 行为不同,选错会影响体验:
- localStorage:适合长期保留的数据(如登录凭证、用户偏好),关浏览器再开还在
- sessionStorage:适合单标签页生命周期的数据(如多步骤表单中间态),换标签页即清空
- 可显式指定:persist: { storage: sessionStorage }
- 重命名 key:persist: { key: 'my_app_user' }
- 开启调试:persist: { debug: true },方便排查序列化失败等问题
注意事项和避坑点
持久化看似简单,但几个关键细节容易出问题:
- paths 只支持顶层字段名,不支持嵌套路径(如 profile.email),深层字段需先扁平化 state 或配合 partialize 函数
- state 必须可序列化:不能含函数、undefined、Symbol、Date 对象等;否则 JSON.stringify 会静默丢弃
- 敏感信息慎用 localStorage:比如 token 建议搭配 sessionStorage,避免多标签页共享时被意外读取
- 跨端项目(如 uni-app)需适配平台 API:H5 用 localStorage,小程序用 uni.setStorageSync,推荐用 pinia-plugin-unistorage 统一处理










