Android Gradle 插件版本说明

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

Android Studio 构建系统以 Gradle 为基础,并且 Android Gradle 插件添加了几项专用于构建 Android 应用的功能。虽然 Android 插件通常会与 Android Studio 的更新步调保持一致,但插件(以及 Gradle 系统的其余部分)可独立于 Android Studio 运行并单独更新。

本页将介绍如何让 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 文件中进行指定。该插件版本适用于在相应 Android Studio 项目中构建的所有模块。以下示例从 build.gradle 文件中将插件的版本号设置为 7.3.0:

Groovy

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

Kotlin

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

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

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

更新 Gradle

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

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

插件版本所需的最低 Gradle 版本
8.08.0
7.47.5
7.37.4
7.27.3.3
7.17.2
7.07.0
4.2.0+6.7.1

旧版

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

./gradle wrapper --gradle-version --7.5.1

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

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

Android Gradle 插件和 Android Studio 兼容性

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

Android Studio 版本 所需插件版本
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 插件版本说明

版本编号变更(2020 年 11 月)

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

重要变更如下:

  • AGP 现在将使用语义版本控制,并且重大变更将在主要版本中发布。

  • 每年将发布一个 AGP 主要版本,与 Gradle 主要版本保持一致。

  • AGP 4.2 之后的版本为版本 7.0,并且会要求升级到 Gradle 7.x 版。AGP 的每个主要版本都会要求在底层 Gradle 工具中进行主要版本升级。

  • API 的废弃将提前大约一年进行,同时提供替代功能。废弃的 API 将在大约一年后的下次重大更新期间移除。

7.3.0(2022 年 9 月)

Android Gradle 插件 7.3.0 是一个主要版本,包含各种新功能和改进。

兼容性

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

支持自定义 C/C++ 构建系统

现在,您可以通过创建一个采用 Ninja build 文件格式写入 build 信息的 Shell 脚本,来创建自定义 C/C++ 构建系统。如需详细了解自定义 C/C++ 构建系统,请参阅使用 Ninja(实验性)集成自定义 C/C++ 构建系统

自定义 C/C++ 构建系统的屏幕截图

最低 Kotlin 插件版本为 1.5.20

从 Android Gradle 插件 7.3.0-alpha08 开始,AGP 要求使用 Kotlin 插件版本 1.5.20 或更高版本。为了保持兼容性,请务必在 build.gradle 文件中指定 Kotlin 插件版本 1.5.20 或更高版本:

org.jetbrains.kotlin:kotlin-gradle-plugin:1.5.20

已启用生成已归档 APK

从 AGP 7.3 开始,构建的所有 Android App Bundle 都会默认启用存储归档。归档是一项新的 app bundle 功能,今后,如果存储支持此功能,存储空间不足的用户就可以借助此功能有效管理应用空间。

如需停止生成已归档 APK,请按如下方式修改应用级 build.gradle 文件:

android {
  bundle {
    storeArchive {
      enable = false
    }
  }
}

已废弃清单文件中的 package 属性

从 AGP 7.3.0-alpha04 开始,使用 Gradle 构建项目时,如果在清单文件中使用 package 属性,AGP 会生成警告。如需为应用设置命名空间,请在模块级 build.gradle 文件中使用 namespace 属性。如需了解详情,请参阅设置命名空间

如需获取移至新命名空间 DSL 方面的帮助,请使用 AGP 升级助理 (Tools > AGP Upgrade Assistant)。

Android 平台支持

从 AGP 7.3.0-beta05 开始,支持的最低 SDK 版本最高可设为 33(可以使用 minSdk = 33 来设置)。最低 SDK 表示可运行您的应用的最低 Android 版本,在应用级 build.gradle 文件中进行设置。