此页面由 Cloud Translation API 翻译。

Android Gradle 插件版本说明

JCenter 代码库已于 2021 年 3 月 31 日变为只读代码库。如需了解详情，请参阅 JCenter 服务更新。

Android Studio 构建系统以 Gradle 为基础，并且 Android Gradle 插件添加了几项专用于构建 Android 应用的功能。虽然 Android 插件通常会与 Android Studio 的更新步调保持一致，但插件（以及 Gradle 系统的其余部分）可独立于 Android Studio 运行并单独更新。

本页将介绍如何让 Gradle 工具保持最新状态，以及最近的更新包含哪些内容。如需查看 Android Gradle 插件过往版本的版本说明，请参阅过往版本说明。

如需简要了解即将针对 Android Gradle 插件进行的重大变更，请参阅 Android Gradle 插件路线图。

如需详细了解如何使用 Gradle 配置 Android build，请参阅以下页面：

如需详细了解 Gradle 构建系统，请参阅 Gradle 用户指南。

更新 Android Gradle 插件

在更新 Android Studio 时，您可能会收到将 Android Gradle 插件自动更新为最新可用版本的提示。您可以选择接受该更新，也可以根据项目的构建要求手动指定版本。

您可以在 Android Studio 的 File > Project Structure > Project 菜单中指定插件版本，也可以在顶级 build.gradle.kts 文件中指定。该插件版本适用于在相应 Android Studio 项目中构建的所有模块。以下示例从 build.gradle.kts 文件中将插件的版本号设置为 8.1.0：

Kotlin

plugins {
    id("com.android.application") version "8.1.0" apply false
    id("com.android.library") version "8.1.0" apply false
    id("org.jetbrains.kotlin.android") version "1.5.31" apply false
}

Groovy

plugins {
    id 'com.android.application' version '8.1.0' apply false
    id 'com.android.library' version '8.1.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.5.31' apply false
}

注意：不应在版本号中使用动态依赖项（如 'com.android.tools.build:gradle:2.+'）。使用此功能可能会导致意外的版本更新，而且难以解析版本差异。

如果指定的插件版本尚未下载，则 Gradle 会在您下次构建项目时进行下载；或者，您也可以在 Android Studio 菜单栏中依次点击 File > Sync Project with Gradle Files 进行下载。

更新 Gradle

在更新 Android Studio 时，您可能会收到一并将 Gradle 更新为最新可用版本的提示。您可以选择接受该更新，也可以根据项目的构建要求手动指定版本。

下表列出了各个 Android Gradle 插件版本所需的 Gradle 版本。为了获得最佳性能，您应使用 Gradle 和插件这两者的最新版本。

插件版本	所需的最低 Gradle 版本
8.3	8.3
8.2	8.2
8.1	8.0
8.0	8.0
7.4	7.5

旧版

插件版本	所需的 Gradle 版本
7.3	7.4
7.2	7.3.3
7.1	7.2
7.0	7.0
4.2.0+	6.7.1
4.1.0+	6.5+
4.0.0+	6.1.1+
3.6.0 - 3.6.4	5.6.4+
3.5.0 - 3.5.4	5.4.1+
3.4.0 - 3.4.3	5.1.1+
3.3.0 - 3.3.3	4.10.1+
3.2.0 - 3.2.1	4.6+
3.1.0+	4.4+
3.0.0+	4.1+
2.3.0+	3.3+
2.1.3 - 2.2.3	2.14.1 - 3.5
2.0.0 - 2.1.2	2.10 - 2.13
1.5.0	2.2.1 - 2.13
1.2.0 - 1.3.1	2.2.1 - 2.9
1.0.0 - 1.1.3	2.2.1 - 2.3

您可以在 Android Studio 的 File > Project Structure > Project 菜单中指定 Gradle 版本，也可以使用命令行更新 Gradle 版本。首选方法是使用 Gradle 封装容器命令行工具，该工具可更新 gradlew 脚本。以下示例使用 Gradle 封装容器将 Gradle 的版本设置为 8.1。请注意，您需要运行此命令两次来升级 Gradle 和 Gradle 封装容器本身（如需了解详情，请参阅升级 Gradle 封装容器）。

gradle wrapper --gradle-version 8.1

