游戏叙事与剧情 / 系统课时
状态结构改了旧档怎么办
状态结构改了旧档怎么办
剧情系统一旦上线,玩家手里的存档就会落后于当前代码。解决重点不是“让旧 JSON 勉强读进来”,而是明确存档版本、迁移顺序和缺省规则,把任意受支持的旧结构稳定转换成当前结构,再交给剧情逻辑使用。
学习目标
- 为存档设计可判定的版本号与当前结构
- 用连续迁移函数把旧档升级到最新版本
- 为新增字段设置安全默认值,并验证迁移结果
先把版本号放进存档
版本号应该描述“存档结构版本”,不要直接复用游戏版本号。游戏可能只改了 UI,却没有改存档;也可能一次更新连续修改多次状态结构。把两者绑定会让迁移条件越来越难判断。
下面以一个剧情状态为例。版本 1 只有金币和章节;版本 2 新增 flags;版本 3 把单个章节编号改成更明确的 progress.chapter。下面是结构定义片段,用于明确各版本的数据形状。
type SaveV1 = {
saveVersion: 1;
coins: number;
chapter: number;
};
type SaveV2 = {
saveVersion: 2;
coins: number;
chapter: number;
flags: Record<string, boolean>;
};
type SaveV3 = {
saveVersion: 3;
coins: number;
flags: Record<string, boolean>;
progress: {
chapter: number;
};
};这里的关键是:每种历史结构都能被明确识别。不要通过“有没有某个字段”来猜版本,因为字段可能缺失、被手工修改,或者在多个版本中都存在。
迁移要按版本逐级执行
不要直接写大量 if (oldVersion < 7) 修改同一个对象。更稳妥的做法是让每次迁移只负责相邻版本,这样每个函数的输入、输出都清晰,测试也容易覆盖。

下面的示例可以直接运行,演示如何把 V1 存档升级到 V3。
type SaveV1 = {
saveVersion: 1;
coins: number;
chapter: number;
};
type SaveV2 = {
saveVersion: 2;
coins: number;
chapter: number;
flags: Record<string, boolean>;
};
type SaveV3 = {
saveVersion: 3;
coins: number;
flags: Record<string, boolean>;
progress: {
chapter: number;
};
};
type AnySave = SaveV1 | SaveV2 | SaveV3;
function migrateV1ToV2(save: SaveV1): SaveV2 {
return {
saveVersion: 2,
coins: save.coins,
chapter: save.chapter,
// 新字段必须给出不会误触发剧情的安全默认值
flags: {}
};
}
function migrateV2ToV3(save: SaveV2): SaveV3 {
return {
saveVersion: 3,
coins: save.coins,
flags: save.flags,
progress: {
chapter: save.chapter
}
};
}
function migrateToLatest(save: AnySave): SaveV3 {
let current: AnySave = save;
while (current.saveVersion < 3) {
if (current.saveVersion === 1) {
current = migrateV1ToV2(current);
continue;
}
if (current.saveVersion === 2) {
current = migrateV2ToV3(current);
continue;
}
throw new Error(`Unsupported save version: ${String(current.saveVersion)}`);
}
return current as SaveV3;
}
const oldSave: SaveV1 = {
saveVersion: 1,
coins: 120,
chapter: 4
};
console.log(JSON.stringify(migrateToLatest(oldSave)));预期输出
{"saveVersion":3,"coins":120,"flags":{},"progress":{"chapter":4}}如果实际项目还支持更老版本,只要继续保留对应的相邻迁移函数即可。删除迁移函数前,要先确认产品已经明确停止支持那一代存档。
默认值必须保证剧情安全
新增字段最容易埋坑。比如新增 bossDefeated 时,如果默认值错误地设为 true,旧档一加载就可能跳过整段 Boss 剧情。默认值应该遵循“没有证据就不推进”的原则。
对于集合类字段,通常优先使用空集合;对于是否完成的布尔状态,通常优先 false;对于进度值,则需要根据旧字段推导,而不是机械清零。能从旧数据恢复的信息应迁移,无法恢复的信息才使用默认值。
加载完成后再做结构校验
迁移结束不等于数据一定可用。存档可能被截断、手工修改,或历史版本本身就写入过非法值,因此当前版本仍应做一次最小校验。下面是片段示例,依赖上一段已经定义的 SaveV3 与 migrateToLatest。
function validateSave(save: SaveV3): void {
if (!Number.isInteger(save.coins) || save.coins < 0) {
throw new Error("Invalid coins");
}
if (!Number.isInteger(save.progress.chapter) || save.progress.chapter < 1) {
throw new Error("Invalid chapter");
}
}
const migrated = migrateToLatest({
saveVersion: 1,
coins: 120,
chapter: 4
});
validateSave(migrated);
console.log("save ok");预期输出
save ok生产环境中还应为失败保留原始存档副本,并记录“原版本、目标版本、失败步骤”,方便恢复和定位。只要坚持“识别版本 → 逐级迁移 → 补安全默认值 → 校验当前结构”这条链路,状态结构升级就不会把旧档变成一次性炸弹。