原生移动开发 / 系统课时
区分 versionCode 与 versionName
区分 versionCode 与 versionName
发布 Android 应用时,真正决定“哪个包更新”的不是用户看到的版本文字,而是内部递增的版本代码。本节把两个字段拆开理解,并用构建产物验证它们最终写入 APK 的值。
学习目标
- 说清
versionCode与versionName各自解决什么问题 - 能在 Gradle 配置中正确设置两个版本字段
- 能从 APK 中验证实际生效的版本代码和版本名称
两个字段承担不同职责
versionCode 是供 Android 系统和分发平台比较版本先后的整数。对同一个应用而言,新发布版本应使用更大的 versionCode,这样安装器和商店才能把它识别为更高版本。
versionName 是面向用户和运营人员的显示字符串,例如 1.2.0、2.0.0-beta.1。它适合表达产品语义,但不参与版本先后比较,因此不能依赖字符串大小判断升级关系。
| 字段 | 典型值 | 主要用途 | 是否决定升级先后 |
|---|---|---|---|
versionCode |
120 |
系统与商店内部比较版本 | 是 |
versionName |
1.2.0 |
展示给用户和团队 | 否 |
因此,versionName 从 1.9.0 改成 2.0.0 并不会自动让安装器认为它更新;真正需要同步递增的是 versionCode。
在 Gradle 中设置版本
下面是 app 模块 build.gradle.kts 中的片段示例,依赖 Android Gradle Plugin 已正常配置。两个字段通常写在 android.defaultConfig 中。
android {
defaultConfig {
versionCode = 120
versionName = "1.2.0"
}
}该配置生效后,构建出的 APK 会携带版本代码 120 和版本名称 1.2.0。如果项目使用 Groovy DSL,字段含义相同,只是 Gradle 语法不同。
从构建产物验证实际值
不要只看 Gradle 文件,还要验证最终产物。假设 Android SDK Command-Line Tools 中的 apkanalyzer 已加入 PATH,并且 Release APK 已生成,可以直接读取清单中的版本信息。
apkanalyzer manifest version-code <PATH>/app-release.apk
apkanalyzer manifest version-name <PATH>/app-release.apk预期输出
120
1.2.0<PATH> 是实际 APK 所在目录,不同项目和构建变体的路径可能不同。这里验证的是打包后的真实值,能发现脚本覆盖、Flavor 配置或 CI 注入导致的版本号与源码预期不一致。
判断一次升级是否成立
对于同一应用的一次正常升级,可以按这个顺序检查:先确认应用标识与签名关系满足升级条件,再确认新包的 versionCode 大于已安装版本,最后确认 versionName 是否符合产品期望。
实际发布时,应把 versionCode 当作机器使用的单调递增序号,把 versionName 当作人使用的版本标签。两者可以同步变化,但职责不要混用。