游戏客户端架构 / 系统课时

配置版本号应该放在哪里

配置版本号应该放在哪里

配置版本不是越多越安全。整包版本、表版本和单条数据版本分别解决不同层级的问题,如果混用,会让兼容判断变得模糊。本课从发布、表结构变化和单条数据演进三个场景出发,确定版本号应该放在哪一层,以及加载时怎样校验。

学习目标

  • 区分整包版本、表版本和数据版本各自负责的兼容边界
  • 根据实际发布方式选择最少但足够的版本层级
  • 设计加载阶段的版本校验顺序,避免新旧配置被错误混用

三种版本号解决三种问题

整包版本回答“这一批配置是否属于同一次发布”,适合做资源包完整性检查和回滚。表版本回答“这张表的结构或语义是否发生变化”,适合驱动字段迁移。单条数据版本回答“同一条实体是否存在独立演进”,只有在记录可以脱离整表单独更新时才有价值。

版本层级 典型位置 主要用途 适合场景
整包版本 配置包清单 发布一致性、缓存失效、回滚 多张表总是一起发布
表版本 每张表的元信息 结构迁移、字段兼容 不同表可独立演进
数据版本 单条记录 单记录升级、冲突判断 记录可独立下发或编辑

整包表级数据级版本关系

默认优先整包版本加表版本

多数游戏配置系统不需要给每一行都加版本。比较稳妥的做法是:配置包有一个发布版本,每张可能独立演进的表再有一个结构版本。

下面是一份简化的配置包清单。它不是某个框架强制的标准格式,而是一种便于说明层级关系的组织方式。

json
{
  "packageVersion": "2026.10.08.1",
  "tables": {
    "characters": {
      "tableVersion": 3,
      "file": "characters.json"
    },
    "items": {
      "tableVersion": 5,
      "file": "items.json"
    }
  }
}

生效行为是:加载器先判断整个包是否可接受,再把各表的 tableVersion 交给对应迁移器。验证时应检查清单中的文件都存在,并确认每张表的版本处于当前程序支持范围内。

让校验顺序对应兼容边界

版本校验应该从外到内。包版本不兼容时,没有必要继续解析内部表;包可用后,再逐表判断是否需要迁移。只有记录确实支持独立更新时,才进入记录级版本判断。

下面的 JavaScript 示例演示最小校验逻辑。假设当前程序支持角色表版本 2 到 3。

js
function checkCharacterTable(manifest) {
  const table = manifest.tables?.characters;

  if (!table) {
    throw new Error("characters table metadata is missing");
  }

  if (table.tableVersion < 2 || table.tableVersion > 3) {
    throw new Error(`unsupported characters tableVersion: ${table.tableVersion}`);
  }

  return table.tableVersion === 2 ? "MIGRATE" : "LOAD";
}

const manifest = {
  packageVersion: "2026.10.08.1",
  tables: {
    characters: {
      tableVersion: 2,
      file: "characters.json"
    }
  }
};

console.log(checkCharacterTable(manifest));

预期输出:

text
MIGRATE

程序只把明确支持的旧版本送入迁移流程。遇到高于当前程序认知的新版本时应拒绝加载,因为新字段、新枚举或语义变化可能让旧程序产生静默错误。

什么时候才需要单条数据版本

如果配置总是整表发布,记录级版本通常只会增加维护成本。只有当单条数据可以独立下发、多人并发编辑,或者服务端需要判断“这条记录是否比本地更新”时,记录级版本才有意义。

实际设计时,先确定最小发布单元,再决定版本放在哪里:整包一起替换就用整包版本;表结构独立演进就增加表版本;记录能够脱离表独立更新,才考虑数据版本。这样版本号数量少,校验链路也更容易测试和维护。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置版本号应该放在哪里

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

登录哪都通