Pinia需通过persist.paths白名单精准指定要缓存的state顶层字段,如['token', 'theme'],仅这些字段存入localStorage/sessionStorage;不支持嵌套路径,敏感信息须脱敏后存储。

Pinia 默认不保存状态,要实现部分 state 属性的缓存,关键在于配置 persist 选项中的 paths 字段。它允许你精准控制哪些字段写入 localStorage(或 sessionStorage),其余字段仍保持内存态、不落盘。
明确指定需要持久化的字段
在 defineStore 的配置对象中,通过 persist.paths 数组列出你要缓存的顶层属性名。只有这些字段会被序列化并存入本地存储,其他字段刷新即丢失。
-
paths: ['token', 'theme', 'lastVisitedPage']—— 只缓存这三个字段 - 字段必须是 state 的直接子属性(不支持嵌套路径如
userInfo.name) - 若 state 中有大数组或复杂对象,建议只存 ID 或必要摘要,避免影响性能和存储限额
配合 storage 类型与键名控制
默认使用 localStorage,但你可以显式指定 storage 方式,并自定义存储 key,方便调试和隔离:
-
storage: sessionStorage—— 页面会话级缓存,关闭标签页即清空 -
key: 'user-preferences'—— 覆盖默认生成的 key(如 store id),避免多个 store 冲突 - 组合示例:
{ enabled: true, paths: ['theme', 'fontSize'], storage: sessionStorage, key: 'ui-settings' }
避免常见误用
paths 不是“排除列表”,而是“白名单”。只要没列进去,就不会持久化——这点和很多人直觉相反:
- ❌ 错误:以为
paths: ['token']会自动包含userInfo(除非你也把它加进去) - ❌ 错误:在 paths 中写
'userInfo.name'—— 插件不解析点号路径,该字段将被忽略 - ✅ 正确做法:若需缓存用户部分信息,可提前在 state 中拆出扁平字段,例如
userId、userName、userAvatar
敏感信息要格外注意
即使只选了部分字段,也要确认它们不包含明文密码、临时 token、授权密钥等:
- token 若需持久化,建议搭配过期时间字段(如
tokenExpiry),并在 getter 中做有效性判断 - 避免缓存
rawUserData这类可能含隐私的完整对象,优先缓存脱敏后字段 - 服务端返回的敏感字段,应在 action 中清洗后再赋值给可持久化的 state 属性


















