Web Storage处理 localStorage 配额异常的实现方法

前端设置页最容易遇到的一类问题，是用户明明只保存了一点配置，localStorage.setItem() 却突然抛出异常。处理这件事的关键不是猜浏览器还剩多少空间，而是把写入当成一个可能失败的同步操作：捕获异常、保留当前页面可用状态，并把大数据迁移到异步存储。这样，配额耗尽、隐私模式限制或用户禁用存储时，页面也不会因为一次保存动作直接中断。

先把 localStorage 配额异常放回正确边界

同一 origin 下的文档共享一块 localStorage，浏览器关闭后数据通常仍会保留；sessionStorage 则按标签页分开。两者都通过同步 API 完成读写，所以“保存一个很大的 JSON”不仅可能遇到容量限制，还可能在主线程上造成卡顿。配额不是一个可以跨浏览器写死的常数，实际结果还会受浏览器策略、用户设置和隐私上下文影响。

因此，本文只处理小型偏好设置、筛选条件和最近一次视图这类同步状态。离线文档、图片缓存、长列表和需要大量更新的数据，应直接评估 IndexedDB 等异步方案。

用可恢复的写入函数捕获失败

不要把 setItem 散落在按钮回调里。先统一序列化、写入和清理动作，失败时返回结果，并且不覆盖内存中的旧值。

// 将小型状态安全地写入 localStorage，失败时交给调用方降级
function trySaveLocal(key, value) {
  try {
    const serialized = JSON.stringify(value);
    localStorage.setItem(key, serialized);
    return true;
  } catch (error) {
    // 配额超限、存储被禁用或序列化失败都走同一条降级路径
    console.warn('localStorage 写入失败，准备使用内存状态', error);
    return false;
  }
}

function tryLoadLocal(key) {
  try {
    const raw = localStorage.getItem(key);
    return raw === null ? undefined : JSON.parse(raw);
  } catch (error) {
    // 读取异常时返回 undefined，避免初始化阶段阻塞页面
    console.warn('localStorage 读取失败', error);
    return undefined;
  }
}

这里没有只判断异常名称，因为不同浏览器对 DOMException 的名称和历史字段并不完全一致；对业务来说，“这次持久化没有完成”比依赖某一个错误字符串更可靠。需要记录指标时，可以在 catch 中单独归类异常，但不要把异常文本展示给最终用户。

内存降级要保留旧值，并明确刷新后的结果

降级不是把异常吞掉后什么都不做。可以为当前页面维护一个内存副本：写入成功就同步更新，写入失败就只更新内存副本；读取时先尝试持久化值，没有值再取内存值。这样用户仍能完成当前表单操作，但刷新页面后内存数据会丢失，界面应给出轻量提示，而不是假装“已永久保存”。

// 仅作为当前页面生命周期的兜底，不承诺刷新后仍存在
const memoryFallback = new Map();

function savePreference(key, value) {
  const ok = trySaveLocal(key, value);
  // 无论持久化是否成功，都让当前页面拥有最新可用值
  memoryFallback.set(key, value);
  return { persisted: ok, value };
}

function loadPreference(key, defaultValue) {
  const persisted = tryLoadLocal(key);
  if (persisted !== undefined) return persisted;
  // 持久化值不可读时，优先返回本页刚刚产生的状态
  return memoryFallback.has(key) ? memoryFallback.get(key) : defaultValue;
}

这段代码的边界很窄：它适合主题、排序方式、表单草稿的小片段，不适合令牌、密码或必须跨设备同步的数据。敏感数据应交给更合适的会话和服务端方案，不能因为“能写进去”就把它当成安全存储。

用检查表决定继续使用还是迁移

最后再做一次容量演练：让测试环境模拟写入失败，确认按钮不会重复提交、旧值不会被空值覆盖，并把“本次仅保存在当前页面”的提示接入产品文案。不要用一次成功写入推断所有浏览器和隐私模式都能永久保存；私密窗口中，localStorage 的生命周期可能接近 sessionStorage。

常见问题

捕获了 QuotaExceededError 就够了吗？

不够。浏览器可能使用不同的异常名称或策略，业务应以写入是否成功为判断依据，再把异常用于日志归类。

清理旧 key 能解决所有配额问题吗？

不能。清理可能释放空间，但无法覆盖存储被禁用、隐私上下文策略或序列化失败；清理前还要确认不会删除用户仍需要的状态。

内存降级后要不要自动重试？

不要在每次渲染时循环重试。可以在用户明确触发保存、页面状态变化或下次加载时做一次有边界的尝试，并记录失败原因。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API