Android Gradle 插件 8.10 发布说明

JCenter 仓库已于 2021 年 3 月 31 日变为只读。如需了解更多信息，请参阅 JCenter 服务更新。

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 项目中构建的所有模块。以下示例将插件版本设置为 8.10.0（来自 build.gradle.kts 文件）：

Kotlin

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

Groovy

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

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

如果指定的插件版本尚未下载，Gradle 将在您下次构建项目或从 Android Studio 菜单栏中点击文件 > 将项目与 Gradle 文件同步 时下载该版本。

更新 Gradle

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

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

插件版本	所需的最低 Gradle 版本
8.10	8.11.1
8.9	8.11.1
8.8	8.10.2
8.7	8.9
8.6	8.7
8.5	8.7
8.4	8.6
8.3	8.4
8.2	8.2
8.1	8.0
8.0	8.0

旧版

插件版本	所需的 Gradle 版本
7.4	7.5
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.10。请注意，您需要运行此命令两次才能升级 Gradle 和 Gradle Wrapper 本身（如需了解更多信息，请参阅升级 Gradle Wrapper）。

gradle wrapper --gradle-version 8.10

但是，在某些情况下这可能会失败，例如，如果您刚刚更新了 AGP，并且它不再符合当前的 Gradle 版本。在这种情况下，您需要编辑 gradle/wrapper/gradle-wrapper.properties 文件中的 Gradle 分发引用。以下示例将 gradle-wrapper.properties 文件中的 Gradle 版本设置为 8.10。

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

Android Gradle 插件和 Android Studio 兼容性

Android Studio 构建系统基于 Gradle，Android Gradle 插件 (AGP) 添加了多项专门用于构建 Android 应用的功能。下表列出了每个版本的 Android Studio 所需的 AGP 版本。

Android Studio 版本	所需的 AGP 版本
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
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

旧版

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 级别的最低版本。如果使用的 Android Studio 或 AGP 版本低于项目 targetSdk 或 compileSdk 所要求的版本，可能会导致意外问题。我们建议您使用最新预览版 Android Studio 和 AGP 来处理以 Android OS 预览版为目标的项目。您可以将 Android Studio 预览版与稳定版同时安装。

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

API 级别	Android Studio 最低版本	AGP 最低版本
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

版本控制变更（2020 年 11 月）

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

以下是值得注意的变更：

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

兼容性

Android Gradle 插件 8.10 支持的最高 API 级别是 API 级别 35。以下是其他兼容性信息：

	最低版本	默认版本	备注
Gradle	8.11.1	8.11.1	如需了解更多信息，请参阅更新 Gradle。
SDK 构建工具	35.0.0	35.0.0	安装或配置 SDK 构建工具。
NDK	不适用	27.0.12077973	安装或配置不同版本的 NDK。
JDK	17	17	如需了解更多信息，请参阅设置 JDK 版本。