Pinia 的 state 默认不持久化，需借助 pinia-plugin-persistedstate 插件实现自动同步 localStorage/sessionStorage；支持全局或按 store/字段粒度配置，兼容 Vue3，开箱即用。
Pinia 的 state 本身不自动持久化，但配合插件可以轻松实现本地存储缓存。核心思路是：让 state 的读写过程自动同步到 localStorage（或 sessionStorage），页面刷新后自动恢复。
用 pinia-plugin-persistedstate 插件实现自动缓存
这是最主流、最稳定的方式，专为 Pinia 设计，支持 Vue3，开箱即用。
- 安装插件：
npm install pinia-plugin-persistedstate - 在
main.js中注册（注意顺序：先创建 pinia，再 use 插件，最后挂载）：
import { createPinia } from 'pinia'
import { createPersistedState } from 'pinia-plugin-persistedstate'
const pinia = createPinia()
pinia.use(createPersistedState()) // ✅ 必须在这一步注册
createApp(App).use(pinia).mount('#app')
```
- 在 store 定义中按需开启持久化（默认全部 state 都缓存，可精确控制）：
export const useUserStore = defineStore('user', {
state: () => ({
token: '',
userInfo: null,
theme: 'light'
}),
persist: true // ✅ 全局启用（整个 store 缓存）
// 或更细粒度控制：
// persist: {
// key: 'user-store',
// paths: ['token', 'userInfo'] // 只缓存这两个字段
// }
})
```
手动控制缓存范围与时机
不是所有状态都需要持久化。比如临时表单草稿、未提交的筛选条件，适合用 sessionStorage；登录态、用户偏好则适合 localStorage。
- 插件支持自定义 storage 实例，可区分场景：
import { createPersistedState } from 'pinia-plugin-persistedstate'
// 为不同 store 指定不同 storage
pinia.use(createPersistedState({
storage: window.sessionStorage // 默认是 localStorage
}))
```
- 也可以在单个 store 中覆盖全局配置：
persist: {
storage: window.sessionStorage,
paths: ['draftContent'] // 仅草稿走 sessionStorage
}
```
注意事项和常见避坑点
缓存不是“设了就完事”，几个关键细节影响实际体验：
- 响应式失效风险：如果 state 中有 Date、RegExp、Map、Set 等非 JSON 可序列化类型，插件会静默跳过 —— 建议只缓存 plain object / array / string / number / boolean
-
多标签页同步问题：localStorage 修改不会自动触发其他标签页的 state 更新。如需实时同步，得监听
storage事件并手动 $patch，或改用sharedWorker方案 - 敏感数据别硬存：token、密码等应配合 HttpOnly Cookie + 后端校验，避免仅依赖前端缓存
- 版本升级时清旧缓存：store 结构变更后，旧 localStorage 数据可能引发解析错误。可在 persist 配置中加 version 字段或手动清理：
persist: {
key: 'user-store-v2', // 更换 key 即自然隔离
// 或在 onRehydrateStorage 中做兼容处理
afterRestore: (ctx) => {
if (!ctx.store.token) ctx.store.$reset()
}
}
```
