localStorage不支持原生版本控制，需手动在数据中嵌入version字段并校验；正确做法是统一存结构化对象，读写时比对版本号，结合惰性清理与启动扫描实现高效维护。
localStorage 本身不支持版本号，必须靠开发者手动注入和校验
浏览器不会给 localStorage 的每个 key 打上版本标记，所谓“按版本清理”，本质是往存入的数据里显式塞一个 version 字段，并在读取/写入时做比对。这和 Cache API 那种天然支持缓存名隔离的机制完全不同——你得自己管字段、自己判逻辑、自己删旧数据。
常见错误是把版本号硬编码进 key 名（如 user_profile_v2），看似隔离了，但会导致：旧版本数据永远滞留、无法批量清理、key 名膨胀难维护。正确做法是统一用结构化对象存储，把 version 当作元数据字段之一：
localStorage.setItem('user_profile', JSON.stringify({ value: {...}, version: 2, timestamp: Date.now() }))- 每次写入前检查当前应用版本（比如从
__APP_VERSION__全局变量或构建时注入的process.env.VUE_APP_VERSION读取） - 读取时先解析，再比对
item.version !== currentVersion，不一致就直接removeItem
读取时惰性清理 + 启动时批量扫描，兼顾性能与彻底性
只靠读取时判断版本会漏掉“从不被访问的旧缓存”，比如某个用户长期不用的草稿页 key；而只靠启动时全量扫描又容易卡顿——尤其当 localStorage 接近 5MB 上限时，for (let i = 0; i 配合多次 <code>JSON.parse 会让页面白屏几百毫秒。
推荐组合策略：
- 每次
getItem都解析并校验version，过期则同步removeItem并返回null - 在
requestIdleCallback中触发一次轻量扫描：只遍历前 20 个 key，检查version和timestamp，超期或版本不符就删 - 用
localStorage存一个标记（如last_version_scan: 1713250332000），确保每天最多扫一次，避免重复开销
多标签页场景下，storage 事件不能替代主动校验
你在标签 A 更新了应用版本、清除了旧缓存，会触发 storage 事件，但标签 B 监听到后，**并不能直接认为自己内存里的缓存已失效**——因为 storage 事件只告诉你 “某个 key 被删了”，并不通知 “所有 key 都该按新版本重载”。更危险的是：标签 B 可能刚从 localStorage 读出一个 v1 数据，正准备渲染，这时收到事件，但已来不及中断渲染流程。
所以必须坚持“每次读都校验”原则：
- 不要在
storage事件里做location.reload()这类粗暴操作 - 可以在事件回调中设置一个标志位（如
window.__CACHE_VERSION_DIRTY = true），下次进入关键读取逻辑前先检查该标志，再强制走一遍getWithVersion - 敏感数据（如 token、权限配置）建议配合
sessionStorage做双保险：主版本存在localStorage，当前会话有效版本存在sessionStorage，后者随标签关闭自动消失
清理逻辑必须区分“过期”和“降级”，避免误删用户主动保存的数据
版本更新不等于数据作废。比如用户在 v1 里手动保存了某份报表筛选条件，升级到 v2 后，这些条件结构没变，只是 UI 交互逻辑优化了——这时候删掉就丢了用户资产。
实际落地要加一层语义判断：
- 定义兼容规则：v2 兼容 v1 的
filter_config，但不兼容 v1 的dashboard_layout - 在工具函数里为不同 key 设定迁移策略：
allowDowngrade: ['filter_config']，遇到低版本只 warn 不删 - 对明确要销毁的 key（如
old_api_cache_*），用正则匹配批量清理，而不是依赖单个 version 字段 - 所有清理动作必须可逆：删除前把旧数据备份到
localStorage['backup_v1_' + key]，保留 24 小时供回滚
最易被忽略的一点：构建产物版本号（如 2.3.1）和运行时版本号（如通过接口拉取的 feature_flag.version）可能不一致。清理逻辑若只认构建版，就会在灰度发布期间误伤——务必以运行时获取的版本为准，且要有兜底 fallback。
