解决JavaScript读写LocalStorage时的容量限制与异常处理

一、LocalStorage 容量限制与 QuotaExceededError 触发机制

现代主流浏览器（如 Chrome、Firefox、Safari、Edge）为每个源（Origin，由协议、域名与端口组成）分配的 LocalStorage 存储上限通常设定为 5MB 左右。当尝试存入的数据超出可用额度时，浏览器会直接抛出类型为 QuotaExceededError 的 DOMException 异常。

需要明确的是，LocalStorage 存储的所有键与值在规范中均被要求转换为 UTF-16 编码的 DOMString。在 JavaScript 引擎中，每个 UTF-16 码元通常占用 2 个字节。这意味着 5MB 的存储上限，在存储纯 ASCII 字符时大约对应 500 万个字符，但在包含大量多字节字符（如中文字符或高区 Unicode 符号）时，字符数将成倍缩水。

图 1：LocalStorage 容量边界分布与配额异常抛出机制

除了容量占满，LocalStorage 还存在其他不可忽视的异常场景：

• 隐私与无痕浏览模式限制：在旧版本 iOS/Safari 的无痕模式下，localStorage.setItem 会直接无条件抛出 QuotaExceededError（配额被设为 0 字节）；部分配置了严格安全策略的环境甚至在访问 window.localStorage 属性本身时就会抛出 SecurityError。
• 第三方 Cookie/存储禁用：当用户在浏览器设置中禁止第三方 Cookie 或网站数据时，嵌入在 iframe 中的应用调用 LocalStorage API 会直接报错。
• 序列化循环引用：使用 JSON.stringify() 序列化复杂对象时，如果对象包含循环引用或 BigInt 等特殊类型，会在写入前抛出常规的 TypeError。

二、捕获与识别异常：区分容量超出与权限受限

为了避免页面崩溃，所有写入操作必须置于 try...catch 块中进行防御。但在实际异常处理中，不能简单将所有错误归结为“容量满了”，必须准确判断异常的名称（e.name）或历史状态码（e.code）。

图 2：LocalStorage 安全写入流程与异常分支分流图

在不同浏览器中，配额超限错误的表示方式存在细微差异。以下是标准的异常识别辅助函数：

/**
 * 校验错误对象是否为配额超出异常 (QuotaExceededError)
 * @param {Error|DOMException} e 捕获的异常对象
 * @returns {boolean}
 */
function isQuotaExceededError(e) {
  if (!e) return false;
  return (
    // 标准现代浏览器 (Chrome, Safari, Edge)
    e.name === 'QuotaExceededError' ||
    // Firefox 兼容识别
    e.name === 'NS_ERROR_DOM_QUOTA_REACHED' ||
    // 历史版本 W3C 规范错误码 22
    e.code === 22 ||
    // Firefox 早期错误码 1014
    e.code === 1014 ||
    // 旧版 WebKit 额外属性
    (e.number & 0xFFFF) === 22
  );
}

三、应对容量限制的四大实用方案

面对 5MB 的硬性瓶颈，单纯等待报错并捕获是不够的。我们需要从架构与数据处理层面主动控制体积，或建立自愈与替代机制。

图 3：前端主流本地存储技术与扩容方案多维对比

1. 引入 TTL 过期时间与 LRU（最近最少使用）自动淘汰

原生 LocalStorage 没有过期机制，历史数据会永久滞留在用户浏览器中，直到触发配额上限。通过为每个数据项添加包含 createTime、expireTime 和 lastAccessTime 的包装元数据，当发生 QuotaExceededError 时，可以自动执行以下清理逻辑：

1. 遍历当前命名空间下的所有键，对比当前时间戳，删除所有已过期的废弃键；
2. 若清理过期键后空间仍然不足，根据 lastAccessTime 从旧到新对所有键进行排序，剔除最久未被访问的条目；
3. 腾出空间后，重新尝试执行当前的写入操作。

2. 使用 LZ-String 对大体积文本进行压缩

许多保存在 LocalStorage 中的数据是高度结构化的 JSON 字符串或长文本（如复杂表单草稿）。由于包含大量重复的键名和格式字符，LZ 压缩算法（如社区成熟的 lz-string 库）通常能实现 50% 至 80% 的体积压缩率。

