前端 localStorage 缓存治理实战：过期时间、版本号和异常兜底

很多前端页面都会用 localStorage 记住用户设置：列表筛选条件、主题色、最近打开的 tab、表单草稿。它简单好用，但也容易变成“旧数据仓库”：字段结构变了，缓存还在；业务规则变了，缓存仍然生效；用户清不掉，页面状态就会很怪。

本文用“商品列表筛选条件缓存”做例子，封装一个带过期时间、版本号和异常兜底的本地缓存工具。重点不是把工具写得很大，而是给每份缓存加上生命周期。

摘要

localStorage 只负责存字符串，不会自动过期，也不知道你的业务字段是否升级。更稳的做法是：写入时带上 expireAt 和 version；读取时先检查过期，再检查版本；版本不兼容就清理重建；解析失败、容量不足时要有兜底。

适合人群

适合正在做后台筛选页、用户偏好设置、轻量草稿保存、前端状态持久化的开发者。你需要了解基本 JavaScript、JSON 和浏览器存储。

目录

• 为什么 localStorage 需要治理
• 给缓存加过期时间
• 版本号不一致时怎么迁移
• 异常兜底和调试方法
• 上线前检查清单

一、为什么 localStorage 需要治理

最常见的问题是“旧缓存影响新页面”。比如商品列表以前只保存 keyword，后来新增了 categoryId、sortBy，再后来字段名又改了。如果读取时不判断版本，旧缓存可能会让页面初始化成一个业务上不存在的状态。

另一个问题是缓存永不过期。用户半年后再打开页面，仍然恢复很久以前的筛选条件，可能以为数据丢了。对筛选条件、草稿、临时偏好这类数据，过期时间是必须的。

二、给缓存加过期时间

先设计一个统一结构。真正的业务数据放在 value，过期时间放在 expireAt，版本号放在 version。

const CACHE_VERSION = 2;

function now() {
  return Date.now();
}

function setCache(key, value, ttlMs) {
  const payload = {
    version: CACHE_VERSION,
    expireAt: now() + ttlMs,
    value,
  };

  localStorage.setItem(key, JSON.stringify(payload));
}

function removeCache(key) {
  localStorage.removeItem(key);
}

读取时先处理空值、解析失败、过期三种情况：

function readRawCache(key) {
  const raw = localStorage.getItem(key);
  if (!raw) {
    return null;
  }

  try {
    return JSON.parse(raw);
  } catch (error) {
    removeCache(key);
    return null;
  }
}

function getCache(key) {
  const payload = readRawCache(key);
  if (!payload) {
    return null;
  }

  if (typeof payload.expireAt !== 'number' || payload.expireAt 

这张图对应缓存生命周期：写入时带过期时间；读取时检查当前时间和过期时间；过期就清理；未过期才把数据返回给页面。这样页面不会长期吃到旧状态。

三、版本号不一致时怎么迁移

过期时间解决“太旧”的问题，版本号解决“结构变了”的问题。假设旧版筛选条件是：

{
  "keyword": "phone",
  "status": "online"
}

新版需要变成：

{
  "keyword": "phone",
  "status": "online",
  "sortBy": "created_desc"
}

如果旧数据还能兼容，就迁移；如果字段差异太大，就清理并使用默认值。

function migrateFilterCache(payload) {
  if (!payload || typeof payload !== 'object') {
    return null;
  }

  if (payload.version === CACHE_VERSION) {
    return payload.value;
  }

  if (payload.version === 1 && payload.value) {
    return {
      keyword: payload.value.keyword || '',
      status: payload.value.status || 'all',
      sortBy: 'created_desc',
    };
  }

  return null;
}

function getVersionedCache(key, fallbackValue) {
  const payload = readRawCache(key);
  if (!payload) {
    return fallbackValue;
  }

  if (typeof payload.expireAt !== 'number' || payload.expireAt 

版本迁移的关键是不要硬读。先看缓存版本和当前版本是否一致；能兼容就补字段后写回新版；不兼容就清理重建，避免旧数据影响页面。

四、在页面里使用

下面把工具用到商品列表筛选条件里：

const FILTER_CACHE_KEY = 'product:list:filter';
const FILTER_DEFAULT = {
  keyword: '',
  status: 'all',
  sortBy: 'created_desc',
};

function loadFilterState() {
  return getVersionedCache(FILTER_CACHE_KEY, FILTER_DEFAULT);
}

function saveFilterState(filter) {
  setCache(FILTER_CACHE_KEY, filter, 7 * 24 * 60 * 60 * 1000);
}

function clearFilterState() {
  removeCache(FILTER_CACHE_KEY);
}

页面初始化时读取缓存，用户修改筛选条件后保存缓存，点击“重置筛选”时清理缓存。这样缓存逻辑和页面逻辑分开，后续维护更容易。

五、异常兜底和调试方法

localStorage 也会失败。比如隐私模式限制、容量不足、用户手动写入脏数据，都可能让读写异常。写入可以加一层保护：

function safeSetCache(key, value, ttlMs) {
  try {
    setCache(key, value, ttlMs);
    return true;
  } catch (error) {
    return false;
  }
}

调试时建议打开浏览器开发者工具，在 Application 面板里查看 Local Storage。重点检查四件事：

• key 是否按业务模块命名，避免互相覆盖。
• value 是否包含 version、expireAt 和业务数据。
• 过期后是否会自动清理。
• 版本升级后是否迁移或重建为默认值。

常见问题

1. localStorage 适合存用户敏感信息吗？

不适合。它能被同源脚本读取，不适合保存 token、手机号、身份证号等敏感信息。本文讨论的是筛选条件、偏好设置这类低风险数据。

2. 为什么不用 sessionStorage？

sessionStorage 会话结束后通常就消失，适合临时状态。需要跨天保留的筛选条件和偏好设置，更适合 localStorage，但要加过期时间。

3. 版本号要不要每次发布都加？

不需要。只有缓存结构或业务含义变了，才需要升级版本。纯样式调整、页面文案调整，不需要改缓存版本。

上线前检查清单

• 缓存 key 是否有模块前缀，避免命名冲突。
• 缓存结构是否包含 version 和 expireAt。
• 读取失败、JSON 解析失败、过期时是否会清理。
• 版本升级后是否能迁移旧数据，或安全回退到默认值。
• 是否避免存储敏感信息。

总结

localStorage 本身很简单，但线上使用要有边界。给缓存加过期时间，可以避免旧状态长期影响页面；加版本号和迁移逻辑，可以应对字段结构变化；加异常兜底，可以让脏数据不会拖垮页面初始化。把这些规则封装成工具函数后，页面代码会干净很多。