原生移动开发 / 系统课时
设计可持续版本号规则
设计可持续版本号规则
多人开发和多条发布流水线并行时,版本号最容易在“各自递增”中发生冲突。可持续方案应把内部版本代码交给单一来源分配,同时让版本名称独立表达正式版、测试版和补丁版语义。
学习目标
- 为正式版和测试版设计一致的
versionName命名方式 - 用单一递增来源避免并行发布时的
versionCode冲突 - 能把版本号注入构建并验证最终产物
先把机器序号与产品语义分开
推荐把两个字段分别设计:versionCode 只负责全局递增,versionName 负责表达产品版本。不要把分支名、渠道、日期和补丁信息全部编码进一个快速膨胀的整数。
例如可以采用下面的发布序列:
| 发布用途 | versionCode |
versionName |
|---|---|---|
| 测试版 | 10427 |
2.4.0-beta.3 |
| 正式版 | 10428 |
2.4.0 |
| 热修复 | 10429 |
2.4.1 |
这里最重要的不是数字长什么样,而是 10427 → 10428 → 10429 来自同一个递增序列。测试版和正式版都消耗这个序列,因此不会出现两个团队各自生成相同代码的情况。

让 CI 成为唯一分配者
多人手工修改 versionCode 的问题在于并发:两个人都从 10426 开始,很容易同时提交 10427。更稳妥的方式是由 CI、发布服务或其他具备原子递增能力的系统生成唯一序号,再把它作为构建参数传入。
如果 CI 的构建编号是“每个分支各自从 1 开始”,就不能直接当全局 versionCode。用于发布的计数器必须跨分支、跨测试与正式渠道共享,或者由独立的版本分配服务统一生成。
versionName 则可以遵循团队约定,例如正式版使用 MAJOR.MINOR.PATCH,预发布版本附加 alpha、beta 或 rc 后缀。它可以重新规划展示格式,但不要承担机器排序职责。
在构建中强制注入版本
下面是 app 模块 build.gradle.kts 的片段示例。它要求 CI 显式提供两个环境变量,缺失或格式错误时直接终止配置,避免产生“默认版本号”的发布包。
val releaseCode = providers.environmentVariable("APP_VERSION_CODE")
.orNull
?.toIntOrNull()
?: error("APP_VERSION_CODE must be an integer")
require(releaseCode > 0) {
"APP_VERSION_CODE must be greater than 0"
}
val releaseName = providers.environmentVariable("APP_VERSION_NAME")
.orNull
?.takeIf { it.isNotBlank() }
?: error("APP_VERSION_NAME must not be blank")
android {
defaultConfig {
versionCode = releaseCode
versionName = releaseName
}
}这段做法适合发布专用流水线。若本地 Debug 构建不希望强制设置环境变量,可以把开发默认值放到单独的本地构建约定中,但 Release 仍应由 CI 提供唯一编号。
构建并核对最终版本
在类 Unix 环境中,可以给一次测试发布分配编号 10427,然后构建 Release APK 并检查产物。<PATH> 需要替换为实际 APK 路径。
APP_VERSION_CODE=10427 APP_VERSION_NAME=2.4.0-beta.3 ./gradlew --quiet :app:assembleRelease
apkanalyzer manifest version-code <PATH>/app-release.apk
apkanalyzer manifest version-name <PATH>/app-release.apk预期输出
10427
2.4.0-beta.3如果构建失败并提示环境变量缺失,说明发布流程没有拿到版本分配结果;如果 APK 中的值与输入不同,应继续检查 Product Flavor、变体脚本或其他 Gradle 配置是否覆盖了 defaultConfig。
给团队留下可执行的发布约束
一套版本规则至少应固定三件事:谁分配 versionCode、什么条件允许递增、versionName 使用什么格式。真正需要避免的是“每条分支一套计数器”“发布前临时手改整数”和“用日期乘大倍率拼出巨大数字”这类难以长期维护的做法。
当测试版、正式版和热修复都从同一个递增源领取内部代码时,并行开发不会再争抢版本号;而 versionName 仍可独立表达产品语义,发布记录也更容易追溯。