原生移动开发 / 技术文章

Android versionCode 怎么设计才不乱

Android 应用的版本号最好从一开始就把两个问题分开:系统如何判断哪个安装包更新,以及用户看到的版本叫什么。versionCode 负责前者,必须沿发布链路持续递增;versionName 负责后者,可以按产品版本表达。把这两个字段各司其职,后续做补丁、多渠道和 CI 自动发版都会简单很多。

versionCode 和 versionName 不是一套编号

versionCode 是 Android 用来判断应用版本顺序的内部整数。为同一应用发布的新构建应使用更高的编号。Google Play 不允许把同一编号用在再次上传的新产物上。已上传并通过验证的同一个 App Bundle 可以用于不同发布轨道,无需为推广重新构建或重新编号。参见 Android 版本配置和 Play 测试轨道说明。

versionName 是展示给用户看的字符串,例如 1.0.0、2.3.1。Android 不依靠它判断升级顺序,因此 1.10.0、2.0.0 这些字符串的大小关系不会代替 versionCode。

字段 面向谁 核心规则 示例
versionCode Android、应用市场、升级逻辑 正整数,发布版本持续递增 42
versionName 用户、客服、产品和测试人员 可读、稳定表达产品版本 1.4.0

因此,一个完全正常的版本可以是 versionCode = 42、versionName = "1.4.0"。两者没有必要转换成相同数字。

versionCode 只做单调递增最稳妥

对大多数应用,最稳定的方案不是把年月日、语义版本和渠道信息全部塞进 versionCode,而是把它当成一个永不回退的发布序号。

例如:

  • 第一次正式发布:1
  • 第二次正式发布:2
  • 修复线上问题再次发布:3
  • 下一次功能版本:4

可以让发布流水线为同一应用 ID 集中分配序号,例如 105、106、107。跨分支、热修复和多流水线时,分配动作要避免并发重复。分配序号后,还要按实际分发顺序核对。比如测试轨道已发 107,生产轨道发布 106 时,符合资格的测试用户可能继续收到 107。若需要给已经安装 107 的用户发基于旧代码的修订,重新构建并发放高于 107 的序号,同时检查数据库和数据格式能否兼容。

Google Play 当前允许的 versionCode 最大值为 2100000000。普通项目使用简单递增序号几乎不会碰到上限,也比日期编码更容易长期维护。

versionName 用产品版本表达变化

versionName 更适合使用类似 Semantic Versioning 的 主版本.次版本.修订版本 形式,例如 2.4.1。

一个容易执行的约定是:

  • 2.0.0:产品出现明显的大版本变化;
  • 2.4.0:增加一批向后兼容的新功能;
  • 2.4.1:修复缺陷,没有明显产品级功能变化。

Android 并不强制这种格式,所以不需要为了符合系统要求机械使用三段版本号。真正重要的是团队内部保持一致,让测试、客服和用户看到 2.4.1 时能够明确对应同一批发布内容。

内部测试版本如果确实需要区分,可以通过构建类型增加后缀,例如 2.4.1-debug。正式 Release 包则保持干净的用户版本号。

推荐把两个字段这样组合

对于普通商业 App,可以直接使用“versionCode 独立递增 + versionName 表达产品版本”的方案。

假设当前线上版本为:

text
versionCode = 41
versionName = 1.3.2

下一次功能发布可以变为:

text
versionCode = 42
versionName = 1.4.0

如果 1.4.0 上线后马上需要修复一个崩溃问题,则发布:

text
versionCode = 43
versionName = 1.4.1

这里最关键的是 42 → 43,而不是尝试从 1.4.0 → 1.4.1 推导 Android 的升级顺序。

在 build.gradle.kts 中可以直接配置:

kotlin
android {
    defaultConfig {
        applicationId = "com.example.app"

        versionCode = 42
        versionName = "1.4.0"
    }

    buildTypes {
        debug {
            versionNameSuffix = "-debug"
        }

        release {
            isMinifyEnabled = true
        }
    }
}

这段配置生效后,Release 构建的版本为 42 / 1.4.0,Debug 构建展示的 versionName 会带上 -debug 后缀。正式发布时仍然只维护一条明确的 versionCode 递增链。

多渠道不要随意改 versionCode

渠道包要相互覆盖升级,首先要核对它们的应用 ID 和签名是否兼容,并检查目标商店是否限制该升级路径。如果多个渠道包代表同一发布批次,可以按渠道规则统一 versionCode 和 versionName。需要以一个渠道包替换另一个已安装包时,还要按实际设备及渠道测试同编号行为,或使用更高编号发布下一批。若渠道使用不同应用 ID,版本号各自独立,也不会相互覆盖。

渠道身份可以放在 Product Flavor、构建字段、安装来源识别或后台渠道参数中,不要仅仅为了区分渠道就把版本号设计成 4201、4202、4203,否则后续很容易出现某个渠道包数值更大,导致另一个渠道的新版本反而不能正常覆盖安装。

若同一应用仍按传统方式上传多个独立 APK,设备可能同时匹配多个产物,这时需要按分发规则为不同 APK 规划唯一的 versionCode 和优先级。通过 AAB 由 Google Play 生成的配置拆分 APK 不需要在应用 Gradle 配置里逐个分配编号。参见 Google Play 多 APK 支持说明。

构建后验证最终版本号

不要只看 Gradle 文件里的配置,因为 Product Flavor、Build Type 或构建脚本都可能覆盖最终值。生成 APK 后,可以用 Android SDK Command-Line Tools 提供的 apkanalyzer 直接读取最终产物。

bash
apkanalyzer apk summary app/build/outputs/apk/release/app-release-unsigned.apk

该示例的 Release 未配置签名,因此以上命令读取未签名产物。配置如上时,命令返回三个以制表符分隔的字段。

text
com.example.app	42	1.4.0

命令应指向实际生成的 APK,产品风味和签名配置可能改变路径或文件名。用 apkanalyzer 或渠道支持的工具读取最终产物中的应用 ID、versionCode 和 versionName,再与发布计划、签名及用户可达的已有版本比较。参见 apkanalyzer 命令说明。

版本号设计最终可以收敛成一条规则:versionCode 是机器使用的永久递增发布序号,versionName 是人使用的产品版本名称。 不要让渠道、日期、Git 提交号和产品版本同时争夺 versionCode 的含义;发布流水线只保证它递增,产品团队只维护清晰的 versionName,长期发版会稳定得多。

目录与阅读设置

记录一个想法

Android versionCode 怎么设计才不乱

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

登录哪都通