Pinia官方推荐的持久化方案是pinia-plugin-persistedstate，通过注册插件并配置persist选项，可自动将store状态同步至localStorage等介质，支持路径过滤、存储介质切换、key重命名及自定义序列化。

Pinia 官方推荐的持久化方案是 pinia-plugin-persistedstate，它能自动将 store 的状态同步到 localStorage（或 sessionStorage、自定义存储介质），页面刷新后数据不丢失。核心在于“自动”——你只需注册插件并简单配置，无需手动写 setItem / getItem。

安装与基础注册

先安装插件：

npm install pinia-plugin-persistedstate

然后在创建 pinia 实例时注册：

import { createPinia } from 'pinia'
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate'

const pinia = createPinia()
pinia.use(piniaPluginPersistedstate)

这样所有开启了 persist: true 的 store 都会默认使用 localStorage 持久化。

为指定 store 启用持久化

在 store 定义中添加 persist 选项即可启用：

export const useUserStore = defineStore('user', {
state: () => ({
name: '',
token: '',
role: 'guest'
}),
persist: true // ✅ 开启自动持久化
)

插件会自动将该 store 的整个 state 序列化后存入 localStorage，key 默认为 store 名（如 "pinia/user"）。

精细化控制：过滤字段与自定义存储

常用场景包括：只保存敏感字段、排除临时计算属性、换用 sessionStorage、或对接 IndexedDB：

• 只持久化部分字段：persist: { paths: ['token', 'role'] }
• 用 sessionStorage 替代 localStorage：persist: { storage: sessionStorage }
• 重命名存储 key：persist: { key: 'my_app_user' }
• 自定义序列化（例如加密）：persist: { serializer: { serialize: encrypt, deserialize: decrypt } }

注意：paths 中的字段必须是顶层响应式属性名，不支持嵌套路径如 profile.name（需配合 partialize 或手动扁平化）。

注意事项与常见问题

持久化不是万能的，需留意以下几点：

• 服务端渲染（SSR）时，localStorage 不可用，插件会自动跳过写入，但首次客户端 hydration 可能出现闪烁 —— 建议搭配 ssr: false 或服务端预取逻辑
• state 中含函数、Symbol、undefined、DOM 节点等无法序列化的值，会被 JSON.stringify 忽略 —— 确保 state 是纯 JSON 友好结构
• 多个 tab 同时修改同一 store 时，localStorage 不触发跨窗口事件 —— 如需实时同步，需额外监听 storage 事件并手动 $patch
• 升级 store 结构后旧数据可能解析失败 —— 可通过 version 字段 + beforeRestore 钩子做迁移处理