游戏引擎 / 系统课时
处理存档版本变化
处理存档版本变化
游戏更新后,旧玩家的本地数据不会自动跟着新代码改变。假设原存档使用 score,新版本改为 totalScore,并新增震动开关,直接读取新字段就可能得到空值。本课建立版本检测、逐版迁移、备份和失败回退流程,让旧档能升级而不丢失进度。
学习目标
- 使用独立的存档格式版本识别旧数据。
- 将版本 1 的字段安全映射到版本 2。
- 验证正常迁移、无效存档和未知新版本的处理方式。
先定义字段变化
假设旧版游戏保存了如下信息:
{
"version": 1,
"level": 3,
"score": 900,
"settings": {
"musicEnabled": false
}
}它的有效结构是版本 1,包含关卡、累计分数和音乐开关。新版存档采用版本 2,将累计分数字段 score 重命名为 totalScore,同时增加 settings.vibrationEnabled。
| 数据项 | 版本 1 | 版本 2 | 迁移规则 |
|---|---|---|---|
| 格式版本 | version: 1 |
version: 2 |
明确升级 |
| 关卡 | level |
level |
保留原值 |
| 累计分数 | score |
totalScore |
保留数值并更名 |
| 音乐开关 | musicEnabled |
musicEnabled |
保留原值 |
| 震动开关 | 不存在 | vibrationEnabled |
默认 true |
迁移不是简单把 version 改成 2:新字段必须从旧字段计算或赋予明确默认值。字段含义不能确认时应拒绝迁移,不能把错误数据当成玩家真实进度。
让迁移只沿着已知路径进行
读取存档后先解析,再判断 version。版本 2 只需要验证后使用;版本 1 必须先验证旧结构、备份原始字符串、转换为版本 2,最后写回同一个主键。未知的未来版本或损坏内容不能直接覆盖,以免老客户端破坏新客户端保存的数据。

正式项目若继续增加版本 3,优先采用 v1 → v2 → v3 的顺序迁移,每一段只处理一次已知变化。不要为每个历史版本各写一套直达最新版本的复杂分支。
实现一次可验证的升级
新建 assets/scripts/ProgressMigrationDemo.ts,将组件挂到场景节点,且不要与其他操作同一存档键的测试组件同时运行。示例使用独立教学键,首次运行写入模拟旧档,以后只读取升级后的数据。
import { _decorator, Component, sys } from 'cc';
const { ccclass } = _decorator;
const KEY = 'tutorial.progress.migration';
const BACKUP_KEY = 'tutorial.progress.migration.v1.backup';
type ProgressV2 = {
version: 2;
level: number;
totalScore: number;
settings: { musicEnabled: boolean; vibrationEnabled: boolean };
};
function isRecord(v: unknown): v is Record<string, unknown> {
return v !== null && typeof v === 'object' && !Array.isArray(v);
}
function validLevel(v: unknown): v is number {
return typeof v === 'number' && Number.isInteger(v) && v >= 1;
}
function validScore(v: unknown): v is number {
return typeof v === 'number' && Number.isFinite(v) && v >= 0;
}
function toV2(v: unknown): ProgressV2 | null {
if (!isRecord(v) || !isRecord(v.settings)) return null;
const music = v.settings.musicEnabled;
if (!validLevel(v.level) || typeof music !== 'boolean') return null;
if (v.version === 1) {
if (!validScore(v.score)) return null;
// 旧字段更名,并补齐新增设置的默认值
return {
version: 2, level: v.level, totalScore: v.score,
settings: { musicEnabled: music, vibrationEnabled: true }
};
}
if (v.version === 2) {
const vibration = v.settings.vibrationEnabled;
if (!validScore(v.totalScore) || typeof vibration !== 'boolean') return null;
return {
version: 2, level: v.level, totalScore: v.totalScore,
settings: { musicEnabled: music, vibrationEnabled: vibration }
};
}
return null;
}
@ccclass('ProgressMigrationDemo')
export class ProgressMigrationDemo extends Component {
start(): void {
try {
// 模拟旧安装遗留的版本1存档;正式项目删除此初始化
if (sys.localStorage.getItem(KEY) === null) {
sys.localStorage.setItem(KEY, JSON.stringify({
version: 1, level: 3, score: 900,
settings: { musicEnabled: false }
}));
}
const data = this.loadAndMigrate();
if (data === null) {
console.warn('存档不可读取或版本不受支持');
return;
}
console.log(`版本=${data.version} 关卡=${data.level} 累计分数=${data.totalScore} 震动=${data.settings.vibrationEnabled}`);
} catch (error) {
console.warn('初始化测试存档失败', error);
}
}
private loadAndMigrate(): ProgressV2 | null {
try {
const raw = sys.localStorage.getItem(KEY);
if (raw === null) return null;
const parsed: unknown = JSON.parse(raw);
if (!isRecord(parsed)) return null;
const current = toV2(parsed);
if (current === null) return null;
if (parsed.version === 1) {
// 备份失败时不改写主键,便于排查和恢复
sys.localStorage.setItem(BACKUP_KEY, raw);
sys.localStorage.setItem(KEY, JSON.stringify(current));
}
return current;
} catch (error) {
console.warn('存档解析或迁移失败', error);
return null;
}
}
}这个实现把数据转换集中在 toV2,将存储操作集中在 loadAndMigrate。这样可以分别验证字段映射是否正确,以及迁移失败后原始字符串是否还在。
验证升级前后的结果
在空教学键且本地存储正常的情况下,第一次预览的预期输出:
版本=2 关卡=3 累计分数=900 震动=true第一次运行完成后,主键应包含以下版本 2 数据:
{
"version": 2,
"level": 3,
"totalScore": 900,
"settings": {
"musicEnabled": false,
"vibrationEnabled": true
}
}预期结果是 BACKUP_KEY 对应的记录仍保留原始版本 1 字符串,而主键已经变成版本 2。刷新预览后再次运行,数据直接通过版本 2 校验,不应重复执行版本 1 迁移。
可以继续验证以下边界:
- 将主键中的
version改成 3。预期拒绝读取,但主键内容不变。 - 将主键内容改成无效 JSON。预期捕获解析异常,不自动覆盖损坏数据。
- 删除旧版
score字段。预期字段校验失败,迁移中止。 - 模拟备份写入失败。预期主键仍是原来的版本 1 数据。
这些检查比单纯验证一次成功升级更重要,因为实际更新可能遇到用户改动过的存档、磁盘空间不足或安装版本回退。
发布前的兼容检查
正式存档迁移应在游戏状态初始化之前完成。只有验证通过的新数据才能传给关卡系统、HUD 和音频设置;如果迁移失败,应保留原始数据并进入可恢复的错误状态,而不是直接开始新游戏覆盖旧档。
建议保留不同历史版本的样本作为回归测试数据,每次升级检查字段含义、默认值、迁移顺序以及重复启动的稳定性。若版本跨度较大,可让每个迁移函数只负责相邻版本之间的转换,再统一验证最终结构。
本例的备份策略适合展示基本兼容机制,但两个独立键的写入并不是跨平台原子事务。正式项目还需要考虑写入中断、备份恢复和存档容量限制;重要玩家数据应配合服务端备份或其他可靠的恢复方案。