关于 Android Gradle 插件

Android Studio 构建系统以 Gradle 为基础，并且 Android Gradle 插件添加了几项专用于构建 Android 应用的功能。

本页将介绍如何让 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 文件中将插件的版本号设置为 9.0：

Kotlin

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

Groovy

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

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

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

更新 Gradle

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

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

插件版本所需的最低 Gradle 版本
9.09.1.0
8.138.13
8.128.13
8.118.13
8.108.11.1
8.98.11.1
8.88.10.2
8.78.9
8.68.7
8.58.7
8.48.6
8.38.4
8.28.2
8.18.0
8.08.0

旧版

插件版本所需的 Gradle 版本
7.47.5
7.37.4
7.27.3.3
7.17.2
7.07.0
4.2.0+6.7.1
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 的版本设置为 9.1.0。请注意，您需要运行此命令两次来升级 Gradle 和 Gradle 封装容器本身（如需了解详情，请参阅升级 Gradle 封装容器）。 

gradle wrapper --gradle-version 9.1.0

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

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

Android Gradle 插件和 Android Studio 兼容性

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

Android Studio 版本 所需的 AGP 版本
Otter 3 功能更新 | 2025.2.3 4.0-9.0
Otter 2 功能更新 | 2025.2.2 4.0-8.13
Otter | 2025.2.1 4.0-8.13
Narwhal 4 功能更新 | 2025.1.4 4.0-8.13
Narwhal 3 功能更新 | 2025.1.3 4.0-8.13
Narwhal 功能更新 | 2025.1.2 4.0-8.12
Narwhal | 2025.1.1 3.2-8.11
Meerkat 功能更新 | 2024.3.2 3.2-8.10
Meerkat | 2024.3.1 3.2-8.9

旧版

Android Studio 版本 所需的 AGP 版本
Ladybug 功能更新 | 2024.2.2 3.2-8.8
Ladybug | 2024.2.1 3.2-8.7
Koala 功能更新 | 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
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 级别。如果使用的 Android Studio 或 AGP 版本低于项目的 targetSdk 或 compileSdk 所要求的版本，可能会导致意外问题。我们建议您使用最新的预览版 Android Studio 和 AGP 来处理以预览版 Android OS 为目标平台的项目。您可以安装 Android Studio 的预览版以及稳定版。

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

API 级别 最低 Android Studio 版本 最低 AGP 版本
36.1 Narwhal 3 功能更新 | 2025.1.3 8.13.0
36.0 Meerkat | 2024.3.1 Patch 1 8.9.1
35 Koala 功能更新 | 2024.2.1 8.6.0
34 Hedgehog | 2023.1.1 8.1.1
33 Flamingo | 2022.2.1 7.2