该方案的优势在于完全无需更改底层存储媒介，直接将等效存储容量扩充到 10MB~20MB。不过，压缩与解压属于 CPU 密集型操作，对于体积特别大的字符串，频繁压缩会短暂阻塞主线程，因此建议仅在内容超过特定阈值（例如 20KB）时才开启压缩。

3. 降级与切换：IndexedDB 与内存存储（Memory Fallback）

当数据规模确定会达到数兆字节以上，或者运行在严格限制存储的环境中时，LocalStorage 不再是合适的目标容器。此时应建立多级降级防线：

• 生产级主存储替代（IndexedDB）：现代浏览器提供了容量巨大（通常可达磁盘剩余空间的 20%~50%）、支持异步且支持存储原生 Blob 和结构化对象的 IndexedDB。通过 localforage 或 idb-keyval 库，可以用类似于 LocalStorage 的简洁 Promise 语法操作海量数据。
• 环境受限保活（Memory Fallback）：在无痕模式或隐私被禁用的极端情况下，使用内存中的 Map 模拟 Storage 接口。虽然页面刷新后数据会重置，但能确保当前会话的单页应用（SPA）所有功能正常运转，彻底避免抛出未捕获异常。

四、生产级安全存储包装库实战

结合上述策略，我们编写一个包含命名空间隔离、过期自动失效、QuotaExceededError 自动淘汰、内存降级兜底的完整工具类 SafeStorage：

/**
 * 生产级安全本地存储封装
 */
class SafeStorage {
  /**
   * @param {Object} options 配置项
   * @param {string} options.prefix 存储键前缀，用于隔离不同模块
   * @param {Storage} [options.storage] 存储后端，默认 window.localStorage
   */
  constructor(options = {}) {
    this.prefix = options.prefix || 'app_cache_';
    this.memoryMap = new Map();
    this.isStorageAvailable = this._checkAvailability(options.storage || window.localStorage);
    this.storage = this.isStorageAvailable ? (options.storage || window.localStorage) : null;
  }

  /**
   * 检测环境是否支持并允许使用存储后端
   */
  _checkAvailability(storage) {
    try {
      if (!storage) return false;
      const testKey = `__test_${Date.now()}__`;
      storage.setItem(testKey, '1');
      storage.removeItem(testKey);
      return true;
    } catch (e) {
      console.warn('[SafeStorage] 本地存储不可用，已自动平滑降级为内存模式。', e);
      return false;
    }
  }

  _getKey(key) {
    return `${this.prefix}${key}`;
  }

  /**
   * 写入数据项
   * @param {string} key 键名
   * @param {*} value 数据实体（支持对象、数组、基础类型）
   * @param {number} [ttl] 有效时长（毫秒），不传则永不过期
   * @returns {boolean} 是否保存成功
   */
  setItem(key, value, ttl = null) {
    const fullKey = this._getKey(key);
    const envelope = {
      val: value,
      cTime: Date.now(),
      aTime: Date.now(),
      exp: ttl ? Date.now() + ttl : null
    };

    let serialized;
    try {
      serialized = JSON.stringify(envelope);
    } catch (e) {
      console.error(`[SafeStorage] 序列化失败，请检查是否存在循环引用：${key}`, e);
      return false;
    }

    // 内存降级通道
    if (!this.isStorageAvailable) {
      this.memoryMap.set(fullKey, serialized);
      return true;
    }

    try {
      this.storage.setItem(fullKey, serialized);
      return true;
    } catch (err) {
      if (this._isQuotaExceeded(err)) {
        console.warn(`[SafeStorage] 触发容量配额溢出，启动 LRU 自动清理自愈机制：${key}`);
        const freed = this._autoEvict();
        if (freed) {
          try {
            this.storage.setItem(fullKey, serialized);
            return true;
          } catch (retryErr) {
            console.error('[SafeStorage] 清理后重试仍超出容量，写入内存兜底。', retryErr);
          }
        }
      }
      // 终极兜底：写进内存 Map，确保当前会话逻辑不崩溃
      this.memoryMap.set(fullKey, serialized);
      return false;
    }
  }

