uniapp小程序数据持久化的最佳实践

一、引言

在小程序开发中，数据持久化是最常见也最重要的需求之一。它能让用户的设置、登录状态、缓存列表、离线阅读数据等在应用重启或断网情况下依然可用，从而大幅提升用户体验和业务连续性。结合 uniapp 跨平台特性，开发者需要兼顾微信、支付宝、百度、字节等多个小程序平台的存储能力与限制，才能设计出既可靠又高效的持久化方案。

本文将从以下几个方面展开全面讲解：

小程序存储基础概念与限制
常用本地持久化方案对比与示例
- uniapp 原生 Storage API（uni.setStorage / uni.getStorage 等）
- plus 小程序原生 Storage（plus.storage）与插件化数据库（如 SQLite）
- Vuex/Pinia + 持久化插件（vuex-persistedstate 等）
云端存储与同步设计思路
数据版本管理与迁移策略
安全性（加密、签名、校验）与异常容错
最佳实践总结

全文将通过“图解+代码”方式，深入剖析各种方案的优劣与使用细节，帮助你在实际项目中快速选型与落地。

二、小程序存储基础概念与限制

2.1 微信/支付宝/百度小程序本地存储介绍

不同平台对本地存储的能力与限制略有差异，但整体思路相似，都提供了简单的键值对存储（键最大长度约 128 字节，值大小有限制）与同步/异步接口。以微信小程序为例：

同步接口

uni.setStorageSync(key: string, data: any): void;
const value = uni.getStorageSync(key: string);

异步接口

uni.setStorage({
  key: 'userInfo',
  data: { name: '张三', id: 1001 },
  success: () => console.log('存储成功'),
  fail: () => console.error('存储失败')
});
uni.getStorage({
  key: 'userInfo',
  success: res => console.log(res.data),
  fail: () => console.error('未找到对应数据')
});

图1：小程序本地 Storage 数据流示意

┌───────────┐                       ┌─────────────┐
│   Page     │      uni.setStorage  │  Storage    │
│ (JS 层)    │ ───────────────────▶ │ (Key-Value) │
└───────────┘                       └─────────────┘
     ▲  │                                 ▲
     │  │ uni.getStorage(异步/同步)       │
     │  └─────────────────────────────────┘
     └─────────────────────────────────────
           JS 层从本地读写数据

一般情况下，本地 Storage常被用于：

用户登录态或 Token
配置信息（主题、语言、开关状态等）
离线/缓存数据（如文章列表、商品列表等）
临时会话数据（购物车、表单填写进度等）

存储限制概览

平台	单个 Key 大小限制	单个 Value 限制	总存储容量（≈）
微信小程序	\~128 KB	\~2 MB	10 MB 左右（不同基础库略有差异）
支付宝小程序	\~128 KB	\~2 MB	10 MB 左右
百度小程序	\~128 KB	\~2 MB	10 MB 左右
字节小程序	\~128 KB	\~2 MB	10 MB 左右

注意：上述数据仅供参考，各平台会根据基础库及版本迭代有所调整。在设计持久化时，务必先检查目标平台的文档及实际可用容量，避免因超限导致存储失败。

三、常用本地持久化方案对比与示例

在 uniapp 中，除了最基础的 uni.setStorage / uni.getStorage，还可借助更丰富的存储方案来满足不同复杂度的需求。以下逐一介绍几种常用方案，并配以代码示例与图解。

3.1 uniapp 原生 Storage API （键值对存储）

3.1.1 同步与异步接口对比

同步接口
```
// 存储
uni.setStorageSync('settings', { theme: 'dark', fontSize: 16 });
// 读取
const settings = uni.getStorageSync('settings');
if (!settings) {
  // 初始值
  uni.setStorageSync('settings', { theme: 'light', fontSize: 14 });
}
```
- 优点：调用简单、时序可控，适合在应用启动或需要立即获取数据的场景。
- 缺点：同步调用会阻塞 JS 线程，若操作大量数据或在渲染过程中多次调用，可能造成界面卡顿。

异步接口

// 存储
uni.setStorage({
  key: 'userToken',
  data: 'abcdefg123456',
  success: () => console.log('Token 存储成功'),
  fail: err => console.error('存储失败', err)
});

// 读取
uni.getStorage({
  key: 'userToken',
  success: res => console.log('Token:', res.data),
  fail: () => console.log('无 Token')
});

优点：不会阻塞主线程，适合在业务流程中“无感”地读写数据。
缺点：需要使用回调或 Promise（可自行封装）来组织时序，适用场景需考虑异步时机。

