原生移动开发 / 技术文章
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 表达产品版本”的方案。
假设当前线上版本为:
versionCode = 41
versionName = 1.3.2下一次功能发布可以变为:
versionCode = 42
versionName = 1.4.0如果 1.4.0 上线后马上需要修复一个崩溃问题,则发布:
versionCode = 43
versionName = 1.4.1这里最关键的是 42 → 43,而不是尝试从 1.4.0 → 1.4.1 推导 Android 的升级顺序。
在 build.gradle.kts 中可以直接配置:
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 直接读取最终产物。
apkanalyzer apk summary app/build/outputs/apk/release/app-release-unsigned.apk该示例的 Release 未配置签名,因此以上命令读取未签名产物。配置如上时,命令返回三个以制表符分隔的字段。
com.example.app 42 1.4.0命令应指向实际生成的 APK,产品风味和签名配置可能改变路径或文件名。用 apkanalyzer 或渠道支持的工具读取最终产物中的应用 ID、versionCode 和 versionName,再与发布计划、签名及用户可达的已有版本比较。参见 apkanalyzer 命令说明。
版本号设计最终可以收敛成一条规则:versionCode 是机器使用的永久递增发布序号,versionName 是人使用的产品版本名称。 不要让渠道、日期、Git 提交号和产品版本同时争夺 versionCode 的含义;发布流水线只保证它递增,产品团队只维护清晰的 versionName,长期发版会稳定得多。