客户端、资源、配置与协议版本

Category

production / 版本体系。节点定位：四类版本（客户端包、资源/配置、协议、服务端逻辑）各自代表什么、为什么必须分开治理、拆开后新增的依赖关系怎么管。

Definition

把所有变化都绑在客户端包版本上，早期看起来最省事，长期几乎一定会失效。原因很简单：这些构件根本不是为同一种发布节奏服务的。客户端包受审核和渠道限制，资源和配置常常需要更快迭代，协议和服务端逻辑还可能为了兼容窗口被迫错开演进。把它们硬绑在一起，意味着所有变化都必须走最慢、最重的那条路。

所以版本拆分不是管理上的“复杂化”，而是对不同变化节奏的承认。

Problem

把所有变化绑在客户端包版本上，早期省事、长期必然失效：所有变化都被迫走最慢最重的发布路径。拆开之后真正新增的不是编号，而是依赖关系——哪组合法、谁兼容谁、错峰窗口怎么算，这些依赖没有台账，多版本共存就是排障地狱。

四类版本各自真正代表什么

客户端包版本

它通常代表宿主二进制能力，包括：

• 原生代码和引擎运行时
• 平台 SDK 和系统权限
• 本地宿主接口
• 基础渲染和运行时能力

它最重，也最难频繁替换，所以通常更适合作为最低宿主能力边界，而不是承载所有业务变化。

资源版本

资源版本对应的是表现资产和加载清单，例如：

• UI 图集
• 场景与特效资源
• 音频和动画
• 分包与热更资源集

它的关键不是版本号本身，而是资源依赖、清单一致性和与宿主能力的匹配关系。

配置版本

配置版本对应的是规则数据和内容参数，例如：

• 数值参数
• 活动规则
• 掉落与任务表
• 页面与内容编排

配置版本之所以需要独立治理，是因为它的变更频率通常远高于客户端包，而且一旦出错，表现出来往往不是崩溃，而是更隐蔽的规则事故。

协议版本

协议版本代表通信契约和状态结构，包括：

• 消息格式
• 字段语义
• 功能开关支持范围
• 前后端是否能对同一份状态达成一致理解

协议版本的难点不在升级本身，而在兼容窗口内新旧客户端如何同时被服务端正确接住。

为什么这些版本必须分开治理

如果不分开，最直接的后果通常有两个：

• 轻量变化被迫走最重的发布链路，整体响应速度越来越慢
• 重量变化伪装成轻量变化，兼容和风险被系统性低估

例如一个只想修活动参数的小改动，如果必须重新走客户端提审，迭代成本会失控；反过来，如果一个依赖新宿主接口的变化被伪装成“只是资源和配置更新”，线上就会出现非常危险的兼容事故。

版本拆开以后，真正新增的不是编号，而是依赖关系

很多团队在这里会走到另一个极端：既然要拆，就给每类构件都配一个版本号。问题是，只有版本号而没有依赖关系和校验规则，系统只会更乱。

真正需要被正式表达的是：

• 某个资源版本最低要求哪个包版本
• 某个配置批次是否依赖某个协议字段
• 某个协议版本是否仍兼容一组历史客户端
• 某个热更补丁是否只能运行在特定宿主能力之上

版本数量不是问题，失去可判定性才是问题。

一个更稳妥的组织方式

比较稳妥的做法通常是：

• 用包版本定义宿主能力基线
• 用资源版本定义可加载资源集合
• 用配置版本定义规则数据快照
• 用协议版本定义通信兼容边界
• 用显式依赖规则把它们串起来

这样做的核心不是把概念拆得更细，而是让系统知道哪些变化可以独立推进，哪些变化必须联动推进。

最容易被忽略的测试难点

版本拆开之后，测试难点不再只是“当前版本能不能跑”，而是：

• 合法组合是不是都能跑
• 非法组合是不是都能被拦住
• 历史包在兼容窗口内是否还能稳定接入
• 灰度组和非灰度组是否看到正确差异

所以多版本治理本质上也会要求测试和发布平台升级，否则团队只是把复杂度从开发端挪到了线上。

常见误区

最常见的错误，是继续把所有变化绑定在客户端包版本上，导致发布链路越来越重。第二类错误，是版本号虽然拆开了，却没有显式依赖关系和合法组合校验。第三类错误，是只做版本拆分，不补测试矩阵和发布判定能力，结果线上还是只能靠经验猜兼容性。

Used By

四类版本的治理规则制定；热更/强更策略（资源版本与包版本的关系）；协议演进与多版本兼容设计。

Related

关系链：四类版本 → 分开治理 → 依赖台账 → 组织方式 → 测试矩阵。上游：版本总览（01）。下游：灰度与回滚（03）、client 树资源系统（client/03，资源版本的生产端）。

Reference

本页为工程经验归纳。