图2：同步 vs 异步 Storage 调用时序示意
┌───────────────────────────────────────────┐
│         同步调用 (setStorageSync)        │
├───────────────────────────────────────────┤
│ 1. 调用 setStorageSync                   │
│ 2. JS 线程被阻塞，等待底层写入完成       │
│ 3. 写入完成后，返回                    │
│ 4. 继续后续逻辑                         │
└───────────────────────────────────────────┘
┌───────────────────────────────────────────┐
│ 异步调用 (setStorage) │
├───────────────────────────────────────────┤
│ 1. 调用 setStorage │
│ 2. 底层开始写入，但立即返回 │
│ 3. JS 线程继续执行后续逻辑 │
│ 4. 写入完成后触发 success 回调 │
└───────────────────────────────────────────┘

3.1.2 常见示例：持久化配置项、登录态与缓存列表

持久化用户登录态与 Token

// utils/auth.js
export function saveToken(token) {
  try {
    uni.setStorageSync('userToken', token);
  } catch (e) {
    console.error('保存 Token 失败', e);
  }
}

export function getToken() {
  try {
    return uni.getStorageSync('userToken') || '';
  } catch (e) {
    console.error('获取 Token 失败', e);
    return '';
  }
}

export function clearToken() {
  try {
    uni.removeStorageSync('userToken');
  } catch (e) {
    console.error('移除 Token 失败', e);
  }
}

说明：saveToken 用于将登录成功后的 token 保存到本地，后续请求可通过 getToken 读取并附加到请求头。
注意：若 token 长度接近存储上限，或平台存储容量接近饱和，可能出现写入失败，需要进行异常捕获与退路设计（如提示用户清理缓存）。

缓存网店商品列表（分页加载时可持久化当前页与滚动位置）

<template>
  <view class="container">
    <scroll-view :scroll-y="true" @scrolltolower="loadMore" :scroll-top="scrollTop" style="height: 100vh;">
      <view v-for="item in goodsList" :key="item.id" class="item-card">
        <text>{{ item.name }}</text>
        <text>¥{{ item.price }}</text>
      </view>
    </scroll-view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      goodsList: [],
      page: 1,
      pageSize: 20,
      scrollTop: 0 // 用于持久化滚动位置
    };
  },
  onLoad() {
    // 尝试恢复本地缓存
    const cache = uni.getStorageSync('goodsCache') || {};
    if (cache.list && cache.page) {
      this.goodsList = cache.list;
      this.page = cache.page;
      this.scrollTop = cache.scrollTop;
    } else {
      this.loadMore();
    }
  },
  onUnload() {
    // 离开页面时保存当前列表与页码、滚动位置
    try {
      uni.setStorageSync('goodsCache', {
        list: this.goodsList,
        page: this.page,
        scrollTop: this.scrollTop
      });
    } catch (e) {
      console.error('缓存商品列表失败', e);
    }
  },
  methods: {
    async loadMore() {
      // 省略请求逻辑，模拟延迟加载
      const newList = [];
      for (let i = 0; i < this.pageSize; i++) {
        newList.push({
          id: (this.page - 1) * this.pageSize + i,
          name: `商品 ${(this.page - 1) * this.pageSize + i}`,
          price: (Math.random() * 100).toFixed(2)
        });
      }
      // 模拟网络延迟
      await new Promise(res => setTimeout(res, 300));
      this.goodsList = [...this.goodsList, ...newList];
      this.page++;
    },
    onScroll(event) {
      // 记录滚动位置
      this.scrollTop = event.detail.scrollTop;
    }
  }
};
</script>

<style>
.item-card {
  padding: 10px;
  border-bottom: 1px solid #ddd;
}
</style>

说明：在 onLoad 中尝试恢复上一次缓存的列表数据及当前分页、滚动位置；在 onUnload 中将最新状态写入本地。
优点：用户切换到其他页面后再回来，可“无感”恢复上一次浏览进度，提升体验。
缺点：若商品列表数据过大，直接将整个数组写入本地可能导致存储压力或卡顿，应结合清理过期缓存或分页只缓存最近 N 页等策略。

3.1.3 大小限制与性能优化

分片存储：若某个 Key 对应的 Value 特别大（如需要缓存几百条对象），可以考虑将其拆分为多个 Key 存储。例如 cache_goods_1、cache_goods_2……
压缩存储：在写入本地前，将 JSON 数据进行 JSON.stringify 后，再进行 gzip 或 LZString 压缩，有助于减小占用。但需要兼容 uni.getStorage 读取时再做解压操作。

异步批量写入：若同时有多个大数据需要持久化，可按队列异步写入，避免一次性大写导致的卡顿。例如使用简单的写入队列与延迟策略：

// utils/storageQueue.js
const queue = [];
let writing = false;

function processQueue() {
  if (writing || queue.length === 0) return;
  writing = true;
  const { key, data } = queue.shift();
  uni.setStorage({
    key,
    data,
    complete: () => {
      writing = false;
      processQueue();
    }
  });
}

export function enqueueSet(key, data) {
  queue.push({ key, data });
  processQueue();
}

在项目中调用 enqueueSet('someKey', someLargeData)，即可保证一次写入完成后再写入下一个，不会造成同时触发多个 setStorage 带来的阻塞或冲突。

