应用版本控制

版本管理是应用升级和维护策略的重要组成部分。版本管理之所以重要，原因如下：

  • 用户需要了解安装在其设备上的应用版本以及可供安装的升级版本等具体信息。
  • 其他应用（包括您作为套件发布的所有其他应用）需要向系统查询您应用的版本，以确定兼容性并识别依赖关系。
  • 您发布应用的平台服务可能也需要查询您应用的版本，以便向用户显示版本信息。发布服务可能还需要检查应用版本以确定兼容性，并建立升级/降级关系。

Android 系统会使用您应用的版本信息来防止降级。系统不会使用应用版本信息来强制限制第三方应用的升级或兼容性。您的应用必须自行实施任何版本限制并告知用户。

Android 系统会强制执行系统版本兼容性，这一点通过构建文件中的 minSdk 设置来体现。此设置允许应用指定其兼容的最低系统 API。有关 API 要求的更多信息，请参阅 指定 API 级别（SDK 版本）要求。

不同项目的版本管理要求各不相同。不过，许多开发者认为 语义化版本控制 (Semantic Versioning) 是版本管理策略的一个良好基础。

设置应用版本信息

要定义应用的版本信息，请在 Gradle 构建文件中为版本设置赋值。

Groovy

    android {
      namespace 'com.example.testapp'
      compileSdk 33

      defaultConfig {
          applicationId "com.example.testapp"
          minSdk 24
          targetSdk 33
          versionCode 1
          versionName "1.0"
          ...
      }
      ...
    }
    ...

Kotlin

    android {
      namespace = "com.example.testapp"
      compileSdk = 33

      defaultConfig {
          applicationId = "com.example.testapp"
          minSdk = 24
          targetSdk = 33
          versionCode = 1
          versionName = "1.0"
          ...
      }
      ...
    }
    ...

版本设置

为两个可用的版本设置定义值：versionCode 和 versionName。

versionCode
用作内部版本号的正整数。此数字有助于确定哪个版本更新，数字越大表示版本越新。这不是向用户显示的版本号；该版本号由 versionName 设置。Android 系统使用 versionCode 值来防止降级，方法是禁止用户安装 versionCode 低于设备上当前已安装版本的 APK。

该值必须为正整数，以便其他应用可以对其进行程序化评估——例如，检查升级或降级关系。您可以将该值设置为任何正整数。不过，请确保应用的每次后续发布都使用更大的值。

注意：Google Play 允许的 versionCode 最大值为 2,100,000,000。

您不能上传 versionCode 已被之前版本使用过的 APK 到 Play 商店。

注意：在某些情况下，您可能希望上传 versionCode 低于最新版本的应用版本。例如，如果您发布多个 APK，则可能已为特定 APK 预设了 versionCode 范围。有关为多个 APK 分配 versionCode 的更多信息，请参阅 分配版本代码。

通常，您会以 versionCode 为 1 发布应用的第一版，然后随着每次发布单调递增该值，无论该发布是大版本还是小版本。这意味着 versionCode 值并不一定与用户可见的应用发布版本相同。应用和发布服务不应向用户显示此版本值。

versionName

用作向用户显示的版本号的字符串。此设置可以指定为原始字符串或字符串资源的引用。

该值是一个字符串，因此您可以将应用版本描述为 <major>.<minor>.<point> 字符串或任何其他类型的绝对或相对版本标识符。versionName 是唯一向用户显示的值。

定义版本值

您可以通过将这些设置包含在模块的 build.gradle 或 build.gradle.kts 文件中 android {} 代码块内嵌套的 defaultConfig {} 代码块中，来定义默认值。然后，您可以通过为不同的构建类型或产品变体定义单独的值，来覆盖这些默认值。以下文件显示了 defaultConfig {} 代码块以及 productFlavors {} 代码块中的 versionCode 和 versionName 设置。

这些值随后会在构建过程中合并到您应用的清单文件中。

Groovy

    android {
        ...
        defaultConfig {
            ...
            versionCode 2
            versionName "1.1"
        }
        productFlavors {
            demo {
                ...
                versionName "1.1-demo"
            }
            full {
                ...
            }
        }
    }

