原生移动开发 / 系统课时

区分 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 中。

kotlin
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 已生成,可以直接读取清单中的版本信息。

bash
apkanalyzer manifest version-code <PATH>/app-release.apk
apkanalyzer manifest version-name <PATH>/app-release.apk

预期输出

text
120
1.2.0

<PATH> 是实际 APK 所在目录,不同项目和构建变体的路径可能不同。这里验证的是打包后的真实值,能发现脚本覆盖、Flavor 配置或 CI 注入导致的版本号与源码预期不一致。

判断一次升级是否成立

对于同一应用的一次正常升级,可以按这个顺序检查:先确认应用标识与签名关系满足升级条件,再确认新包的 versionCode 大于已安装版本,最后确认 versionName 是否符合产品期望。

实际发布时,应把 versionCode 当作机器使用的单调递增序号,把 versionName 当作人使用的版本标签。两者可以同步变化,但职责不要混用。

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

目录与阅读设置

阅读设置

17

记录一个想法

区分 versionCode 与 versionName

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

登录哪都通