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 中的 File > Project Structure > Project 菜单中指定插件版本，也可以在顶级 build.gradle.kts 文件中指定。插件版本适用于在该 Android Studio 项目中构建的所有模块。以下示例在 build.gradle.kts 文件中将插件设置为版本 8.10.0

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 菜单栏中点击 File > Sync Project with Gradle Files 时下载它。

更新 Gradle

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

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

插件版本最低所需 Gradle 版本
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 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 Feature Drop | 2025.1.2 4.0-8.12
Narwhal | 2025.1.1 3.2-8.11
Meerkat Feature Drop | 2024.3.2 3.2-8.10
Meerkat | 2024.3.1 3.2-8.9
Ladybug Feature Drop | 2024.2.2 3.2-8.8
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 级别的最低工具版本

支持特定 API 级别的 Android Studio 和 AGP 存在最低版本要求。使用的 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 Feature Drop | 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 Build Tools 35.0.0 35.0.0 安装或配置 SDK Build Tools。
NDK 不适用 27.0.12077973 安装或配置不同版本的 NDK。
JDK 17 17 如需了解更多信息，请参阅设置 JDK 版本。

已修复的问题

Android Gradle 插件 8.10.0

已修复的问题
Android Gradle 插件
AGP 应该声明它支持即将发布的 API 35
启用统计信息时，AndroidComponentsExtension.addSourceSetConfigurations 功能损坏
在 AGP 8.8.0 中使用 isolated project 设置时，项目 ':app' 无法访问 'Project.group' 和 'Project.version'
初始化脚本 'C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle' 行：162
初始化脚本 'C:\Users\mypc\AppData\Local\Temp\ijresolvers2.gradle' 行：162
无法剥离以下库，按原样打包
添加对向 R8 传递“isolated splits”信息的功能支持
从 Android Studio 运行应用时，应用崩溃，出现 NoClassDefFoundError 和 ClassNotFoundException
Android Gradle 插件：避免在 PackageRenderscriptTask 和 ProcessJavaResTask 中覆盖 Sync.getDestinationDir()
为单元测试使用合并的 Java 资源
Isolated project：DeclarativeSchemaModel 序列化错误
Dexer (D8)
android.os.Build.VERSION_CODES_FULL 的向后移植对于 Baklava 不正确
AutoClosable 脱糖不再报告 ExecutorService.close 受支持
Lint
密封接口上的 `@Parcelize` 注解出现错误的 Lint 警告
AS 2024.3.1.4 编辑 Kotlin 文本时会间歇性卡顿。
CredentialManagerSignInWithGoogle 出现误报的 Lint 错误
Aligned16KB Lint 检查中出现 ConcurrentModificationException
Lint：AGP 8.10.0-alpha05 触发大量 SyntheticAccessor 误报
使在测试源代码上启用 NewApi 成为可能
在 Android Studio 中进行代码检查后，按下“LintIdeFix”按钮的效果是什么？
警告消息文本中的错误：“不必要；此处 `Build.VERSION.SDK_INT >= Build.VERSION_CODES.O` *永远*不会为 true（`SDK_INT` ≥ 26 且 < 31）”
代码缩减器 (R8)
更新到 AGP 8.9.0 后无法生成签名 APK
在分配点分析先写后读属性时，生成 classfile 时遇到错误
R8 代码缩减器 8.6.*、8.7.*、8.8.0 版本中的 Java SPI 问题
类初始化中安全转换导致的 ClassCastException
AGP 8.9 中的资源缩减问题导致动态功能模块中资源丢失
无法调用 com.android.tools.r8.internal.H5.x()

Android Gradle 插件 8.10.1

已修复的问题
Android Gradle 插件
使用 AGP 在非默认构建类型中显式启用设备测试不起作用
代码缩减器 (R8)
将 Kotlin 更新到 2.1.20 后，编译即时应用时出现 NullPointerException
[AGP]：错误：R8：java.lang.OutOfMemoryError：所需数组长度 2147483638 + 196 过大