Kotlin

    android {
        ...
        defaultConfig {
            ...
            versionCode = 2
            versionName = "1.1"
        }
        productFlavors {
            create("demo") {
                ...
                versionName = "1.1-demo"
            }
            create("full") {
                ...
            }
        }
    }

在此示例的 defaultConfig {} 代码块中，versionCode 值表示当前的 APK 包含应用的第二个版本，而 versionName 字符串指定它向用户显示为版本 1.1。此文件还定义了两个产品变体：“demo”和“full”。由于“demo”产品变体将 versionName 定义为“1.1-demo”，因此“demo”构建使用此 versionName 而不是默认值。“full”产品变体代码块未定义 versionName，因此它使用默认值“1.1”。

注意：如果您的应用直接在 <manifest> 元素中定义应用版本，Gradle 构建文件中的版本值会覆盖清单中的设置。此外，在 Gradle 构建文件中定义这些设置允许您为应用的不同版本指定不同的值。为了获得更高的灵活性并避免在清单合并时发生潜在的覆盖，请从 <manifest> 元素中移除这些属性，改在 Gradle 构建文件中定义您的版本设置。

Android 框架提供了一个 API，允许您查询系统以获取有关您应用的版本信息。要获取版本信息，请使用 PackageManager.getPackageInfo(java.lang.String, int) 方法。

指定 API 级别（SDK 版本）要求

如果您的应用需要特定最低版本的 Android 平台，您可以将该版本要求指定为应用 build.gradle 或 build.gradle.kts 文件中的 API 级别设置。在构建过程中，这些设置会合并到您应用的清单文件中。指定 API 级别要求可确保您的应用只能安装在运行兼容版本 Android 平台的设备上。

注意：如果您直接在应用的清单文件中指定 API 级别要求，构建文件中的相应设置会覆盖清单文件中的设置。此外，在 Gradle 构建文件中定义这些设置允许您为应用的不同版本指定不同的值。为了获得更高的灵活性并避免在清单合并时发生潜在的覆盖，请从 <uses-sdk> 元素中移除这些属性，改在 Gradle 构建文件中定义您的 API 级别设置。

有两个可用的 API 级别设置：

  • minSdk — 应用运行所需的最低 Android 平台版本，由平台的 API 级别标识符指定。
  • targetSdk — 应用设计运行的 API 级别，与 <SDK_INT> 常量挂钩。在某些情况下，这允许应用使用目标 API 级别中定义的清单元素或行为，而不是仅限于使用最低 API 级别定义的那些。

    • 无法指定应用目标或要求的次要 SDK 版本。要安全地调用比您的 minSdkVersion 要求更高主要或次要 SDK 版本的新 API，您可以使用 SDK_INT_FULL 常量通过检查次要或主要发布版本来保护代码块。

    if (SDK_INT_FULL >= VERSION_CODES_FULL.[MAJOR or MINOR RELEASE]) {
  // Use APIs introduced in a major or minor SDK version
}

要在 build.gradle 或 build.gradle.kts 文件中指定默认 API 级别要求，请将一个或多个 API 级别设置添加到嵌套在 android {} 代码块内的 defaultConfig{} 代码块中。您还可以通过将设置添加到构建类型或产品变体中，为应用的不同版本覆盖这些默认值。

以下文件在 defaultConfig {} 代码块中指定了默认的 minSdk 和 targetSdk 设置，并为一个产品变体覆盖了 minSdk。

Groovy

android {
    ...
    defaultConfig {
        ...
        minSdk 21
        targetSdk 33
    }
    productFlavors {
        main {
            ...
        }
        afterNougat {
            ...
            minSdk 24
        }
    }
}

Kotlin

android {
    ...
    defaultConfig {
        ...
        minSdk = 21
        targetSdk = 33
    }
    productFlavors {
        create("main") {
            ...
        }
        create("afterNougat") {
            ...
            minSdk = 24
        }
    }
}

在准备安装您的应用时，系统会检查这些设置的值并将它们与系统版本进行比较。如果 minSdk 值大于系统版本，系统将阻止安装该应用。

如果您未指定这些设置，系统将假定您的应用与所有平台版本兼容。这等同于将 minSdk 设置为 1。

有关更多信息，请参阅 什么是 API 级别？。有关 Gradle 构建设置，请参阅 配置构建变体。