Android Gradle 插件 7.0.0（2021 年 7 月）

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

7.0.1（2021 年 8 月）

本次要更新包含多项 bug 修复。如需查看重要 bug 修复列表，请阅读 版本更新博客上的相关博文。

兼容性

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

需要 JDK 11 才能运行 AGP 7.0

使用 Android Gradle 插件 7.0 构建应用时，现在需要 JDK 11 才能运行 Gradle。Android Studio Arctic Fox 捆绑了 JDK 11，并将 Gradle 配置为默认使用 JDK 11，这意味着大多数 Android Studio 用户不需要对项目进行任何配置更改。

如果您需要手动设置 JDK 版本供 Android Studio 中的 AGP 使用，您需要使用 JDK 11 或更高版本。

如果使用的是独立于 Android Studio 的 AGP，请将 JAVA_HOME 环境变量或 -Dorg.gradle.java.home 命令行选项设置为您的 JDK 11 安装目录，以此升级 JDK 版本。

请注意，已废弃的 SDK 工具软件包中的 SDK 管理器和 AVD 管理器不适用于 JDK 11。如需继续将 SDK 管理器和 AVD 管理器与 AGP 7.0 及更高版本搭配使用，您需要在当前的 Android SDK 命令行工具软件包中切换到工具的最新版本。

Variant API 已稳定

新的 Variant API 现已稳定。请参阅 com.android.build.api.variant 软件包中的新接口以及 gradle-recipes GitHub 项目中的示例。作为新的 Variant API 的一部分，我们通过 Artifacts 接口提供了许多称为工件的中间文件。这些工件（如合并后的清单）可以使用第三方插件和代码安全地获取与自定义。

我们会继续扩展 Variant API，为其添加新功能并增加为进行自定义而提供的中间工件数量。

lint 的行为变更

本部分将介绍 Android Gradle 插件 7.0.0 中的多项 lint 行为变更。

针对库依赖项提高了 lint 性能

现在，在设置了 checkDependencies = true 的情况下运行 lint 的速度比以往快。如果 Android 项目包含具有库依赖项的应用，建议将 checkDependencies 设置为 true（如下所示），并通过 ./gradlew :app:lint 运行 lint，这样就会并行分析所有依赖项模块并且仅生成一份报告，报告中囊括应用及其所有依赖项中存在的问题。

Groovy

// build.gradle
android {
  ...
  lintOptions {
    checkDependencies true
  }
}

Kotlin

// build.gradle.kts
android {
  ...
  lint {
    isCheckDependencies = true
  }
}

lint 任务现在可以显示为“UP-TO-DATE”

如果模块的源代码和资源未更改，就无需再次对该模块运行 lint 分析任务。发生这种情况时，任务的执行在 Gradle 输出中显示为“UP-TO-DATE”。进行此更改后，在设置了 checkDependencies = true 的应用模块上运行 lint 时，只有已更改的模块才需要运行分析。因此，lint 的运行速度更快。

如果 lint 报告任务的输入未更改，那么该任务同样不需要运行。与此相关的一个已知问题是，lint 任务的状态为“UP-TO-DATE”时无输出到 stdout 的 lint 文本输出（问题 191897708）。

在动态功能模块上运行 lint

AGP 不再支持从动态功能模块运行 lint。 从相应的应用模块运行 lint 将在其动态功能模块上运行 lint，并将所有问题都包含在应用的 lint 报告中。与此相关的一个已知问题是，在设置了 checkDependencies = true 的情况下从应用模块运行 lint 时，系统不会检查动态功能库依赖项，除非这些库依赖项同时也是应用依赖项（问题 191977888）。

仅对默认变体运行 lint

运行 ./gradlew :app:lint 时，系统现在仅对默认变体运行 lint。在之前的 AGP 版本中，系统会对所有变体运行 lint。

R8 缩减器中的“缺少类”警告

R8 能够更精确、更一致地处理缺少的类和 -dontwarn 选项。因此，您应该开始评估 R8 发出的“缺少类”警告。

当 R8 遇到未在您的应用或其任一依赖项中定义的类引用时，会发出一条警告，该警告将显示在您的 build 输出中。例如：

R8: Missing class: java.lang.instrument.ClassFileTransformer

这条警告表示，在分析应用的代码时，找不到类定义 java.lang.instrument.ClassFileTransformer。虽然该警告通常意味着出现了错误，但也有可能您需要忽略该警告。忽略该警告的两个常见原因如下：

  1. 以 JVM 和缺少的类为目标的库属于 JVM 库类型（如上例所示）。

  2. 您的其中一个依赖项使用了仅限编译时使用的 API。

您可以通过向 proguard-rules.pro 文件添加 -dontwarn 规则来忽略“缺少类”警告。例如：

