Android Gradle 插件 8.3 版本说明

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

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

更新 Android Gradle 插件

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

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

Kotlin

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

Groovy

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

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

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

更新 Gradle

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

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

插件版本所需的最低 Gradle 版本
8.4(Alpha 版)8.6-rc-1
8.38.4
8.28.2
8.18.0
8.08.0
7.47.5

旧版

插件版本所需的 Gradle 版本
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 版本设置为 8.3。 请注意,您需要运行此命令两次来升级 Gradle 和 Gradle 封装容器本身(如需了解详情,请参阅升级 Gradle 封装容器)。

gradle wrapper --gradle-version 8.3

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

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

Android Gradle 插件和 Android Studio 兼容性

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

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

旧版

Android Studio 版本 所需的 AGP 版本
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 版本低于项目的 targetSdkcompileSdk 所要求的版本,可能会导致意外问题。我们建议您使用最新的预览版 Android Studio 和 AGP 来处理以预览版 Android OS 为目标平台的项目。您可以安装 Android Studio 的预览版以及稳定版

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

API 级别 最低 Android Studio 版本 最低 AGP 版本
VanillaIceCream 预览 水母 | 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.3 支持的最高 API 级别为 API 级别 34。下面是其他兼容性信息:

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

以下是 Android Gradle 插件 8.3 中的新功能。

支持 Gradle 版本目录

Android Studio 支持基于 TOML 的 Gradle 版本目录,借助此功能,您可以在一个集中位置管理依赖项,并跨模块或项目共享依赖项。Android Studio 现在可让您通过编辑器建议以及与 Project Structure 对话框集成来更轻松地配置版本目录。了解如何设置和配置 Gradle 版本目录或如何将 build 迁移到版本目录

代码补全和导航

当您以 TOML 文件格式修改版本目录或将依赖项从版本目录添加到 build 文件时,Android Studio 会提供代码补全功能。如需使用代码补全功能,请按 Ctrl + 空格键(在 macOS 中,按 Command + 空格键)。此外,您还可以按 Ctrl+b(在 macOS 中,按 Command+b)快速从应用的 build.gradle 文件中的依赖项引用导航到版本目录中声明的位置。

添加依赖项时的代码补全功能

与“Project Structure”对话框集成

如果您的项目使用以 TOML 文件格式定义的版本目录,您可以在 Android Studio 中通过 Project Structure 对话框的 Variables 视图 (File > Project Structure > Variables) 修改已在其中定义的变量。 每个版本目录都有一个下拉列表,其中列出了该目录中的变量。若要修改变量,请点击其值,然后覆盖它。保存这些更改后,TOML 文件会进行相应的更新。

“Project Structure”对话框中版本目录中的变量

您还可以在 Project Structure 对话框的 Dependencies 视图 (File > Project Structure > Dependencies) 中更新依赖项。如需使用 Project Structure 对话框更新版本,请找到要修改的模块和依赖项,然后更新 Requested Version 字段。保存这些更改后,TOML 文件会进行相应的更新。请注意,如果依赖项版本是使用变量定义的,则直接以这种方式更新版本会将该变量替换为硬编码值。另请注意,无论您是否使用 Project Structure 对话框,从 build 文件中移除某个依赖项并不会从版本目录中移除该依赖项。

“Project Structure”对话框中版本目录中的依赖项

已知问题和限制

以下是 Android Studio 中的 Gradle 版本目录支持的已知问题或限制。

  • 突出显示 Kotlin 脚本文件中的插件别名声明时出错:如果您添加 alias(libs.plugins.example) 形式的插件声明,编辑器会在 libs 部分下方添加一条红色下划线。这是 Gradle 8.0 及更低版本中的已知问题,并将在未来的 Gradle 版本中解决。

  • Android Studio 仅支持 TOML 格式的版本目录:目前,Android Studio 代码补全、导航和“Project Structure”对话框支持仅适用于以 TOML 文件格式定义的版本目录。不过,您仍然可以直接在 settings.gradle 文件中添加版本目录,并在项目中使用其依赖项。

  • 不支持 KTS build 文件导航:对于使用 Kotlin 脚本编写的 build 文件,尚不支持使用 Ctrl + 点击键(在 macOS 上,按 Command + 点击)前往版本目录中的依赖项定义。

  • Firebase Assistant 直接在构建脚本中添加依赖项:Firebase Assistant 可直接将依赖项添加到您的构建脚本中,而不是通过版本目录添加。

  • 不支持“Find usages”功能:尚不支持在其他 build 文件中查找版本目录变量的使用情况,无论 build 文件是在 KTS 中还是 Groovy 中。也就是说,在版本目录中的变量定义上按住 Ctrl + 点击(在 macOS 上,按住 Command + 点击)不会转到使用该变量的 build 文件。

  • Android Studio 中的“Project Structure”对话框会显示多个目录文件(如果这些文件位于根 gradle 文件夹中),但不显示复合 build 的目录。例如,如果您有两个目录文件,一个用于应用,一个用于复合 build,则“Project Structure”对话框仅显示应用目录文件。您可以使用复合 build,但必须直接修改其 TOML 文件。

更多 SDK 数据分析:政策问题

对于在 Google Play SDK 索引中违反 Play 政策的公共 SDK,Android Studio 会在 build.gradle.ktsbuild.gradle 文件以及“Project Structure”对话框中显示 lint 警告。您应更新所有违反 Play 政策的依赖项,因为这些违规行为可能会导致您日后无法将应用发布到 Google Play 管理中心。这些违反政策警告是对 Android Studio 显示的过时版本警告的补充。

Android Studio compileSdk 版本支持

如果您的项目使用的 compileSdk 不受 Android Studio 当前版本支持,Android Studio 会显示警告。此外,我们还建议您改用支持项目所用 compileSdk 的 Android Studio 版本(如果有)。请注意,升级 Android Studio 可能还需要升级 AGP。如果当前版本的 AGP 不支持项目使用的 compileSdk,AGP 还会在 Build 工具窗口中显示警告。

Lint 行为变更

从 Android Gradle 插件 8.3.0-alpha02 开始,在模块上运行 lint 时,系统会针对该模块的主要组件和测试组件运行单独的 lint 分析任务。我们进行这项更改是为了提高性能。 如需还原到之前的行为,请在 gradle.properties 文件中设置 android.experimental.lint.analysisPerComponent=false