LocalStorage需手动添加version字段实现版本校验：存储时包装数据并写入整数版本号，读取时比对版本，不匹配则清理或调用迁移函数逐级升级。
LocalStorage 本身不提供版本号机制，要实现数据的版本号校验，需在存入数据时**手动添加 version 字段**，读取时比对预设的当前版本，不匹配则视为过期或格式变更，触发清理或迁移逻辑。
1. 存储时写入版本号
每次保存数据前，把数据包装成带 version 的对象。建议用语义化版本（如 "1.0.0"）或简单整数（如 1、2），便于后续判断。
- 推荐用整数版本号，轻量且易于比较
- 版本号应随数据结构变更而升级（例如新增字段、删字段、改类型）
- 示例写法：
const CURRENT_VERSION = 2;
const data = { name: "Alice", preferences: { theme: "dark" } };
localStorage.setItem("userConfig", JSON.stringify({
version: CURRENT_VERSION,
data
}));
2. 读取时校验并处理不兼容情况
读取后先解析，检查 version 字段是否存在且等于当前版本。若不一致，说明本地数据是旧格式，不能直接使用。
- version 缺失或非数字 → 视为 v0，需迁移或清空
- version 小于当前值 → 执行升级函数（transform v1 → v2）或直接丢弃
- version 大于当前值 → 理论上不应出现，可警告并清空（防降级污染）
function loadWithVersion(key, currentVersion) {
const item = localStorage.getItem(key);
if (!item) return null;
try {
const parsed = JSON.parse(item);
if (typeof parsed.version !== 'number') {
localStorage.removeItem(key); // 无版本号，视为无效
return null;
}
if (parsed.version < currentVersion) {
// 可选：调用 migrate 函数升级数据
const migrated = migrate(parsed.data, parsed.version, currentVersion);
localStorage.setItem(key, JSON.stringify({
version: currentVersion,
data: migrated
}));
return migrated;
}
if (parsed.version === currentVersion) {
return parsed.data;
}
// version > currentVersion：主动降级风险大，清空更安全
localStorage.removeItem(key);
return null;
} catch (e) {
localStorage.removeItem(key);
return null;
}
}
3. 提供可扩展的迁移函数
当版本迭代频繁时，迁移逻辑不宜硬编码在加载处，应抽离为独立函数，按版本逐级升级（v1→v2→v3），避免跳步出错。
立即学习“Java免费学习笔记（深入）”；
- 每个 migrate 函数只负责从某旧版到紧邻新版的转换
- 用 switch 或 map 映射版本号到迁移器
- 迁移失败时返回 null 或抛错，由上层决定是否重置
function migrate(data, from, to) {
let result = data;
for (let v = from; v < to; v++) {
switch (v) {
case 1:
result = { ...result, locale: result.lang || "zh-CN" };
break;
case 2:
result = { ...result, notifications: { enabled: true } };
break;
default:
throw new Error(`No migration path from v${v}`);
}
}
return result;
}
4. 开发阶段配合脚本自动检测版本一致性
可在项目启动或构建时生成 version 校验快照，或利用 ESLint 插件检查 localStorage key 的 version 常量是否与实际迁移逻辑同步，减少人为遗漏。
- 将 CURRENT_VERSION 放在统一配置文件中，所有相关代码引用它
- 单元测试覆盖各版本迁移路径，确保升级后数据结构正确
- 上线新版本前，确认旧版用户访问时能平稳过渡（不崩溃、不丢失关键字段）
