Pinia 默认不持久化状态，需安装 pinia-plugin-persistedstate 插件并调用 .use() 全局启用；再在具体 store 的 persist 选项中配置 enabled、storage、paths 和 key 实现精准持久化。
Pinia 本身只在内存中维护状态，页面一刷新，所有 store 数据就清空了。要让登录态、用户信息、主题偏好等关键数据“记住”，就得靠持久化插件把状态自动存进 localStorage 或 sessionStorage，刷新后自动读取恢复。
安装并注册持久化插件
先装插件，再挂载到 Pinia 实例上，全局启用持久化能力：
- 运行命令安装：
npm install pinia-plugin-persistedstate（推荐这个名称，社区最主流、维护活跃） - 在
src/stores/index.ts中创建 Pinia 实例时调用.use()：
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'
const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)
export default pinia
这一步做完，整个应用就具备了持久化基础——但具体哪些 store 要存、存哪些字段、存在哪，还得单独配置。
在 Store 中开启持久化并精细控制
不是所有状态都该持久化。比如临时搜索关键词、动画开关就不必存；而 token、userProfile、themeMode 这类核心数据必须存。通过 persist 选项精准控制：
立即学习“前端免费学习笔记（深入）”；
-
启用开关：设
enabled: true -
指定存储位置：默认是
localStorage，如需关页即失效，可改用sessionStorage -
选择保存字段：用
paths列出要持久化的响应式属性名，避免整 state 全存（例如只存['token', 'userInfo']） -
自定义存储 key：用
key改变 localStorage 里的键名，方便调试和隔离（如设为'app-user-store'）
state: () => ({
token: '',
userInfo: null as UserInfo | null,
themeMode: 'light'
}),
persist: {
enabled: true,
storage: sessionStorage, // 或 localStorage
key: 'user-persist',
paths: ['token', 'userInfo']
}
})
注意几个易错点
持久化不是“开了就万事大吉”，实际使用中容易踩坑：
- 不要持久化函数、DOM 引用、Promise 实例等无法序列化的值——它们会被 JSON.stringify 丢弃，导致恢复后 state 不完整
-
修改了 store 结构（比如删字段或改类型）后，旧 localStorage 数据可能解析失败，建议加
beforeRestore或afterRestore钩子做兼容处理 - 敏感信息（如 refreshToken）不建议直接存在 localStorage，即使加密也需谨慎；生产环境更推荐服务端 session + httpOnly cookie 方案
- 如果用了 TypeScript，记得在
tsconfig.json的"types"中加入"pinia-plugin-persistedstate"，否则类型提示会缺失
验证是否生效
最直接的验证方式：打开浏览器开发者工具 → Application → Storage → LocalStorage（或 SessionStorage），找到你设置的 key（如 user-persist），看值是否随 store 更新而实时变化；然后刷新页面，检查 store.state 是否与缓存一致、组件渲染是否保持上次状态。
