Android Gradle 插件 8.7 版本说明

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 构建的详细信息，请参阅以下页面

• 配置您的构建
• Android Gradle 插件 DSL 参考
• Gradle DSL 参考
• Gradle 性能用户指南

有关 Gradle 构建系统的更多信息，请参阅 Gradle 用户指南。

更新 Android Gradle 插件

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

您可以在 Android Studio 中的**文件** > **项目结构** > **项目**菜单或顶层 build.gradle.kts 文件中指定插件版本。插件版本适用于在该 Android Studio 项目中构建的所有模块。以下示例从 build.gradle.kts 文件中将插件设置为 8.7.0 版本

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

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

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

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

更新 Gradle

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

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

您可以通过 Android Studio 中的**文件** > **项目结构** > **项目**菜单指定 Gradle 版本，也可以使用命令行更新 Gradle 版本。推荐使用 Gradle Wrapper 命令行工具，该工具会更新 gradlew 脚本。以下示例使用 Gradle Wrapper 将 Gradle 版本设置为 8.7。请注意，您需要运行此命令两次才能同时升级 Gradle 和 Gradle Wrapper 本身（更多信息，请参阅 升级 Gradle Wrapper）。

gradle wrapper --gradle-version 8.7

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

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

Android Gradle 插件和 Android Studio 兼容性

Android Studio 构建系统基于 Gradle，而 Android Gradle 插件 (AGP) 添加了一些特定于构建 Android 应用的功能。下表列出了每个 Android Studio 版本所需的 AGP 版本。

有关 Android Gradle 插件新增功能的信息，请参阅 Android Gradle 插件发行说明。

Android API 级别工具的最低版本

支持特定 API 级别有 Android Studio 和 AGP 的最低版本。使用低于项目 targetSdk 或 compileSdk 所需的 Android Studio 或 AGP 版本可能会导致意外问题。我们建议使用最新预览版的 Android Studio 和 AGP 来处理面向 Android 操作系统预览版的项目。您可以 并行安装 Android Studio 的预览版和稳定版。

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

版本变更 (2020 年 11 月)

我们正在更新 Android Gradle 插件 (AGP) 的版本编号，使其更 closely 匹配底层的 Gradle 构建工具。

以下是值得注意的更改

• AGP 现在将使用语义版本控制，重大更改将针对主要版本。

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

• AGP 4.2 之后的发行版本将为 7.0 版，这需要升级到 Gradle 7.x 版。每个主要版本的 AGP 都需要底层 Gradle 工具的主要版本升级。

• API 将提前大约一年弃用，同时提供替换功能。弃用的 API 将在大约一年后的后续主要更新中删除。

兼容性

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

Lint 行为更改

从 Android Gradle Plugin 8.7.0-alpha08 开始，如果使用 Gradle 运行 lint 时出现 LintError，则 lint 分析任务会抛出异常。此更改可防止罕见的错误缓存在构建缓存中。

不幸的是，此更改会破坏 lint 基线文件中存在真正 LintError 实例的项目的构建。错误消息包含有关哪些 lint 检查导致问题的信息。在某些情况下，更新相应的库依赖项可能会解决问题。如果不行，您可以禁用有问题的 lint 检查，直到库作者修复它。

已修复的问题

Android Gradle 插件 8.7.0

Android Gradle 插件 8.7.1

Android Gradle 插件 8.7.2