UniApp Pinia 持久化插件推荐：pinia-plugin-uni-persist-next 使用指南
在 Vue 3 + Pinia 构建的项目中，store 默认只是内存里的“临时存储区”——一旦页面刷新、App 重启或者小程序重新进入，所有状态便会瞬间清零，辛苦积累的数据说没就没。
但难点在于，UniApp 项目往往需要同时运行在 H5、App 和小程序端，直接套用 localStorage 显然行不通。因此这款插件干脆基于 UniApp 自带的 storage API 打造了一套 Pinia 状态持久化方案，专门解决这种“跨端”场景下最让人头疼的数据保存问题。
简单来说，@rdeam/pinia-plugin-uni-persist-next 能够自动将 Pinia 中的 store 写入 UniApp 的 storage，并在应用启动时自动读取恢复，省去手动调用 uni.setStorage 或 uni.getStorage 的重复劳动。
安装方式
pnpm add @rdeam/pinia-plugin-uni-persist-next
基本用法
使用之前，需要先将插件注册到 Pinia 实例中，为 store 装上“持久化引擎”：
import { createPinia } from 'pinia';
import { createUniPersistPlugin } from '@rdeam/pinia-plugin-uni-persist-next';const pinia = createPinia();pinia.use(
createUniPersistPlugin({
keyPrefix: 'app_storage_',
}),
);
接着，在需要持久化的 store 里添加 persist 配置，示例如下：
import { defineStore } from 'pinia';export const useUserStore = defineStore('user', {
state: () => ({
token: '',
userInfo: null,
}),
persist: {
enabled: true,
strategies: [
{
key: 'user',
paths: ['token'],
},
],
},
});
这个配置的效果是——仅持久化 token 字段，userInfo 对象不会被写入 storage。相比以前手动读写 storage 的重复操作，这种声明式配置明显更加清爽高效。
为什么需要 paths
之所以要引入 paths，是因为并非所有状态都适合一股脑塞进 storage。
比如用户的 token、语言偏好、主题设置——这些数据确实应该持久保存。但如果把列表数据、临时弹窗状态甚至接口返回的大对象也存进去，不仅浪费存储空间，还可能拖累性能。
因此插件提供了 paths 选项，让开发者精确控制需要持久化的字段：
persist: {
enabled: true,
strategies: [
{
key: 'user',
paths: ['token'],
},
],
}
不过有一点需要注意：paths 目前仅支持顶层字段。也就是说写 ['token'] 完全没问题，但像 ['user.info.name'] 这种深层路径暂时还不支持——这并非当前版本的能力范围。
多策略存储
一个 store 还可以配置多个保存策略，将不同字段拆分到不同的 storage key 中。例如：
persist: {
enabled: true,
strategies: [
{
key: 'user_token',
paths: ['token'],
},
{
key: 'user_profile',
paths: ['userInfo'],
},
],
}
这样一来，token 和用户资料就能分开展开、分开管理，比全部挤在同一个 key 里更加清晰有序。
同步恢复与默认异步写入
在数据恢复环节，插件采用了 uni.getStorageSync，优势在于 store 初始化时能尽快获取本地数据，不会因为异步等待而阻塞整个流程。
写入时，默认走的是异步 API uni.setStorage：
persist: {
enabled: true,
async: true,
}
当然也支持改为同步写入，配置方式同样简洁：
persist: {
enabled: true,
async: false,
}
甚至还可以在单个策略上独立控制，无需全局调整：
persist: {
enabled: true,
strategies: [
{
key: 'user',
paths: ['token'],
async: false,
},
],
}
恢复前后的生命周期钩子
插件提供了两个实用的生命周期钩子——beforeRestore 和 afterRestore：
persist: {
enabled: true,
beforeRestore(ctx) {
console.log('即将恢复状态', ctx.store.$id);
},
afterRestore(ctx) {
console.log('状态恢复完成', ctx.store.$id);
},
}
这两个钩子非常适合用于日志记录、埋点上报，或者在恢复前后执行一些轻量级逻辑，比如恢复后触发一次数据同步。但需要留意的是，钩子内应避免执行过重操作，毕竟持久化恢复本身涉及同步读写，一旦卡住会影响整体体验。
清理 storage
插件还内置了两个实用的工具方法：
import { clearAll, clearStore } from '@rdeam/pinia-plugin-uni-persist-next';clearStore('app_storage_user');
clearAll();
不过有一点需要特别留意：clearAll() 底层调用的是 uni.clearStorageSync()，它并非只清除插件写入的数据，而是将整个应用的 storage 全部清空。这在开发阶段使用尚可，生产环境中还请谨慎调用，否则很可能误删其他模块的数据。
数据序列化说明
storage 本质上只能存储字符串，因此插件内部自然需要进行 JSON 序列化。当前版本对一些特殊类型做了额外处理：
Date：保存时转为带标记的对象，恢复时再转回DateBigInt：保存时转为字符串，避免JSON.stringify直接报错- 循环引用：保存时用占位字符串替代，防止序列化过程中崩溃
但需要明确一点：BigInt 恢复后目前仍是字符串，而非 bigint 类型。如果你的业务逻辑强依赖 bigint，读取后需要手动转换回来，或者等待后续版本支持完整的类型还原。
适用场景分析
总体来看，这款插件比较适合以下情况：
- UniApp 项目正在使用 Pinia 管理状态
- 需要保存 token、用户偏好、简单配置等轻量数据
- 希望 store 初始化时自动从本地恢复数据，无需手动调用 storage API
- 不想在每个 store 中重复编写
uni.setStorage和uni.getStorage
不太适用的场景也很明确：
- 需要保存大量列表数据，例如上千条的表格或日志
- 需要复杂的深层字段选择，比如
a.b.c.d这种嵌套路径 - 需要加密、过期时间、版本迁移等高级持久化能力
- 对 BigInt、Map、Set 等复杂类型有“存什么恢复什么”的完整要求
这些更复杂的诉求，要么在业务层自行封装，要么等待该插件后续版本逐步完善。
总结
@rdeam/pinia-plugin-uni-persist-next 并非一个功能庞杂的插件，它核心解决的是 UniApp 项目中 Pinia 状态持久化的基础问题：
- store 开启配置后自动保存数据
- 应用启动时自动将数据恢复至 store
- 支持自定义 key 前缀
- 支持按字段筛选，避免全量存储
- 支持同步或异步写入策略
- 基于 UniApp 自带的 storage API，能够适配多端运行
对于大多数只需稳定保存 token、设置项、用户偏好等轻量状态的场景，这个插件确实能大幅减少重复代码。而更复杂的数据持久化需求，建议结合业务实际情况，在其基础上进行二次封装。
