Android Gradle 插件 8.9 版本说明

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

重要提示：如需查看详细的 Android Gradle 插件 API 废弃和移除日志，请参阅 Android Gradle 插件 API 更新。

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 build，请参阅以下页面：

• 配置 build
• Android Gradle 插件 DSL 参考文档
• Gradle DSL 参考文档
• Gradle 性能用户指南

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

更新 Android Gradle 插件

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

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

KotlinGroovy

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

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

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

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

更新 Gradle

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

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

插件版本	所需的最低 Gradle 版本
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
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.9。请注意，您需要运行此命令两次来升级 Gradle 和 Gradle 封装容器本身（如需了解详情，请参阅升级 Gradle 封装容器）。

gradle wrapper --gradle-version 8.9

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

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

Android Gradle 插件和 Android Studio 兼容性

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

如果您的项目不受某个特定版本的 Android Studio 支持，您仍然可以使用旧版 Android Studio 打开和更新项目。

Android Studio 版本	所需的 AGP 版本
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 版本
Baklava 预览	Meerkat | 2024.3.1	8.9.0
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.9 支持的 API 级别上限为 API 级别 35。以下是其他兼容性信息：

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

修复的问题

Android Gradle 插件 8.9.0

已修复的问题
Android Gradle 插件	问题 331016661 当 GMD 设置任务因磁盘空间不足而失败时，提供有实用价值的错误消息 问题 317358817 com.android.settings 插件不识别 targetSdk 问题 373478537 无用的错误“未指定 compileSdkVersion。Please add it to build.gradle" 问题 378314205 “Build”菜单中缺少“Clean build” 问题 340315591 或许可以让 AGP 的内置 Kotlin 支持自动添加 kotlin stdlib 依赖项 问题 338596003 更新了 shouldConfigureKotlinPlatformAttribute，以处理内置的 Kotlin 支持 问题 378724144 在 `checkTestedAppObfuscationRelease` 的错误消息中提供 Kotlin Gradle 语法 问题 383184394 修复了未解析依赖项时可能出现的融合库错误 问题 380110863 gradle.properties 中的系统属性不会传递到单独进程中的 R8 Gradle Worker 问题 241582907 将 BuiltArtifact.outputFile 设为文件类型 问题 383182777 未在融合库中提供命名空间时，系统未提供合适的错误消息 问题 196209595 AGP 7.1.0-alpha08 中的 lint 选项不允许使用标准输出 问题 317215060 Android Gradle 插件：变体应公开源代码集名称 问题 379657438 配置缓存对 TERM 环境变量的设置非常脆弱 问题 393189008 启用统计信息后，AndroidComponentsExtension.addSourceSetConfigurations 会损坏 问题 394384907 初始化脚本“C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle”第 162 行 问题 393189008 启用统计信息后，AndroidComponentsExtension.addSourceSetConfigurations 会损坏
Dexer (D8)	问题 395140848 java.lang.VerifyError: Verifier rejected class: [0x430] copy1 v2<-v264 type=Undefined cat=3
lint	问题 377475534 运行 Lint Gradle 检查时 lint 会崩溃 问题 377642757 lint 失败并抛出 InstantiationException，但 lint 堆栈轨迹中没有异常消息 问题 375352607 lint 检查误报：android.permission.SCHEDULE_EXACT_ALARM 仅授予系统应用 问题 370343337 应将 StringFormatInvalid 检查应用于 Compose stringResource 方法 问题 374896332 RequiresFeature 注解不适用于 Kotlin 文件 问题 376498180 kotlin android.os.Handler removeCallbacks Runnable 问题 378128668 使用 shift 对常量进行定义时，出现 WrongConstant lint 错误 问题 370778975 WrongConstant lint 出现两次 问题 381126163 在 API 26 以下使用不受支持的 Java nio API 时出现运行时异常（没有 lint 错误） 问题 382253664 lint 会阻止使用 RequiresApi，即使是在测试中的私有辅助方法中也是如此 问题 360354551 在 Android Studio 中使用 .hasRoute(Route::class) 时，K2 模式会抛出 RestrictedApi 警告 问题 382043552 lint 建议将测试中的 @RequiresExtension 替换为 @SdkSuppress，后者不支持 SDK 扩展 问题 383595384 当 FrameLayout 与 fitSystemWindows 搭配使用来封装需要自定义内边距的子 RelativeLayout 时，Lint 会错误地报告不必要的嵌套布局。 问题 383595395 CoarseFineLocation lint 规则未考虑 maxSdkVersion 属性 问题 385875832 lint 8.7.3 中的 AppLinkSplitToWebAndCustom 是 UnknownIssue 问题 387281249 lint 检查 StringEscapeDetector 在“\\”上崩溃 问题 389023409 针对密封接口上的“@Parcelize”注解显示错误的 lint 警告 问题 382396705 在编辑 Kotlin 文本时，AS 2024.3.1.4 会间歇性挂起。
lint 集成	问题 383661626 构建 app bundle 时，lintVitalRelease 不会自动运行
缩减器 (R8)	问题 394185143 升级到 AGP 8.8 后，Gson Proguard 无法正常运行 问题 391417819 java.lang.VerifyError: Verifier rejected class 问题 395489597 使用 AGP 8.10.0-alpha04 中包含的 R8 进行缩减时，Leanback 会崩溃