-dontwarn java.lang.instrument.ClassFileTransformer

为方便起见，AGP 将生成一个文件，包含所有可能缺少的规则，并将其写入一个文件路径，例如以下文件路径：app/build/outputs/mapping/release/missing_rules.txt。将这些规则添加到 proguard-rules.pro 文件中即可忽略警告。

在 AGP 7.0 中，“缺少类”消息将显示为警告，通过在 gradle.properties 中设置 android.r8.failOnMissingClasses = true 可将其转换为错误。在 AGP 8.0 中，这些警告将变成破坏 build 的错误。将 -ignorewarnings 选项添加到 proguard-rules.pro 文件中可以保留 AGP 7.0 的行为，但建议不要这样做。

移除了 Android Gradle 插件构建缓存

AGP 构建缓存已在 AGP 4.1 中移除。AGP 构建缓存之前在 AGP 2.3 中引入，对 Gradle 构建缓存起到了补充的作用；在 AGP 4.1 中，AGP 构建缓存已完全被 Gradle 构建缓存所取代。此次变更不会影响构建时间。

在 AGP 7.0 中，移除了 android.enableBuildCache 属性、android.buildCacheDir 属性和 cleanBuildCache 任务。

在项目中使用 Java 11 源代码

现在，您最高可以在应用的项目中编译 Java 11 版本的源代码，这让您可以使用更新的语言功能，例如专用接口方法、匿名类的 diamond 运算符以及 lambda 参数的局部变量语法。

如需启用此功能，请将 compileOptions 设置为所需的 Java 版本，并将 compileSdkVersion 设置为 30 或更高：

// build.gradle
android {
  compileSdkVersion 30
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_11
    targetCompatibility JavaVersion.VERSION_11
  }
  // For Kotlin projects
  kotlinOptions {
    jvmTarget = "11"
  }
}
 
// build.gradle.kts
android {
  compileSdkVersion(30)
  compileOptions {
    sourceCompatibility(JavaVersion.VERSION_11)
    targetCompatibility(JavaVersion.VERSION_11)
  }
  kotlinOptions {
    jvmTarget = "11"
  }
}

移除了依赖项配置

在 AGP 7.0 中，移除了以下配置（或依赖项范围）：

  • compile
    该配置已被 api 或 implementation 替换，具体取决于用例。
    同样适用于*Compile 变体，例如 debugCompile。
  • provided
    该配置已被 compileOnly 替换。
    同样适用于*Provided 变体，例如 releaseProvided。
  • apk
    该配置已被 runtimeOnly 替换。
  • publish
    该配置已被 runtimeOnly 替换。

在大多数情况下，AGP 升级助理会自动将您的项目迁移到新配置。

针对 Android Gradle 插件进行编译时的类路径更改

如果要针对 Android Gradle 插件进行编译，编译类路径可能会更改。由于 AGP 现在是在内部使用 api/implementation 配置，因此某些工件可能会从您的编译类路径中移除。如果您在编译时依赖 AGP 依赖项，请务必将其添加为显式依赖项。

不支持在 Java 资源文件夹中添加原生库

以前，您可以在某个 Java 资源文件夹中添加原生库，并使用 android.sourceSets.main.resources.srcDirs 注册该文件夹，以便提取该原生库并将其添加到最终 APK 中。从 AGP 7.0 开始，此功能不受支持，Java 资源文件夹中的原生库将被忽略。请改为使用专为处理原生库而设计的 DSL 方法 android.sourceSets.main.jniLibs.srcDirs。如需了解详情，请参阅如何配置源代码集。

已知问题

本部分介绍了 Android Gradle 插件 7.0.0 中存在的已知问题。

与 1.4.x Kotlin 多平台插件不兼容

Android Gradle 插件 7.0.0 与 Kotlin 多平台插件 1.5.0 及更高版本兼容。使用 Kotlin 多平台支持的项目需要更新到 Kotlin 1.5.0 才能使用 Android Gradle 插件 7.0.0。解决方法之一是，您可以将 Android Gradle 插件降级到 4.2.x，不过建议不要这样做。

如需了解详情，请参阅 KT-43944。

缺少 lint 输出

lint 任务的状态为“UP-TO-DATE”时无输出到 stdout 的 lint 文本输出（问题 191897708）。如需了解更多背景信息，请参阅 lint 的行为变更。此问题将在 Android Gradle 插件 7.1 中得到解决。

系统不会对所有动态功能库依赖项进行 lint 检查

在设置了 checkDependencies = true 的情况下从应用模块运行 lint 时，系统不会检查动态功能库依赖项，除非这些库依赖项同时也是应用依赖项（问题 191977888）。解决方法之一是，您可以在这些库上运行 lint 任务。如需了解更多背景信息，请参阅 lint 的行为变更。