Uniapp本地存儲（uni.setStorage）全面解析與實踐指南

在移動應用開發中，本地存儲是不可或缺的核心功能之一。作為跨平臺開發框架，Uniapp提供了一套完善的本地存儲解決方案，使開發者能夠輕松實現數據的持久化存儲。本文將深入探討Uniapp本地存儲的方方面面，從基礎使用到高級技巧，幫助你在實際項目中高效利用這一功能。

一、本地存儲的重要性與Uniapp實現

1.1 為什么需要本地存儲？

在應用開發中，本地存儲解決了幾個關鍵問題：

數據持久化：關閉應用后數據不會丟失
離線訪問：無網絡時仍能獲取關鍵數據
性能優化：減少網絡請求，提升用戶體驗
狀態保持：記住用戶偏好和登錄狀態

1.2 Uniapp本地存儲的特點

Uniapp的本地存儲系統具有以下優勢：

跨平臺一致性：一套API在所有平臺（H5、小程序、App等）上表現一致
容量更大：相比瀏覽器localStorage的5MB限制，Uniapp存儲空間更大
數據類型豐富：支持存儲對象、數組等復雜數據結構
同步/異步雙模式：滿足不同場景需求

二、Uniapp本地存儲核心API詳解

2.1 存儲數據

異步存儲（推薦在需要處理回調時使用）

uni.setStorage({key: 'user_profile',  // 存儲鍵名data: {              // 存儲數據（支持多種類型）name: '李四',age: 28,preferences: {theme: 'dark',fontSize: 14}},success: () => {console.log('數據存儲成功');uni.showToast({ title: '保存成功', icon: 'success' });},fail: (err) => {console.error('存儲失敗:', err);uni.showToast({ title: '保存失敗', icon: 'none' });}
});

同步存儲（適合簡單場景）

try {const settings = {notification: true,vibration: false,language: 'zh-CN'};uni.setStorageSync('app_settings', settings);
} catch (e) {console.error('同步存儲失敗:', e);
}

2.2 獲取數據

異步獲取

