原生移动开发 / 系统课时

设计可持续版本号规则

设计可持续版本号规则

多人开发和多条发布流水线并行时,版本号最容易在“各自递增”中发生冲突。可持续方案应把内部版本代码交给单一来源分配,同时让版本名称独立表达正式版、测试版和补丁版语义。

学习目标

  • 为正式版和测试版设计一致的 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 显式提供两个环境变量,缺失或格式错误时直接终止配置,避免产生“默认版本号”的发布包。

kotlin
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 路径。

bash
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

预期输出

text
10427
2.4.0-beta.3

如果构建失败并提示环境变量缺失,说明发布流程没有拿到版本分配结果;如果 APK 中的值与输入不同,应继续检查 Product Flavor、变体脚本或其他 Gradle 配置是否覆盖了 defaultConfig。

给团队留下可执行的发布约束

一套版本规则至少应固定三件事:谁分配 versionCode、什么条件允许递增、versionName 使用什么格式。真正需要避免的是“每条分支一套计数器”“发布前临时手改整数”和“用日期乘大倍率拼出巨大数字”这类难以长期维护的做法。

当测试版、正式版和热修复都从同一个递增源领取内部代码时,并行开发不会再争抢版本号;而 versionName 仍可独立表达产品语义,发布记录也更容易追溯。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计可持续版本号规则

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

登录哪都通