萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> Android 開發

HTML5 LocalStorage 完整指南:特性、限制、封裝最佳實務與避坑

前言

localStorage 提供簡單的鍵值持久化儲存 (同源、同瀏覽器),容量約 5MB,不隨 HTTP 請求發送。本文深入解析特性、與 sessionStorage/cookie 差異、序列化策略、配額管理、隱私模式限制與生產級封裝庫設計。

核心特性對照

特性localStoragesessionStorageCookie
生命週期永久 (手動清除/清除瀏覽資料才消失)分頁/視窗關閉即銷毀可設定 Expires/Max-Age
容量~5 MB (各瀏覽器略異)~5 MB4 KB / 個,每域 ~300 個
網路傳輸**從不**隨請求發送不發送**每請求自動攜帶**
同源策略嚴格 (scheme+host+port)嚴格 + 同分頁可設 Domain/Path 放寬
資料型別字串 (需自行序列化)字串字串
事件通知storage 事件 (跨分頁同步)無無

基本 API

localStorage.setItem('key', 'value');
const val = localStorage.getItem('key'); // null 若不存在
localStorage.removeItem('key');
localStorage.clear(); // 清空該源所有鍵
const len = localStorage.length;
const key = localStorage.key(index); // 遍歷用

序列化策略

// 通用 JSON 封裝
const Storage = {
  set(key, value) {
    try { localStorage.setItem(key, JSON.stringify(value)); }
    catch (e) { if (e.name === 'QuotaExceededError') handleQuota(); }
  },
  get(key, defaultValue = null) {
    const raw = localStorage.getItem(key);
    if (raw === null) return defaultValue;
    try { return JSON.parse(raw); }
    catch { return defaultValue; } // 防禦性:損壞資料回預設
  },
  remove(key) { localStorage.removeItem(key); },
  clear() { localStorage.clear(); }
};

// 使用
Storage.set('user', { id: 1, name: 'Alice', tags: ['vip','beta'] });
const user = Storage.get('user', { id: 0, name: 'Guest', tags: [] });

進階主題

1. 配額管理與 QuotaExceededError

  • 寫入超過配額拋出 QuotaExceededError (Safari 私有模式下寫入也會拋出)。
  • 策略:捕獲錯誤 → 清理舊/低優先級快取 → 重試一次 → 仍失敗則降級 (僅記憶體快取/上傳伺服器)。
  • 可用 navigator.storage.estimate() (Storage API) 查詢剩餘配額。

2. 隱私/無痕模式限制

  • Safari (iOS/macOS) 私密模式:**完全禁用 localStorage/setItem 拋錯**。
  • Chrome/Edge/Firefox 隱私模式:正常運作,但關閉視窗即清除 (行為同 sessionStorage)。
  • **對策**:try { localStorage.setItem('test','1'); localStorage.removeItem('test'); } catch { /* 降級 */ } 偵測可用性。

3. 跨分頁同步 (storage 事件)

window.addEventListener('storage', e => {
  if (e.key === 'auth_token' && e.newValue !== e.oldValue) {
    // 另一分頁更新了 token,當前分頁同步刷新狀態
    authStore.updateToken(e.newValue);
  }
});

注意:storage 事件**不在發出分頁觸發**,僅在其他同源分頁觸發。

4. 效能陷阱

  • 同步阻塞:所有 API 同步執行,大量寫入會卡主執行緒。
  • Firefox 啟動時一次性將整個 localStorage 讀入記憶體,資料過大 (接近 5MB) 會明顯延遲啟動。
  • **對策**:分批寫入 (requestIdleCallback)、關鍵路徑改用 IndexedDB (非同步)、定期清理過期鍵。

生產級封裝庫設計要點 (TypeScript)

interface StorageOptions {
  prefix?: string;           // 鍵名前綴避免衝突
  serializer?: (v: any) => string;
  deserializer?: (s: string) => any;
  ttl?: number;              // 毫秒,過期自動失效
  encrypt?: (s: string) => string; // 可選加密
  decrypt?: (s: string) => string;
}

function createStorage(localStorage: Storage, opts: StorageOptions = {}) {
  const { prefix = '', serializer = JSON.stringify, deserializer = JSON.parse, ttl, encrypt, decrypt } = opts;
  const now = () => Date.now();

  return {
    set(key: string, value: any) {
      const payload = { value, timestamp: now() };
      let data = serializer(payload);
      if (encrypt) data = encrypt(data);
      localStorage.setItem(prefix + key, data);
    },
    get(key: string) {
      const raw = localStorage.getItem(prefix + key);
      if (!raw) return null;
      let data = decrypt ? decrypt(raw) : raw;
      try {
        const { value, timestamp } = deserializer(data);
        if (ttl && now() - timestamp > ttl) { this.remove(key); return null; }
        return value;
      } catch { return null; }
    },
    remove(key) { localStorage.removeItem(prefix + key); },
    clear() { /* 只清除帶 prefix 的鍵 */ },
    keys() { /* 遍歷並過濾 prefix */ }
  };
}

// 使用
const appStore = createStorage(localStorage, { prefix: 'myapp:', ttl: 7*24*3600*1000 });
appStore.set('session', { token: 'abc', expires: Date.now()+3600*1000 });

避坑清單

  1. ❌ 直接存物件 localStorage.setItem('k', {a:1}) → 變成 "[object Object]"。
  2. ❌ 忽略 QuotaExceededError 導致靜默失敗。
  3. ❌ 敏感資訊 (Token、PII) 明文存放。
  4. ❌ 當作主要資料庫 (無索引、無查詢、無事務、5MB 上限)。
  5. ❌ 未處理隱私模式不可用情況。
  6. ✅ 統一封裝、加前綴、TTL、序列化/反序列化防禦、配額降級、跨分頁同步。

LocalStorage 適合「小量、非關鍵、需跨分頁同步」的持久化場景;複雜查詢、大資料、離線優先請改用 IndexedDB / OPFS / SQLite (WASM)。

copyright © 萬盛學電腦網 all rights reserved