不过，此操作在某些情况下可能会失败，例如您刚刚更新了 AGP，导致其不再与当前 Gradle 版本兼容。在这种情况下，您需要修改 gradle/wrapper/gradle-wrapper.properties 文件中的 Gradle 分发引用。以下示例在 gradle-wrapper.properties 文件中将 Gradle 的版本设置为 8.1。

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.1-bin.zip
...

Android Gradle 插件和 Android Studio 兼容性

Android Studio 构建系统以 Gradle 为基础，并且 Android Gradle 插件 (AGP) 添加了几项专用于构建 Android 应用的功能。下表列出了各个 Android Studio 版本所需的 AGP 版本。

Android Studio 版本	所需的 AGP 版本
Iguana \| 2023.2.1	3.2-8.3
Hedgehog \| 2023.1.1	3.2-8.2
Giraffe \| 2022.3.1	3.2-8.1
Flamingo \| 2022.2.1	3.2-8.0
Electric Eel \| 2022.1.1	3.2-7.4

旧版

Android Studio 版本	所需的 AGP 版本
Dolphin \| 2021.3.1	3.2-7.3
Chipmunk \| 2021.2.1	3.2-7.2
Bumblebee \| 2021.1.1	3.2-7.1
Arctic Fox \| 2020.3.1	3.1-7.0

如需了解 Android Gradle 插件的新变化，请参阅 Android Gradle 插件版本说明。

适用于 Android API 级别工具的最低版本

Android Studio 和 AGP 有支持特定 API 级别的最低版本。如果使用版本低于项目的 targetSdk 或 compileSdk 所要求的 Android Studio 或 AGP，可能会导致意外问题。对于以预览版 Android OS 为目标平台的项目，我们建议使用最新预览版的 Android Studio 和 AGP。您可以安装 Android Studio 的预览版和稳定版。

Android Studio 和 AGP 的最低版本如下所示：

API 级别	Android Studio 最低版本	最低 AGP 版本
34	Hedgehog \| 2023.1.1	8.1.1
33	Flamingo \| 2022.2.1	7.2

版本编号变更（2020 年 11 月）

我们将更新 Android Gradle 插件 (AGP) 的版本号，以使其更接近底层 Gradle 构建工具。

重要变更如下：

AGP 现在将使用语义版本控制，并且重大变更将在主要版本中发布。
每年将发布一个 AGP 主要版本，与 Gradle 主要版本保持一致。
AGP 4.2 之后的版本为版本 7.0，并且会要求升级到 Gradle 7.x 版。AGP 的每个主要版本都会要求在底层 Gradle 工具中进行主要版本升级。
API 将提前大约一年废弃，同时提供替代功能。弃用的 API 将在大约一年后的下次主要版本更新期间移除。

8.1.0（2023 年 7 月）

Android Gradle 插件 8.1.0 是一个主要版本，包含各种新功能和改进。

兼容性

	最低版本	默认版本	备注
Gradle	8.0	8.0	如需了解详情，请参阅更新 Gradle。
SDK Build Tools	33.0.1	33.0.1	安装或配置 SDK Build Tools。
NDK	N/A	25.1.8937393	安装或配置其他版本的 NDK。
JDK	17	17	如需了解详情，请参阅设置 JDK 版本。

Kotlin DSL 是 build 配置的默认类型

新项目现在默认使用 Kotlin DSL (build.gradle.kts) 进行 build 配置。它具有语法突出显示、代码补全以及导航到声明的功能，可提供比 Groovy DSL (build.gradle) 更出色的修改体验。请注意，如果您使用 AGP 8.1 和 Kotlin DSL 进行 build 配置，则应使用 Gradle 8.1 以获得最佳体验。如需了解详情，请参阅 Kotlin DSL 迁移指南。

按应用自动设定语言支持

从 Android Studio Giraffe Canary 7 和 AGP 8.1.0-alpha07 开始，您可以将应用配置为自动支持各应用语言偏好设定。Android Gradle 插件会根据您的项目资源生成 LocaleConfig 文件，并在最终清单文件中添加对该文件的引用，这样您就不必再手动进行此操作。AGP 使用应用模块的 res 文件夹中的资源以及任何库模块依赖项来确定要在 LocaleConfig 文件中添加的语言区域。

请注意，各应用自动语言功能支持搭载 Android 13（API 级别 33）或更高版本的应用。如需使用此功能，您必须将 compileSdkVersion 设为 33 或更高版本。如需为之前版本的 Android 配置各应用语言偏好设定，您仍然需要使用 API 和应用内语言选择器。

