Version Code：什么是Version Code、数字标识符和更新

Android中的Version Code是什么

Version Code — 是Integer类型的一个整数，分配给Android应用程序的每个构建。与Version Name不同，Version Code不向用户显示，仅由操作系统和Google Play在安装更新时用于比较版本。

Version Code的格式

Version Code 必须是从1到2100000000范围内的正整数。每个后续构建的Version Code必须严格大于前一个。如果开发者发布了Version Code为5的构建，下一次发布可以使用6、7或任何大于5的数字，但不能是4也不能再是5。

产生历史

Google在2007年发布Android SDK时引入了Version Code和Version Name的区分。Version Code被设计为用于自动版本比较的机器标识符，而Version Name则是人类可读的标签。这种区分允许开发者随意命名版本，同时通过数字编码保持严格的更新顺序。

Version Code版本管理如何工作

比较机制 Version Code内置于Android操作系统和Google Play商店。在每次发布时，Google Play会检查新构建的Version Code是否大于已安装版本的编码。如果不满足条件，发布将被拒绝并报错。

更新检查过程

当设备联系Google Play检查更新时，服务器会将已安装应用的Version Code与商店中可用的最大值进行比较。如果服务器上的编码更大，则启动更新的下载和安装。用户看到开发者指定的Version Name，但更新决策是基于Version Code做出的。

Version Code的增量

开发者采用不同的策略来增加Version Code。最简单的方法是每次构建时增加1。对于CI/CD管道，常常使用时间戳或构建编号：2026070301（年-月-日-编号）。重要的是编码单调递增，并且不在不同的构建和Google Play跟踪之间重复。

• 单调增量 — 每次提交到release分支时增加1
• 时间戳格式 — 每日构建用20260703，每天多次构建用2026070301
• 数字中的SemVer — 版本1.1.0对应100010000（major 1, minor 1, patch 0）
• 构建编号 — 使用来自CI系统的BUILD_NUMBER（Jenkins、GitHub Actions）

Version Code与Version Name的区别

Version Code和Version Name— build.gradle中的两个独立字段，执行不同的功能。Version Code是系统的内部标识符，Version Name是用户的市场营销标签。它们可以相互独立地变化。

用户的Version Name

Version Name— 是一个字符串，显示在应用程序设置、Google Play和更新对话框中。开发者可以指定任何格式：1.0.0、2.3.1-beta、3.0-rc1。对于比较文本版本，Version Name不被使用— Google Play始终依赖Version Code。

偏差场景

可能出现Version Code增加但Version Name保持不变的情况。例如，如果开发者在不改变功能的情况下的时候修复了热修复构建中的一个严重错误。Version Name保持2.0.0，Version Code从5变为6。Google Play将正确处理这种更新。

// 示例: version name不变，code增加
android {
    defaultConfig {
        versionCode 6  // 之前是5 — 没有新功能的热修复
        versionName "2.0.0"  // 未改变
    }
}

// 在运行时检查版本
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("编码: $code, 名称: $name")

在build.gradle中配置Version Code

Version Code的配置在应用模块的build.gradle文件中完成。versionCode字段接受一个整数，位于defaultConfig块中。对于不同的flavor构建，可以通过产品配置中的versionCode字段设置自己的值。

基础配置

// build.gradle.kts — Kotlin DSL
android {
    defaultConfig {
        applicationId "com.example.app"
        versionCode 15
        versionName "2.1.0"
    }

    flavorDimensions +"version"
    productFlavors {
        create("demo") {
            versionCode 1015
        }
        create("full") {
            versionCode 2015
        }
    }
}

Product flavors允许为不同配置使用不同的Version Code：示例版、平板电脑的单独版本。如果项目中使用了flavors，最终的Version Code由基数和flavor特定的增量组成。Google Play独立跟踪每个组合。

通过CI自动化增量

在CI/CD管道中（GitHub Actions、GitLab CI、Jenkins），Version Code常常根据构建编号或日期自动生成。这消除了手动更新时的人为错误。脚本从build.gradle读取当前Version Code，增加它并在构建开始前写回。

// Version Code的自动增量
import java.util.Properties
import java.io.FileInputStream

val versionProps = Properties()
versionProps.load(FileInputStream("version.properties"))

val versionCode = versionProps.getProperty("VERSION_CODE").toInt() + 1
versionProps.setProperty("VERSION_CODE", versionCode.toString())

android {
    defaultConfig {
        versionCode = versionCode
    }
}

在Google Play中发布的Version Code规则

Google Play对于发布和更新应用程序时的Version Code有严格的规则。违反这些规则将导致构建被拒绝或无法发布更新。开发者必须理解生命周期所有阶段的限制和代码管理策略。

单调增长规则

Google Play不允许上传Version Code小于或等于当前已发布版本的APK或AAB。这条规则独立适用于每个跟踪（production、beta、alpha）。如果在production中上传了Version Code为10的构建，而alpha中的编码为5，则alpha跟踪可以更新到6、7、8或9，但production保持在10。

跟踪之间的迁移

在将构建从alpha提升到beta，然后到production时，Version Code必须在每个阶段增加。如果alpha版本的编码为10，beta可以使用11，production可以使用12。如果alpha已经使用10，则不能将编码为10的构建部署到production，即使production还没有见过它。

• Monotonous increment — 每个跟踪中的构建在同一跟踪中具有比前一个更大的Version Code
• Cross-track awareness — 在跟踪之间提升时，Version Code顺序增加
• Internal testing — 内部测试跟踪使用相同的单调性规则
• Multiple APKs — 旧的发布格式要求每个APK都有唯一的Version Code

指定Version Code时的错误

最常见的错误是上传到同一个跟踪的不同构建中Version Code重复。Google Play返回APK_VERSION_CODE_ALREADY_EXISTS错误。另一个错误是超过最大值2100000000，这将导致编译错误。为了避免冲突，请在CI系统中使用与构建编号或构建日期关联的自动代码生成。

开发者经常犯的错误还包括在为替代跟踪构建热修复时不增加Version Code。如果production的编码为15，而alpha跟踪保持在14，那么在将alpha提升到production时，Google Play将拒绝构建，因为它的编码小于当前的production。同时监控所有跟踪中代码的单调性—为此，使用一个统一的version.properties文件，所有跟踪从中读取当前值非常方便。