UniApp项目Pinia状态持久化插件

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：保存时转为带标记的对象，恢复时再转回 Date
• BigInt：保存时转为字符串，避免 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、设置项、用户偏好等轻量状态的场景，这个插件确实能大幅减少重复代码。而更复杂的数据持久化需求，建议结合业务实际情况，在其基础上进行二次封装。