游戏客户端架构 / 系统课时
配置版本号应该放在哪里
配置版本号应该放在哪里
配置版本不是越多越安全。整包版本、表版本和单条数据版本分别解决不同层级的问题,如果混用,会让兼容判断变得模糊。本课从发布、表结构变化和单条数据演进三个场景出发,确定版本号应该放在哪一层,以及加载时怎样校验。
学习目标
- 区分整包版本、表版本和数据版本各自负责的兼容边界
- 根据实际发布方式选择最少但足够的版本层级
- 设计加载阶段的版本校验顺序,避免新旧配置被错误混用
三种版本号解决三种问题
整包版本回答“这一批配置是否属于同一次发布”,适合做资源包完整性检查和回滚。表版本回答“这张表的结构或语义是否发生变化”,适合驱动字段迁移。单条数据版本回答“同一条实体是否存在独立演进”,只有在记录可以脱离整表单独更新时才有价值。
| 版本层级 | 典型位置 | 主要用途 | 适合场景 |
|---|---|---|---|
| 整包版本 | 配置包清单 | 发布一致性、缓存失效、回滚 | 多张表总是一起发布 |
| 表版本 | 每张表的元信息 | 结构迁移、字段兼容 | 不同表可独立演进 |
| 数据版本 | 单条记录 | 单记录升级、冲突判断 | 记录可独立下发或编辑 |

默认优先整包版本加表版本
多数游戏配置系统不需要给每一行都加版本。比较稳妥的做法是:配置包有一个发布版本,每张可能独立演进的表再有一个结构版本。
下面是一份简化的配置包清单。它不是某个框架强制的标准格式,而是一种便于说明层级关系的组织方式。
{
"packageVersion": "2026.10.08.1",
"tables": {
"characters": {
"tableVersion": 3,
"file": "characters.json"
},
"items": {
"tableVersion": 5,
"file": "items.json"
}
}
}生效行为是:加载器先判断整个包是否可接受,再把各表的 tableVersion 交给对应迁移器。验证时应检查清单中的文件都存在,并确认每张表的版本处于当前程序支持范围内。
让校验顺序对应兼容边界
版本校验应该从外到内。包版本不兼容时,没有必要继续解析内部表;包可用后,再逐表判断是否需要迁移。只有记录确实支持独立更新时,才进入记录级版本判断。
下面的 JavaScript 示例演示最小校验逻辑。假设当前程序支持角色表版本 2 到 3。
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));预期输出:
MIGRATE程序只把明确支持的旧版本送入迁移流程。遇到高于当前程序认知的新版本时应拒绝加载,因为新字段、新枚举或语义变化可能让旧程序产生静默错误。
什么时候才需要单条数据版本
如果配置总是整表发布,记录级版本通常只会增加维护成本。只有当单条数据可以独立下发、多人并发编辑,或者服务端需要判断“这条记录是否比本地更新”时,记录级版本才有意义。
实际设计时,先确定最小发布单元,再决定版本放在哪里:整包一起替换就用整包版本;表结构独立演进就增加表版本;记录能够脱离表独立更新,才考虑数据版本。这样版本号数量少,校验链路也更容易测试和维护。