3.2 plus 小程序原生 Storage 与 SQLite 插件

uniapp 在 App（H5/原生 App）或部分小程序环境下，还可以使用 plus.storage 或集成 SQLite 插件来实现更复杂的本地数据库操作。以下仅做简要介绍，针对移动端 App 或高频读写场景更有意义。

3.2.1 plus.storage（仅限 App/H5 端，非小程序端）

写入

// 适用于 App/WebView 端
const key = 'localLogs';
const logs = plus.storage.getItem(key) ? JSON.parse(plus.storage.getItem(key)) : [];
logs.push({ time: Date.now(), action: 'click', details: {} });
plus.storage.setItem(key, JSON.stringify(logs));

读取

const logsString = plus.storage.getItem('localLogs');
const logs = logsString ? JSON.parse(logsString) : [];

说明：plus.storage 是基于 HTML5 WebStorage（localStorage） API 封装而来，底层同样用 Key-Value 存储，容量相对浏览器或宿主环境更充裕。但在小程序环境下并不适用，需使用 uni.setStorage。

3.2.2 SQLite 插件（大数据量、高并发读写场景）

若你的项目数据量非常大（如离线地图数据、离线笔记、用户行为日志等），单纯靠 Key-Value 存储已经无法满足需求，这时可通过以下方式引入 SQLite 插件：

安装插件
在 HBuilderX 插件市场或通过 npm 安装 weex-plugin-sqlite 类似第三方插件，或使用官方提供的 uniSQLite 插件（视平台而定）。

使用示例

import { openDatabase, executeSql, querySql } from '@/plugins/sqlite';

// 打开（或创建）本地数据库
const db = openDatabase({ name: 'myapp.db', location: 'default' });

// 创建表
executeSql(db, 'CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT, content TEXT, created_at INTEGER)');

// 插入数据
function saveNote(title, content) {
  const timestamp = Date.now();
  executeSql(db, 'INSERT INTO notes (title, content, created_at) VALUES (?, ?, ?)', [title, content, timestamp]);
}

// 查询数据
function getAllNotes(callback) {
  querySql(db, 'SELECT * FROM notes ORDER BY created_at DESC', [], (res) => {
    // res.rows 是结果集合
    callback(res.rows);
  }, (err) => {
    console.error('查询失败', err);
  });
}

// 删除数据
function deleteNote(id) {
  executeSql(db, 'DELETE FROM notes WHERE id = ?', [id]);
}

图3：SQLite 数据库示意

┌───────────────────────────────────────────┐
│             本地 SQLite 数据库             │
│ ┌───────────┬───────────────┬────────────┐ │
│ │   Table   │     Column    │   Type     │ │
│ ├───────────┼───────────────┼────────────┤ │
│ │   notes   │ id            │ INTEGER PK │ │
│ │           ├───────────────┼────────────┤ │
│ │           │ title         │ TEXT       │ │
│ │           ├───────────────┼────────────┤ │
│ │           │ content       │ TEXT       │ │
│ │           ├───────────────┼────────────┤ │
│ │           │ created_at    │ INTEGER    │ │
│ └───────────┴───────────────┴────────────┘ │
└───────────────────────────────────────────┘

优点：支持复杂查询、事务、索引，对大数据量场景更友好。
缺点：需要额外引入插件，打包体积会增加；部分小程序平台不支持本地 SQLite（仅限 App/H5 端或特定插件市场），兼容性需自行评估。

3.3 Vuex/Pinia + 持久化插件

