游戏引擎 / 系统课时

处理存档版本变化

处理存档版本变化

游戏更新后,旧玩家的本地数据不会自动跟着新代码改变。假设原存档使用 score,新版本改为 totalScore,并新增震动开关,直接读取新字段就可能得到空值。本课建立版本检测、逐版迁移、备份和失败回退流程,让旧档能升级而不丢失进度。

学习目标

  • 使用独立的存档格式版本识别旧数据。
  • 将版本 1 的字段安全映射到版本 2。
  • 验证正常迁移、无效存档和未知新版本的处理方式。

先定义字段变化

假设旧版游戏保存了如下信息:

json
{
  "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,将组件挂到场景节点,且不要与其他操作同一存档键的测试组件同时运行。示例使用独立教学键,首次运行写入模拟旧档,以后只读取升级后的数据。

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。这样可以分别验证字段映射是否正确,以及迁移失败后原始字符串是否还在。

验证升级前后的结果

在空教学键且本地存储正常的情况下,第一次预览的预期输出:

text
版本=2 关卡=3 累计分数=900 震动=true

第一次运行完成后,主键应包含以下版本 2 数据:

json
{
  "version": 2,
  "level": 3,
  "totalScore": 900,
  "settings": {
    "musicEnabled": false,
    "vibrationEnabled": true
  }
}

预期结果是 BACKUP_KEY 对应的记录仍保留原始版本 1 字符串,而主键已经变成版本 2。刷新预览后再次运行,数据直接通过版本 2 校验,不应重复执行版本 1 迁移。

可以继续验证以下边界:

  1. 将主键中的 version 改成 3。预期拒绝读取,但主键内容不变。
  2. 将主键内容改成无效 JSON。预期捕获解析异常,不自动覆盖损坏数据。
  3. 删除旧版 score 字段。预期字段校验失败,迁移中止。
  4. 模拟备份写入失败。预期主键仍是原来的版本 1 数据。

这些检查比单纯验证一次成功升级更重要,因为实际更新可能遇到用户改动过的存档、磁盘空间不足或安装版本回退。

发布前的兼容检查

正式存档迁移应在游戏状态初始化之前完成。只有验证通过的新数据才能传给关卡系统、HUD 和音频设置;如果迁移失败,应保留原始数据并进入可恢复的错误状态,而不是直接开始新游戏覆盖旧档。

建议保留不同历史版本的样本作为回归测试数据,每次升级检查字段含义、默认值、迁移顺序以及重复启动的稳定性。若版本跨度较大,可让每个迁移函数只负责相邻版本之间的转换,再统一验证最终结构。

本例的备份策略适合展示基本兼容机制,但两个独立键的写入并不是跨平台原子事务。正式项目还需要考虑写入中断、备份恢复和存档容量限制;重要玩家数据应配合服务端备份或其他可靠的恢复方案。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理存档版本变化

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通