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 文件中指定。该插件版本适用于在相应 Android Studio 项目中构建的所有模块。以下示例从 build.gradle 文件中将插件的版本号设置为 7.4.1：

Groovy

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

Kotlin

plugins {
    id("com.android.application") version "7.4.1" apply false
    id("com.android.library") version "7.4.1" 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.18.0
8.08.0
7.47.5
7.37.4
7.27.3.3
7.17.2
7.07.0
4.2.0+6.7.1

旧版

插件版本所需的 Gradle 版本
4.1.0+6.5+
4.0.0+6.1.1+
3.6.0 - 3.6.45.6.4+
3.5.0 - 3.5.45.4.1+
3.4.0 - 3.4.35.1.1+
3.3.0 - 3.3.34.10.1+
3.2.0 - 3.2.14.6+
3.1.0+4.4+
3.0.0+4.1+
2.3.0+3.3+
2.1.3 - 2.2.32.14.1 - 3.5
2.0.0 - 2.1.22.10 - 2.13
1.5.02.2.1 - 2.13
1.2.0 - 1.3.12.2.1 - 2.9
1.0.0 - 1.1.32.2.1 - 2.3

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

gradle wrapper --gradle-version 7.5.1

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

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

Android Gradle 插件和 Android Studio 兼容性

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

Android Studio 版本 所需插件版本
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
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 插件版本说明。

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

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

重要变更如下：

  • AGP 现在将使用语义版本控制，并且重大变更将在主要版本中发布。

  • 每年将发布一个 AGP 主要版本，与 Gradle 主要版本保持一致。

  • AGP 4.2 之后的版本为版本 7.0，并且会要求升级到 Gradle 7.x 版。AGP 的每个主要版本都会要求在底层 Gradle 工具中进行主要版本升级。

  • API 将提前大约一年废弃，同时提供替代功能。废弃的 API 将在大约一年后的下次重大更新期间移除。

7.4.0（2022 年 12 月）

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

兼容性

最低版本 默认版本 备注
Gradle 7.5 7.5 如需了解详情，请参阅更新 Gradle。
SDK Build Tools 30.0.3 30.0.3 安装或配置 SDK Build Tools。
NDK 不适用 23.1.7779620 安装或配置其他版本的 NDK。
JDK 11 11 如需了解详情，请参阅设置 JDK 版本。

补丁版本

以下是 Android Gradle 插件 7.4 的补丁版本列表。

Android Gradle 插件 7.4.2（2023 年 2 月）

本次要更新包含以下 bug 修复：

修复的问题
DexingFileDependenciesTask.outputKeepRules 是一个目录，但已被标记为 OutputFile
更新到 7.4 Beta 1 时出现 AnnotationProcessorOptions.arguments are queried 错误
测试变体中的清单占位符导致 processDebugUnitTestManifest 失败

Android Gradle 插件 7.4.1（2023 年 2 月）

本次要更新包含以下 bug 修复：

修复的问题
从 destination 属性迁移到 outputLocation 属性，以解决废弃警告问题并为 Gradle 9.0 做好准备
AGP 7.4.0-rc01 会破坏 Variant API，并显示“Querying the mapped value of map(provider(java.util.Set)) before task '...' has completed is not supported”

AGP 升级助理升级后报告和回滚功能

AGP 升级助理现在包含升级后报告。此报告介绍了已完成的步骤以及升级是成功还是失败。它还包含一项操作，如果在升级后构建或测试项目时遇到问题，用来还原由升级助理所做的更改。

项目导入作业并行运行

现在，当您使用 Gradle 7.4.2 或更高版本以及 Android Gradle 插件 7.2.0 或更高版本时，Studio IDE 会并行导入项目。具体而言，当 Android Studio 触发 Gradle 同步时，系统将并行创建用于描述 build 中所含项目的信息。这通常能加快同步过程，对于较大的项目，尤为如此。基准测试表明，为一个大型项目（包含 3,500 个 Gradle 子项目）构建 Gradle 模型所需的时间缩短了 50%，从 10 分钟缩短为 5 分钟。

Android Gradle 插件适用于 JVM 11 字节码

从 Android Gradle 插件 7.4.0-alpha04 开始，AGP 附带 JVM 11 字节码。这意味着，如果您针对 AGP 进行编译或编写自定义 lint 检查，则需要开始以 JVM 11 字节码为目标适用对象。其中一种方法是在模块级 build.gradle 文件中添加以下代码：

sourceCompatibility = "11"
targetCompatibility = "11"
上一页
SDK 构建工具
下一页
Android Gradle 插件路线图