对于中大型项目，开发者通常会使用集中式状态管理（Vuex 或 Pinia）来管理全局状态。配合“持久化插件”（如 vuex-persistedstate 或 [pinia-plugin-persistedstate](https://github.com/prazdevs/pinia-plugin-persistedstate）），可自动将部分或全部状态写入本地 Storage，实现“关机不丢失状态”。

3.3.1 Vuex + vuex-persistedstate 示例

安装依赖
```
npm install vuex vuex-persistedstate
```

配置 Vuex Store

// store/index.js
import Vue from 'vue';
import Vuex from 'vuex';
import createPersistedState from 'vuex-persistedstate';

Vue.use(Vuex);

const store = new Vuex.Store({
  state: {
    userInfo: null,
    settings: {
      theme: 'light',
      fontSize: 14
    },
    cart: [] // 购物车商品列表
  },
  mutations: {
    setUserInfo(state, user) {
      state.userInfo = user;
    },
    updateSettings(state, settings) {
      state.settings = { ...state.settings, ...settings };
    },
    addToCart(state, item) {
      state.cart.push(item);
    },
    clearCart(state) {
      state.cart = [];
    }
  },
  actions: {
    login({ commit }, user) {
      commit('setUserInfo', user);
    }
  },
  plugins: [
    createPersistedState({
      storage: {
        getItem: key => uni.getStorageSync(key),
        setItem: (key, value) => uni.setStorageSync(key, value),
        removeItem: key => uni.removeStorageSync(key)
      },
      // 只持久化部分 state，避免把整个 store 都存储进去
      reducer: state => ({
        userInfo: state.userInfo,
        settings: state.settings
      })
    })
  ]
});

export default store;

说明：createPersistedState 插件会在每次 state 变化后自动将指定数据序列化并写入本地 Storage（key 默认为 vuex 或可自定义）。
优点：无需手动调用 uni.setStorage，由插件负责把 state 与 Storage 同步，减少重复代码；支持“白名单”/“黑名单”配置，可灵活指定需要持久化的字段。
缺点：如果 reducer 返回的对象过大，插件每次触发都会序列化并写入一次，可能导致卡顿；需要谨慎选择要持久化的字段，避免保存大量数组或对象。

页面中使用

<script>
import { mapState, mapMutations } from 'vuex';

export default {
  computed: {
    ...mapState(['userInfo', 'settings'])
  },
  methods: {
    ...mapMutations(['updateSettings']),
    switchTheme() {
      const newTheme = this.settings.theme === 'light' ? 'dark' : 'light';
      this.updateSettings({ theme: newTheme });
    }
  },
  onLoad() {
    // 页面加载时，store 中的 userInfo 与 settings 已被插件自动恢复
    console.log('当前主题：', this.settings.theme);
  }
};
</script>

效果：用户切换主题后，无需额外手动存储操作，下次打开应用时 settings.theme 自动恢复到上一次的值。

3.3.2 Pinia + pinia-plugin-persistedstate 示例

若使用 Pinia（Vue3 推荐方案），配合 pinia-plugin-persistedstate 也可实现同样效果。

安装依赖

npm install pinia pinia-plugin-persistedstate

配置 Pinia

// store/index.js
import { createPinia } from 'pinia';
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';

const pinia = createPinia();
pinia.use(
  piniaPluginPersistedstate({
    storage: {
      getItem: key => uni.getStorageSync(key),
      setItem: (key, value) => uni.setStorageSync(key, value),
      removeItem: key => uni.removeStorageSync(key)
    }
  })
);

export default pinia;

定义 Store（以 User Store 为例）

// store/user.js
import { defineStore } from 'pinia';

export const useUserStore = defineStore({
  id: 'user',
  state: () => ({
    userInfo: null,
    token: ''
  }),
  actions: {
    setUser(user) {
      this.userInfo = user;
      this.token = user.token;
    },
    logout() {
      this.userInfo = null;
      this.token = '';
    }
  },
  persist: {
    enabled: true, // 使用默认 key = 'pinia'
    strategies: [
      {
        key: 'user-store',
        storage: {
          getItem: key => uni.getStorageSync(key),
          setItem: (key, value) => uni.setStorageSync(key, value),
          removeItem: key => uni.removeStorageSync(key)
        },
        paths: ['userInfo', 'token'] // 只持久化 userInfo 与 token
      }
    ]
  }
});

页面调用示例

<template>
  <view>
    <text v-if="userStore.userInfo">欢迎，{{ userStore.userInfo.name }}</text>
    <button @click="loginDemo">模拟登录</button>
  </view>
</template>

<script>
import { useUserStore } from '@/store/user';

export default {
  setup() {
    const userStore = useUserStore();

    function loginDemo() {
      // 模拟后端返回
      const mockUser = { name: '李四', token: 'xyz789' };
      userStore.setUser(mockUser);
    }

    return { userStore, loginDemo };
  }
};
</script>

效果：用户调用 loginDemo 后，userInfo 与 token 被写入本地，下次打开小程序时可自动恢复，若用户调用 logout()，对应本地数据也会被清理。

四、云端存储与同步设计思路

除了本地持久化，在有网络的情况下，将数据同步到云端或自建后端，是保证数据不丢失、在多端设备共享场景中常用的做法。以下以微信小程序云开发（CloudBase / 云开发）为例，介绍最常见的云端存储方案。

4.1 微信小程序云开发（CloudBase）示例

初始化云开发环境

// main.js / App.vue 入口
if (uni.cloud) {
  uni.cloud.init({
    env: 'your-env-id', // 云环境 ID
    traceUser: true
  });
}

获取数据库引用

const db = uni.cloud.database();
const notesCollection = db.collection('notes');

增删改查示例

新增笔记

async function addNoteToCloud(title, content) {
  try {
    const timestamp = new Date().getTime();
    const res = await notesCollection.add({
      data: {
        title,
        content,
        created_at: timestamp,
        updated_at: timestamp
      }
    });
    console.log('笔记添加成功，ID：', res._id);
    return res._id;
  } catch (e) {
    console.error('添加笔记失败', e);
    throw e;
  }
}

获取全部笔记

async function getAllNotesFromCloud() {
  try {
    const res = await notesCollection.orderBy('created_at', 'desc').get();
    return res.data; // array of notes
  } catch (e) {
    console.error('获取笔记失败', e);
    return [];
  }
}

更新笔记

async function updateNoteInCloud(id, newContent) {
  try {
    const timestamp = new Date().getTime();
    await notesCollection.doc(id).update({
      data: {
        content: newContent,
        updated_at: timestamp
      }
    });
    console.log('更新成功');
  } catch (e) {
    console.error('更新失败', e);
  }
}

删除笔记

async function deleteNoteFromCloud(id) {
  try {
    await notesCollection.doc(id).remove();
    console.log('删除成功');
  } catch (e) {
    console.error('删除失败', e);
  }
}

本地缓存 + 云同步思路

在离线/网络波动场景下，推荐使用“本地先写，后台异步同步”的思路：

流程示意（ASCII）

┌────────────┐        1. 本地添加/更新/删除     ┌─────────────┐
│  Page/Store │ ─────────────────────────────▶ │  Local DB   │
│            │                                 │  （SQLite/Storage）│
└────────────┘                                 └─────────────┘
      │                                            │
      │ 2. 后台 Job/Listener 检测“待同步”标记      │
      └─────────────────────────────────▶
                                               ┌────────────┐
                                               │ CloudBase  │
                                               │  数据库    │
                                               └────────────┘

具体实现思路：
1. 前端操作：用户在页面中新增/修改/删除数据时，先将变动写入本地 SQLite 或 Storage，同时在本地记录一条“待同步”队列；
2. 后台同步：监听网络状态，当检测到网络可用时，遍历“待同步”队列，将对应操作（增/改/删）请求发送到云端；
3. 冲突与回滚：若某次同步失败（网络中断、权限过期等），可在下一次网络恢复后重试；若云端发生冲突（如同一条笔记被多人同时编辑），需要设计合并或覆盖策略。

示例代码（伪代码）：

// 本地存储待同步队列
function enqueueSyncTask(task) {
  const queue = uni.getStorageSync('syncQueue') || [];
  queue.push(task);
  uni.setStorageSync('syncQueue', queue);
}

// 添加笔记时
async function addNote(title, content) {
  // 1. 写入本地 SQLite 或 Storage
  const localId = saveNoteLocally(title, content); // 返回本地 ID
  // 2. 记录“待同步”任务
  enqueueSyncTask({ action: 'add', localId, title, content });
}

// 后台监听网络状态
uni.onNetworkStatusChange(async res => {
  if (res.isConnected) {
    const queue = uni.getStorageSync('syncQueue') || [];
    for (let i = 0; i < queue.length; i++) {
      const task = queue[i];
      try {
        if (task.action === 'add') {
          // 发送到云端
          const cloudId = await addNoteToCloud(task.title, task.content);
          // 将本地记录与云端 ID 关联
          bindLocalWithCloud(task.localId, cloudId);
        }
        // 其他 action: 'update', 'delete'
        // 同理处理...
        // 同步成功后，从队列移除
        queue.splice(i, 1);
        i--;
      } catch (e) {
        console.error('同步失败，稍后重试', e);
      }
    }
    uni.setStorageSync('syncQueue', queue);
  }
});

优点：保证离线可用性，提升用户体验；
缺点：开发复杂度较高，需要处理冲突与错误重试；对网络波动敏感，需做好并发控制与节流。

五、数据版本管理与迁移策略

在实际项目迭代中，随着业务需求变化，需要对本地持久化的数据结构进行调整（如新增字段、更改字段格式、拆分表结构等）。如果没有统一的版本管理与迁移机制，可能导致旧版本数据无法正常解析或报错，严重影响用户体验。以下介绍一套较为通用的迁移思路与实践。

5.1 版本号与迁移脚本设计

统一维护一个全局版本号
- 在本地 Storage 中维护一个 DATA_VERSION，用来标识当前数据模型版本。
- 每次发布涉及本地数据结构变更时，需自增 DATA_VERSION，并编写相应的迁移逻辑。
在应用启动时检测并执行迁移
- 在 App.vue 或 main.js 入口文件中，读取本地 DATA_VERSION。
- 如果 localVersion < currentVersion（硬编码或从远端配置获取），则执行对应版本区间的迁移脚本，迁移完成后更新 DATA_VERSION。

图4：数据迁移流程示意

┌──────────────────────────────────────────┐
│        App 启动时检查 localVersion       │
│    ┌─────────────────────────────────┐   │
│    │ localVersion=1, currentVersion=3 │   │
│    └─────────────────────────────────┘   │
│                ↓                       │
│     执行迁移脚本（1→2，2→3）            │
│                ↓                       │
│     迁移完成后：localVersion = 3       │
└──────────────────────────────────────────┘

5.2 示例：从版本 1 → 版本 2 → 版本 3

定义当前版本号（硬编码或配置文件）

// config/version.js
export const CURRENT_DATA_VERSION = 3;

在入口文件执行迁移逻辑

// main.js 或 App.vue 的 onLaunch 钩子
import { CURRENT_DATA_VERSION } from '@/config/version';
import { migrateFrom1To2, migrateFrom2To3 } from '@/utils/migrations';

function runDataMigrations() {
  const localVersion = uni.getStorageSync('DATA_VERSION') || 1;
  // 版本升级路径示例：1 → 2 → 3
  if (localVersion < 2) {
    migrateFrom1To2(); // 包含一系列迁移逻辑
    uni.setStorageSync('DATA_VERSION', 2);
  }
  if (localVersion < 3) {
    migrateFrom2To3();
    uni.setStorageSync('DATA_VERSION', 3);
  }
}

// 应用启动时调用
runDataMigrations();

编写具体迁移脚本

// utils/migrations.js

// 1 → 2：拆分用户信息（原来一个 'user' 对象，拆分为 'userProfile' 与 'userSettings'）
export function migrateFrom1To2() {
  try {
    const rawUser = uni.getStorageSync('user') || null;
    if (rawUser) {
      // 假设旧数据结构：{ id, name, theme, fontSize }
      const userProfile = {
        id: rawUser.id,
        name: rawUser.name
      };
      const userSettings = {
        theme: rawUser.theme,
        fontSize: rawUser.fontSize
      };
      uni.setStorageSync('userProfile', userProfile);
      uni.setStorageSync('userSettings', userSettings);
      uni.removeStorageSync('user');
      console.log('从版本 1 迁移到 2 完成');
    }
  } catch (e) {
    console.error('迁移 1→2 失败', e);
  }
}

// 2 → 3：调整购物车数据格式（从数组改为以商品 ID 为 key 的对象映射，方便快速查重）
export function migrateFrom2To3() {
  try {
    const oldCart = uni.getStorageSync('cart') || [];
    // 旧格式：[{ id, name, price, quantity }, ...]
    const newCartMap = {};
    oldCart.forEach(item => {
      newCartMap[item.id] = {
        name: item.name,
        price: item.price,
        quantity: item.quantity
      };
    });
    uni.setStorageSync('cartMap', newCartMap);
    uni.removeStorageSync('cart');
    console.log('从版本 2 迁移到 3 完成');
  } catch (e) {
    console.error('迁移 2→3 失败', e);
  }
}

说明：migrateFrom1To2 将旧版 user 对象拆分为两个存储键；migrateFrom2To3 将购物车数组改为对象映射以提升查找、更新效率。
优点：每次版本升级针对性地对旧数据进行转化，保证应用继续可用且数据模型始终与代码逻辑保持一致。
注意：对于数据量庞大的迁移操作，可能导致首次升级出现明显卡顿，可考虑在离屏（Splash 页面或“升级提示”页面）中分批迁移，并使用 Progress 反馈给用户。

六、安全性（加密、签名、校验）与异常容错

在存储敏感信息（如用户凭证、个人隐私数据）时，仅依赖本地 Storage 并不安全，容易被用户或恶意应用篡改、窃取。以下介绍常见的加密与校验思路，以及异常情况下的降级与容错策略。

6.1 数据加密与签名

对敏感字段进行对称加密

使用 AES、DES、SM4 等对称加密算法，将敏感信息（如 Token、手机号等）加密后再存储。
在读回时再解密使用。示例采用 crypto-js 库（需先安装 npm install crypto-js）：

// utils/crypto.js
import CryptoJS from 'crypto-js';

const SECRET_KEY = 'my_secret_key_123'; // 32 位长度，可更换成你的密钥

export function encryptData(data) {
  const plainText = typeof data === 'string' ? data : JSON.stringify(data);
  return CryptoJS.AES.encrypt(plainText, SECRET_KEY).toString();
}

export function decryptData(cipherText) {
  try {
    const bytes = CryptoJS.AES.decrypt(cipherText, SECRET_KEY);
    const decrypted = bytes.toString(CryptoJS.enc.Utf8);
    try {
      return JSON.parse(decrypted);
    } catch {
      return decrypted;
    }
  } catch (e) {
    console.error('解密失败', e);
    return null;
  }
}

示例：保存加密后的 Token

import { encryptData, decryptData } from '@/utils/crypto';

export function saveEncryptedToken(token) {
  const cipher = encryptData(token);
  uni.setStorageSync('encryptedToken', cipher);
}

export function getEncryptedToken() {
  const cipher = uni.getStorageSync('encryptedToken');
  if (!cipher) return '';
  return decryptData(cipher) || '';
}

优点：即使用户通过调试工具查看本地 Storage，也只能看到已经加密的密文，降低敏感数据泄露风险。
缺点：前端加密密钥一旦被泄露，安全性大打折扣；且加密/解密增加了额外的 CPU 及算法复杂度。

数据签名校验

对存储关键数据添加签名字段，使用 HMAC-SHA256 等算法防篡改，即“只读”不能“写入”。但由于前端是打开环境，恶意用户仍然可能直接修改签名；该方式只能抵御一般误操作，无法抵御恶意篡改。

import CryptoJS from 'crypto-js';

const HMAC_SECRET = 'another_secret_key';

// 存储带签名的数据
export function saveWithSignature(key, data) {
  const jsonString = JSON.stringify(data);
  const signature = CryptoJS.HmacSHA256(jsonString, HMAC_SECRET).toString();
  uni.setStorageSync(key, JSON.stringify({ payload: data, sign: signature }));
}

// 读取并校验签名
export function getWithSignature(key) {
  const raw = uni.getStorageSync(key);
  if (!raw) return null;
  try {
    const { payload, sign } = JSON.parse(raw);
    const expectedSign = CryptoJS.HmacSHA256(JSON.stringify(payload), HMAC_SECRET).toString();
    if (sign !== expectedSign) {
      console.warn('数据签名校验失败，可能被篡改');
      return null;
    }
    return payload;
  } catch (e) {
    console.error('解析或校验异常', e);
    return null;
  }
}

注意：前端密钥同样可被逆向分析出，无法做到高安全级别加密；仅适用于对“误操作范畴”的防护。

6.2 容错与降级

写入失败重试

在 uni.setStorage 报错（如容量不足）时，可提示用户清理缓存或自动删除最老的缓存数据，再次尝试写入。
示例：当缓存列表数据过大导致写入失败时，主动删除最旧的一页数据后重试：

function safeSetStorage(key, data, maxRetries = 2) {
  try {
    uni.setStorageSync(key, data);
  } catch (e) {
    console.warn('首次写入失败，尝试清理旧缓存重试', e);
    if (key === 'goodsCache' && maxRetries > 0) {
      // 假设 data 为列表缓存，删除最旧一页后重试
      const list = data.list || [];
      const pageSize = data.pageSize || 20;
      if (list.length > pageSize) {
        const trimmedList = list.slice(pageSize);
        safeSetStorage('goodsCache', { ...data, list: trimmedList }, maxRetries - 1);
      } else {
        uni.removeStorageSync(key);
        console.warn('缓存已清空，写入新数据');
        uni.setStorageSync(key, { ...data, list: [] });
      }
    } else {
      console.error('无法处理的写入失败', e);
    }
  }
}

失效/过期机制

对于临时缓存（如验证码、临时表单数据），建议加上时间戳，定期检查并清理过期数据，避免老旧数据长期占用容量。
示例：

// 缓存示例：存储带过期时间的验证码
function saveTempCaptcha(key, code, ttl = 5 * 60 * 1000) {
  const expireAt = Date.now() + ttl;
  uni.setStorageSync(key, { code, expireAt });
}

function getTempCaptcha(key) {
  const data = uni.getStorageSync(key);
  if (!data) return null;
  if (Date.now() > data.expireAt) {
    uni.removeStorageSync(key);
    return null;
  }
  return data.code;
}

说明：当调用 getTempCaptcha 时，如果本地数据已过期则自动清理并返回 null，保证后续业务不会误用过期验证码。

异常回退逻辑

在业务中，若读取本地数据失败（如格式错误、缺失字段），需要设计合理的回退方案，比如恢复到默认值、强制登出、重新拉取远程数据等。
示例：读取用户信息时，若解析失败则清除本地并重新走登录流程：

function safeGetUserInfo() {
  try {
    const cipher = uni.getStorageSync('encryptedUser');
    if (!cipher) return null;
    const user = decryptData(cipher);
    if (!user || !user.id) throw new Error('数据结构异常');
    return user;
  } catch (e) {
    console.error('解析用户信息失败，清除本地数据并重定向登录', e);
    uni.removeStorageSync('encryptedUser');
    uni.reLaunch({ url: '/pages/login/login' });
    return null;
  }
}

七、最佳实践总结

结合以上各章内容，以下整理一份“uniapp 小程序数据持久化”的最佳实践要点，供开发者在项目中参考和落地。

优先使用原生 Storage API，合理选择同步/异步接口
- 若数据量小且时序需在一行代码后立即获取，使用 uni.setStorageSync / uni.getStorageSync；
- 若数据量较大或可异步处理，使用 uni.setStorage / uni.getStorage，避免阻塞主线程。
对大数据量或复杂查询场景，考虑 SQLite 或 IndexedDB（仅 H5）
- 在 App/H5 端引入 SQLite 插件，避免 Key-Value 存储的性能瓶颈；
- 小程序端若需缓存海量离线数据，可通过小程序云数据库或服务端接口辅助。
集中式状态管理需配合持久化插件
- 对于 Vuex/Pinia 管理的全局状态，使用 vuex-persistedstate / pinia-plugin-persistedstate 实现自动同步；
- 严格筛选需要持久化的字段，避免一次性序列化过大对象。
编写数据迁移脚本，维护数据结构版本
- 在本地 Storage 中维护 DATA_VERSION，在应用启动时自动执行对应版本区间的迁移逻辑；
- 对于离线升级耗时较长时，可展示“升级中”提示并分批迁移，避免用户长时间等待。
安全拼装：加密与签名
- 对敏感数据（Token、用户隐私）进行 AES 加密，再存储到本地；
- 可对关键数据附加 HMAC-SHA256 签名，防止误操作或简单篡改；
- 但注意：前端密钥易泄露，勿在前端存放过于敏感信息。
失效与容错机制
- 对临时数据设置过期时间，并在读取时自动清理；
- 监听 uni.setStorage 写入失败，采用“清理最旧数据并重试”策略；
- 读取本地数据时加上数据合法性校验，若异常则执行回退逻辑（如清空、重新登录、重新拉取远程数据）。
云端同步思路：本地先写 + 后台异步同步
- 离线时将“增/改/删”操作缓存到本地“待同步”队列，网络恢复后再批量同步到云端；
- 设计合理的冲突解决策略（覆盖、合并、用户选择）及重试机制，保证数据一致性。
定期清理与压缩
- 对长期不再使用的数据（如旧分页缓存、过期日志）定时清理；
- 对大 JSON（如列表缓存）进行压缩（如 LZString、gzip），减少本地存储占用；
- 可将频繁更新的本地数据定期写入 SQLite 或云端，减轻 Key-Value 写压力。
监控与日志
- 在开发阶段，通过微信开发者工具、Chrome DevTools 等调试工具查看本地 Storage 使用情况；
- 在生产环境集成监控 SDK（如友盟+、腾讯云 TMonitor），定期上报本地存储使用情况与异常失败次数，提前预警。
详细文档与注释
- 对项目中所有关键存储键（Key 名称）进行统一管理（如在 constants/storage.js 中定义）；
- 每个 Key 的用途、存储格式、加密方式、版本信息等在文档中描述清楚，后续维护时更易理解与扩展。

八、示例项目结构与参考代码

为帮助你快速在项目中套用以上最佳实践，下面给出一个示例项目的简化目录结构，以及部分核心代码示例。

my-uniapp-project/
├─ pages/
│  ├─ index/
│  │    ├─ index.vue
│  │    └─ index.js
│  ├─ login/
│  │    ├─ login.vue
│  │    └─ login.js
│  └─ notes/
│       ├─ notes.vue
│       └─ notes.js
├─ store/
│  ├─ index.js            // Vuex 或 Pinia 配置
│  ├─ modules/
│  │    ├─ user.js        // user store
│  │    ├─ settings.js    // settings store
│  │    └─ cart.js        // cart store
│  └─ plugins/
│       ├─ vuex-persist.js  // 持久化插件封装
│       └─ pinia-persist.js
├─ utils/
│  ├─ storage.js          // 封装 uni.setStorage、加锁、分片等
│  ├─ crypto.js           // 数据加密解密
│  ├─ migrations.js       // 数据迁移脚本
│  └─ syncQueue.js        // 同步队列示例
├─ config/
│  └─ version.js          // 数据版本号
├─ plugins/
│  └─ sqlite.js           // SQLite 封装（App 端）
├─ main.js                // 入口：执行 runDataMigrations、初始化 store、云开发等
├─ App.vue
├─ manifest.json
└─ pages.json

pages/index/index.vue：在 onLoad 时调用 safeGetUserInfo() 检查登录态，若无则跳转到 pages/login/login.vue；若有则正常进入主页面。
pages/login/login.vue：登录完成后调用 saveEncryptedToken(token) 与 userStore.setUser(user)。
pages/notes/notes.vue：展示本地与云端同步的笔记列表，支持离线新增并写入“待同步队列”，网络恢复时自动推送到云端。
utils/storage.js：对 uni.setStorage / uni.getStorage 进行统一封装，加入异常重试、分片存储、统一 Key 管理等逻辑。
utils/migrations.js：包含从版本 1→2→3 的数据结构转换脚本，确保升级后旧用户数据可用。
store/plugins/vuex-persist.js：基于 vuex-persistedstate 对 uni.setStorageSync / uni.getStorageSync 做兼容封装。
plugins/sqlite.js：App 端或 H5 端使用 SQLite 存储海量笔记。

九、总结

本文从本地存储基础出发，逐步扩展到插件化数据库、集中式状态持久化及云端同步，并结合 数据版本迁移、安全加密、容错回退 等高级话题，系统性地讲解了 uniapp 小程序中数据持久化的各类场景与实践方案。最后给出了一份简化的示例项目结构，帮助你快速在真实项目中落地。

无论是小而全局的键值存储，还是大而复杂的离线数据库，抑或多端同步与版本迁移，只要遵循“统一 Key 管理、分层存储设计、容错与安全优先、持续监控”的原则，你就能在项目中构建一套高效、可靠、安全的持久化方案，显著提升应用的可用性与用户体验。