  /**
   * 读取数据项
   * @param {string} key 键名
   * @param {*} [defaultValue] 默认值
   * @returns {*}
   */
  getItem(key, defaultValue = null) {
    const fullKey = this._getKey(key);
    let serialized = null;

    if (this.isStorageAvailable) {
      try {
        serialized = this.storage.getItem(fullKey);
      } catch (e) {
        serialized = this.memoryMap.get(fullKey);
      }
    } else {
      serialized = this.memoryMap.get(fullKey);
    }

    if (!serialized) return defaultValue;

    try {
      const envelope = JSON.parse(serialized);

      // 过期判定
      if (envelope.exp && Date.now() > envelope.exp) {
        this.removeItem(key);
        return defaultValue;
      }

      // 更新最后访问时间（用于 LRU）
      envelope.aTime = Date.now();
      if (this.isStorageAvailable) {
        try {
          this.storage.setItem(fullKey, JSON.stringify(envelope));
        } catch (_) {}
      }

      return envelope.val;
    } catch (e) {
      return defaultValue;
    }
  }

  /**
   * 删除数据项
   */
  removeItem(key) {
    const fullKey = this._getKey(key);
    if (this.isStorageAvailable) {
      try {
        this.storage.removeItem(fullKey);
      } catch (_) {}
    }
    this.memoryMap.delete(fullKey);
  }

  /**
   * 判定配额超限
   */
  _isQuotaExceeded(e) {
    return (
      e &&
      (e.name === 'QuotaExceededError' ||
        e.name === 'NS_ERROR_DOM_QUOTA_REACHED' ||
        e.code === 22 ||
        e.code === 1014)
    );
  }

  /**
   * 自动清理过期与最久未访问条目 (LRU)
   */
  _autoEvict() {
    if (!this.isStorageAvailable) return false;
    const candidates = [];
    const now = Date.now();

    // 收集所有带该前缀的键
    for (let i = 0; i < this.storage.length; i++) {
      const k = this.storage.key(i);
      if (k && k.startsWith(this.prefix)) {
        try {
          const item = JSON.parse(this.storage.getItem(k));
          // 如果已过期，立即就地删除
          if (item.exp && now > item.exp) {
            this.storage.removeItem(k);
            continue;
          }
          candidates.push({ key: k, aTime: item.aTime || item.cTime || 0 });
        } catch (_) {
          // 格式损坏的直接淘汰
          this.storage.removeItem(k);
        }
      }
    }

    // 按最后访问时间升序排列（最老的排在最前面）
    candidates.sort((a, b) => a.aTime - b.aTime);

    // 剔除前 25% 最久未使用的缓存项
    const evictCount = Math.max(1, Math.ceil(candidates.length * 0.25));
    for (let i = 0; i < evictCount && i < candidates.length; i++) {
      this.storage.removeItem(candidates[i].key);
    }

    return true;
  }
}

// 导出全局单例
const safeStorage = new SafeStorage({ prefix: 'portal_v1_' });

五、全生命周期决策架构与工程化落地

在实际企业级应用构建中，针对不同体积、更新频率与生命周期的业务数据，应当建立清晰的存储决策矩阵。不要将所有状态盲目塞入 LocalStorage。

图 4：前端本地存储分级容灾与生命周期决策全景

六、最佳实践建议

1. 命名空间（Namespace）隔离：在所有键名前增加统一的应用或模块前缀（如 app_auth_token）。在执行清理和遍历时，只删除属于自己模块的数据，绝对不能随意调用原生的 localStorage.clear()，防止清空同一域名下其他应用或统计 SDK 的关键信息。
2. 建立容量预警与上报埋点：在发生 QuotaExceededError 或执行淘汰策略时，应向前端监控平台（如 Sentry 或自定义日志网关）上报异常事件，附带当前已使用的估算键值大小，以便开发团队及时发现异常膨胀的缓存数据。
3. 使用 StorageManager API 提前评估：现代浏览器提供了 navigator.storage.estimate() 异步方法，可以获取当前源的总配额与使用量字节数。在大型应用初始化时，可以根据剩余配额智能预判是否需要清除非必要缓存。