Android Studio 构建系统基于 Gradle，Android Gradle 插件添加了一些特定于构建 Android 应用程序的功能。虽然 Android Gradle 插件 (AGP) 通常与 Android Studio 同步更新，但插件（以及 Gradle 系统的其余部分）可以独立于 Android Studio 运行，并且可以单独更新。
本页介绍如何使您的 Gradle 工具保持最新，以及最新更新中包含的内容。有关以前的 Android Gradle 插件版本的版本说明，请参阅 以前的版本说明。
要查看此版本的 Android Gradle 插件中修复了哪些问题，请参阅 已关闭的问题。
有关 Android Gradle 插件中即将发生的重大更改的概览，请参阅 Android Gradle 插件路线图。
有关如何使用 Gradle 配置 Android 构建的详细信息，请参阅以下页面
有关 Gradle 构建系统的更多信息，请参阅 Gradle 用户指南。
更新 Android Gradle 插件
更新 Android Studio 时，您可能会收到提示，要求您将 Android Gradle 插件自动更新到最新版本。您可以选择接受更新或根据项目的构建要求手动指定版本。
您可以在 Android Studio 中的**文件** > **项目结构** > **项目** 菜单或顶级 build.gradle.kts 文件中指定插件版本。插件版本适用于在该 Android Studio 项目中构建的所有模块。以下示例从 build.gradle.kts 文件将插件设置为版本 8.6.0
Kotlin
plugins {
id("com.android.application") version "8.6.0" apply false
id("com.android.library") version "8.6.0" apply false
id("org.jetbrains.kotlin.android") version "2.0.20" apply false
}
Groovy
plugins {
id 'com.android.application' version '8.6.0' apply false
id 'com.android.library' version '8.6.0' apply false
id 'org.jetbrains.kotlin.android' version '2.0.20' apply false
}
注意：您不应在版本号中使用动态依赖项，例如 'com.android.tools.build:gradle:8.6.+'。使用此功能会导致意外的版本更新，并且难以解决版本差异。
如果指定的插件版本尚未下载，Gradle 会在您下次构建项目或从 Android Studio 菜单栏中单击**文件** > **将项目与 Gradle 文件同步** 时下载它。
更新 Gradle
更新 Android Studio 时，您可能会收到提示，要求您将 Gradle 也更新到最新版本。您可以选择接受更新或根据项目的构建要求手动指定版本。
下表列出了每个版本的 Android Gradle 插件所需的 Gradle 版本。为了获得最佳性能，您应使用 Gradle 和插件的最新版本。
| 插件版本 | 最低要求的 Gradle 版本 |
|---|---|
| 8.5 | 8.7 |
| 8.4 | 8.6 |
| 8.3 | 8.4 |
| 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 中的**文件** > **项目结构** > **项目** 菜单中指定 Gradle 版本，或使用命令行更新您的 Gradle 版本。首选方法是使用 Gradle Wrapper 命令行工具，该工具会更新 gradlew 脚本。以下示例使用 Gradle Wrapper 将 Gradle 版本设置为 8.6。请注意，您需要运行此命令两次才能升级 Gradle 本身和 Gradle Wrapper 本身（有关更多信息，请参阅 升级 Gradle Wrapper）。
gradle wrapper --gradle-version 8.6
但是，这在某些情况下可能会失败，例如，如果您刚刚更新了 AGP 并且它不再与当前 Gradle 版本兼容。在这种情况下，您需要编辑 gradle/wrapper/gradle-wrapper.properties 文件中的 Gradle 分发引用。以下示例在 gradle-wrapper.properties 文件中将 Gradle 版本设置为 8.6。
...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.6-bin.zip
...
Android Gradle 插件和 Android Studio 兼容性
Android Studio 构建系统基于 Gradle，而 Android Gradle 插件 (AGP) 添加了几个专门用于构建 Android 应用的功能。下表列出了每个 Android Studio 版本所需的 AGP 版本。
| Android Studio 版本 | 所需的 AGP 版本 |
|---|---|
| Ladybug | 2024.2.1 | 3.2-8.7 |
| Koala Feature Drop | 2024.1.2 | 3.2-8.6 |
| Koala | 2024.1.1 | 3.2-8.5 |
| Jellyfish | 2023.3.1 | 3.2-8.4 |
| 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 |
旧版本
| Android Studio 版本 | 所需的 AGP 版本 |
|---|---|
| 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 插件发行说明。
Android API 级别工具的最低版本
Android Studio 和 AGP 的最低版本支持特定的 API 级别。使用低于项目 targetSdk 或 compileSdk 所需的 Android Studio 或 AGP 版本可能会导致意外问题。我们建议使用最新的 Android Studio 和 AGP 预览版来处理面向 Android 操作系统预览版的项目。您可以 将 Android Studio 预览版与稳定版一起安装。
Android Studio 和 AGP 的最低版本如下所示
| API 级别 | Android Studio 最低版本 | AGP 最低版本 |
|---|---|---|
| VanillaIceCream 预览版 | Jellyfish | 2023.3.1 | 8.4 |
| 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 将在大约一年后的下一个主要更新中被删除。
兼容性
Android Gradle 插件 8.6 支持的最高 API 级别为 API 级别 34。以下是其他兼容性信息
| 最低版本 | 默认版本 | 备注 | |
|---|---|---|---|
| Gradle | 8.7 | 8.7 | 要了解详细信息，请参阅 更新 Gradle。 |
| SDK 构建工具 | 34.0.0 | 34.0.0 | 安装 或 配置 SDK 构建工具。 |
| NDK | N/A | 26.1.10909125 | 安装 或 配置 不同版本的 NDK。 |
| JDK | 17 | 17 | 要了解详细信息，请参阅 设置 JDK 版本。 |
以下是 Android Gradle 插件 8.6 中的新功能。
Android Gradle 插件中的 Kotlin 测试夹具支持
从 Android Gradle 插件 8.5.0-beta01 开始，您现在可以在 testFixtures 源代码中使用 Kotlin。以前，testFixtures 源代码仅支持 Java。
要使用此功能，请执行以下操作。
- 确保您使用的是 Kotlin 1.9.20 或更高版本。
- 将
android.experimental.enableTestFixturesKotlinSupport=true添加到您的gradle.properties文件中。 在您的模块的
build.gradle.kts或build.gradle文件中添加对 Kotlin 标准库的显式依赖项dependencies { testFixturesImplementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.20") }
已知限制：测试夹具目前不支持 KAPT 或 KSP。