uni.getStorage({key: 'user_profile',success: (res) => {console.log('獲取到的數據:', res.data);this.userInfo = res.data;  // 在Vue中綁定到data},fail: (err) => {console.error('數據獲取失敗:', err);}
});

同步獲取

try {const settings = uni.getStorageSync('app_settings');if (settings) {this.notification = settings.notification;// 其他賦值操作...}
} catch (e) {console.error('同步獲取失敗:', e);
}

2.3 刪除數據

異步刪除

uni.removeStorage({key: 'temp_data',success: () => {console.log('數據刪除成功');}
});

同步刪除

try {uni.removeStorageSync('outdated_cache');
} catch (e) {console.error('刪除失敗:', e);
}

2.4 清空存儲

// 異步清空（無回調）
uni.clearStorage();// 同步清空
uni.clearStorageSync();// 實際項目中通常會添加確認提示
function clearAllStorage() {uni.showModal({title: '警告',content: '確定要清除所有本地數據嗎？此操作不可撤銷！',success: (res) => {if (res.confirm) {uni.clearStorageSync();uni.showToast({ title: '已清除所有數據', icon: 'success' });}}});
}

三、高級應用技巧

3.1 存儲加密

對于敏感信息（如token、用戶憑證等），建議先加密再存儲：

import CryptoJS from 'crypto-js';const SECRET_KEY = 'your-secret-key-123';// 加密存儲
function setEncryptedStorage(key, data) {try {const encrypted = CryptoJS.AES.encrypt(JSON.stringify(data), SECRET_KEY).toString();uni.setStorageSync(key, encrypted);return true;} catch (e) {console.error('加密存儲失敗:', e);return false;}
}// 解密獲取
function getDecryptedStorage(key) {try {const encrypted = uni.getStorageSync(key);if (!encrypted) return null;const bytes = CryptoJS.AES.decrypt(encrypted, SECRET_KEY);return JSON.parse(bytes.toString(CryptoJS.enc.Utf8));} catch (e) {console.error('解密失敗:', e);return null;}
}

3.2 存儲過期策略

實現自動過期的存儲機制：

// 帶過期時間的存儲
function setStorageWithExpiry(key, value, expiryDays) {const now = new Date();const item = {value: value,expiry: now.getTime() + (expiryDays * 24 * 60 * 60 * 1000)};uni.setStorageSync(key, item);
}// 獲取并檢查過期
function getStorageWithExpiry(key) {const item = uni.getStorageSync(key);if (!item) return null;const now = new Date();if (now.getTime() > item.expiry) {uni.removeStorageSync(key);return null;}return item.value;
}// 使用示例
setStorageWithExpiry('api_cache', apiResponse, 7); // 保存7天
const cachedData = getStorageWithExpiry('api_cache');

3.3 存儲空間管理

// 估算已用存儲空間
function getStorageSize() {let total = 0;const keys = uni.getStorageInfoSync().keys;keys.forEach(key => {const item = uni.getStorageSync(key);total += JSON.stringify(item).length;});return (total / 1024).toFixed(2) + 'KB';
}// 清理最早存儲的X條記錄
function cleanupOldestItems(limit) {const keys = uni.getStorageInfoSync().keys;if (keys.length <= limit) return;// 按時間排序（需要存儲時記錄時間戳）const sortedKeys = keys.map(key => {return {key,time: uni.getStorageSync(key)._timestamp || 0};}).sort((a, b) => a.time - b.time);// 刪除最早的for (let i = 0; i < sortedKeys.length - limit; i++) {uni.removeStorageSync(sortedKeys[i].key);}
}

四、性能優化與最佳實踐

4.1 存儲性能優化

合理分塊：大數據拆分成多個key存儲

// 存儲大型數組
function saveLargeArray(key, array, chunkSize = 100) {for (let i = 0; i < array.length; i += chunkSize) {const chunk = array.slice(i, i + chunkSize);uni.setStorageSync(`${key}_chunk_${i/chunkSize}`, chunk);}
}

避免頻繁操作：合并多次存儲為單次操作
使用索引：對大量數據建立索引提高查詢效率

4.2 最佳實踐

鍵名命名規范

// 推薦使用有意義的命名空間
const STORAGE_KEYS = {USER_INFO: 'app:user:info',SETTINGS: 'app:global:settings',CACHE_PREFIX: 'cache:'
};

類型安全封裝

class TypedStorage {constructor(key, defaultValue, type) {this.key = key;this.default = defaultValue;this.type = type;}get() {const value = uni.getStorageSync(this.key);if (value === null || value === undefined) return this.default;if (typeof value !== this.type) return this.default;return value;}set(value) {if (typeof value !== this.type) {console.warn(`Invalid type for ${this.key}, expected ${this.type}`);return;}uni.setStorageSync(this.key, value);}
}// 使用示例
const darkMode = new TypedStorage('dark_mode', false, 'boolean');

錯誤處理策略

function safeGetStorage(key, defaultValue) {try {const value = uni.getStorageSync(key);return value !== undefined ? value : defaultValue;} catch (e) {console.error(`獲取${key}失敗:`, e);return defaultValue;}
}

五、跨平臺注意事項

平臺差異處理

function setCrossPlatformStorage(key, value) {// 小程序端有10MB限制if (process.env.UNI_PLATFORM === 'mp-weixin') {if (JSON.stringify(value).length > 8 * 1024 * 1024) {console.warn('數據大小接近小程序限制');}}uni.setStorageSync(key, value);
}

兼容性檢查

function checkStorageAvailable() {try {const testKey = '__storage_test__';uni.setStorageSync(testKey, testKey);uni.removeStorageSync(testKey);return true;} catch (e) {return false;}
}

六、實際應用場景

6.1 用戶登錄狀態維護

// 登錄成功后
function handleLoginSuccess(userData, token) {const authData = {user: userData,token: token,lastLogin: new Date().getTime()};uni.setStorageSync('auth', authData);this.$store.commit('setAuth', authData); // 同步到Vuex
}// 檢查登錄狀態
function checkAuth() {const auth = uni.getStorageSync('auth');if (!auth || !auth.token) return false;// 檢查token是否過期（假設有效期7天）const sevenDays = 7 * 24 * 60 * 60 * 1000;if (new Date().getTime() - auth.lastLogin > sevenDays) {uni.removeStorageSync('auth');return false;}return true;
}

6.2 應用設置持久化

// 設置管理器
const appSettings = {defaults: {theme: 'light',fontSize: 16,notifications: true},init() {const saved = uni.getStorageSync('settings') || {};return { ...this.defaults, ...saved };},save(currentSettings) {uni.setStorageSync('settings', currentSettings);},reset() {uni.setStorageSync('settings', this.defaults);}
};// 在Vue中使用
export default {data() {return {settings: appSettings.init()};},watch: {settings: {deep: true,handler(newVal) {appSettings.save(newVal);}}}
}

6.3 列表數據緩存

// 帶緩存的數據加載
async function loadDataWithCache(listType, forceRefresh = false) {const cacheKey = `list_cache_${listType}`;if (!forceRefresh) {const cached = uni.getStorageSync(cacheKey);if (cached) {const { data, timestamp } = cached;// 1小時內使用緩存if (Date.now() - timestamp < 3600000) {return data;}}}// 獲取新數據const freshData = await fetchNewData(listType);uni.setStorageSync(cacheKey, {data: freshData,timestamp: Date.now()});return freshData;
}