如需启用各应用自动语言支持，请指定默认语言区域：

在应用模块的 res 文件夹中，创建一个名为 resources.properties 的新文件。
在 resources.properties 文件中，使用 unqualifiedResLocale 标签设置默认语言区域。将语言代码与可选的脚本代码和区域代码（使用短划线将各部分隔开）组合在一起即可构成语言区域名称：
- 语言：使用由两个或三个字母组成的 ISO 639-1 代码。
- 脚本（可选）：使用 ISO 15924 代码。
- 区域（可选）：使用由两个字母组成的 ISO 3166-1-alpha-2 代码或三位数的 UN_M.49 代码。
例如，如果您的默认语言区域是美式英语：
```
    unqualifiedResLocale=en-US
    
```

AGP 会将此默认语言区域和您指定的所有其他语言区域（使用 res 文件夹中的 values-* 目录）添加到自动生成的 LocaleConfig 文件中。

默认情况下，各应用自动语言支持功能处于关闭状态。如需开启此功能，请在模块级 build.gradle.kts 文件（如果您使用的是 Groovy，则为 build.gradle 文件）的 androidResources {} 代码块中使用 generateLocaleConfig 设置：

Kotlin

android {
  androidResources {
    generateLocaleConfig = true
  }
}

Groovy

android {
  androidResources {
    generateLocaleConfig true
  }
}

Android Lint 包含以 JVM 17 为目标的字节码

从 AGP 8.1.0-alpha04 开始，Android Lint 包含以 JVM 17 为目标的字节码。如果您编写自定义 lint 检查，则需要使用 JDK 17 或更高版本进行编译，并在 Kotlin 编译器选项中指定 jvmTarget = '17'。

如需详细了解 lint 工具，请参阅使用 lint 检查改进您的代码。

原生库压缩设置已移至 DSL

从 AGP 8.1.0-alpha10 开始，如果您不使用 DSL（而非清单）配置原生库压缩功能，则会收到警告。以下指南介绍了如何更新配置以使用 DSL。如需获取进行这些更新方面的帮助，请使用 AGP 升级助理 (Tools > AGP Upgrade Assistant)。

如需使用未压缩的原生库，请从清单中移除 android::extractNativeLibs 属性，并将以下代码添加到模块级 build.gradle.kts 文件（如果您使用的是 Groovy，则为 build.gradle 文件）：

Kotlin

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging = false
    }
  }
}

Groovy

android {
  packagingOptions {
    jniLibs {
      useLegacyPackaging false
    }
  }
}

实验性 build 标志

这些是 AGP 8.1 中提供的用于配置 build 的实验性标志。

举报	添加于	默认值	备注
`android.experimental.useDefaultDebugSigningConfigForProfileableBuildtypes`	AGP 8.0	`false`	如果在未指定签名配置的情况下启用此选项，会导致 AGP 在运行可分析或可调试的 build 时使用默认的调试签名配置。此标志默认处于停用状态，以鼓励 build 作者声明特定的分析签名配置。
`android.experimental.library.desugarAndroidTest`	AGP 8.0	`false`	此标志可让库构建器为测试 APK 启用核心库脱糖，而不会影响生成的 AAR（例如通过 lint 检查）。我们计划最终在 Variant API 中支持此行为。
`android.experimental.testOptions.managedDevices.customDevice`	AGP 8.0	`false`	启用后，Gradle 管理的设备允许使用插件提供的用户定义的自定义设备类型。如果要使用 Firebase Test Lab 插件，必须启用此标志。
`android.lint.printStackTrace`	AGP 8.0	`false`	启用后，Android lint 会在崩溃时输出堆栈轨迹。此标志与 `LINT_PRINT_STACKTRACE` 环境变量具有相同的功能。
`android.experimental.testOptions.managedDevices.maxConcurrentDevices`	AGP 8.0	无	指定在任何时间点处于活跃状态的并发 Gradle 管理设备 (AVD) 数量上限。如果值为 0 或负数，则表示设备数量没有上限。
`android.experimental.testOptions.installApkTimeout`	AGP 8.0	无	安装 APK 的超时时长（以秒为单位）。如果值为 0 或负数，UTP 会将其设为默认值。