Android Gradle Plugin 7.0.0(2021 年 7 月)

Android Gradle plugin 7.0.0 是一个主要版本,包含多项新功能和改进。

7.0.1(2021 年 8 月)

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

兼容性

最低版本 默认版本 注意事项
Gradle 7.0.2 7.0.2 要了解详情,请参阅更新 Gradle
SDK 构建工具 30.0.2 30.0.2 安装配置 SDK 构建工具。
NDK 不适用 21.4.7075529 安装配置不同版本的 NDK。
JDK 11 11 要了解详情,请参阅设置 JDK 版本

运行 AGP 7.0 需要 JDK 11

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

如果您需要在 Android Studio 内手动设置 AGP 使用的 JDK 版本,您需要使用 JDK 11 或更高版本。

在独立于 Android Studio 使用 AGP 时,通过将 JAVA_HOME 环境变量-Dorg.gradle.java.home 命令行选项设置为 JDK 11 安装目录,升级 JDK 版本。

请注意,已弃用的 SDK Tools 软件包中的 SDK Manager 和 AVD Manager 不适用于 JDK 11。要继续在 AGP 7.0 及更高版本中使用 SDK Manager 和 AVD Manager,您需要切换到当前 Android SDK 命令行工具软件包中的新版本工具。

Variant API 稳定版

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

我们将继续扩展 Variant API,添加新功能,并增加可供自定义的中间工件数量。

Lint 的行为变化

本部分介绍了 Android Gradle plugin 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 遇到应用或其某个依赖项中未定义的类引用时,它会发出一个警告,该警告会显示在您的构建输出中。例如

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

此警告表示分析应用代码时找不到类定义 java.lang.instrument.ClassFileTransformer。虽然这通常意味着存在错误,但您可能希望忽略此警告。忽略此警告的两个常见原因如下:

  1. 针对 JVM 的库以及缺失的类属于 JVM 库类型(如上例所示)。

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

您可以通过将 -dontwarn 规则添加到您的 proguard-rules.pro 文件来忽略类缺失警告。例如

-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 中,这些警告将成为中断构建的错误。您可以通过将选项 -ignorewarnings 添加到您的 proguard-rules.pro 文件来保持 AGP 7.0 的行为,但不建议这样做。

Android Gradle plugin 构建缓存已移除

AGP 构建缓存已在 AGP 4.1 中移除。AGP 构建缓存最初在 AGP 2.3 中引入以补充 Gradle 构建缓存,但在 AGP 4.1 中已完全被 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
    根据用例,此项已被 apiimplementation 取代。
    也适用于 *Compile 变体,例如:debugCompile
  • provided
    此项已被 compileOnly 取代。
    也适用于 *Provided 变体,例如:releaseProvided
  • apk
    此项已被 runtimeOnly 取代。
  • publish
    此项已被 runtimeOnly 取代。

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

针对 Android Gradle plugin 编译时的类路径变化

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

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

之前,您可以在 Java resources 文件夹中添加一个原生库,并使用 android.sourceSets.main.resources.srcDirs 注册该文件夹,以便提取原生库并将其添加到最终 APK 中。从 AGP 7.0 开始,此操作不受支持,并且 Java resources 文件夹中的原生库将被忽略。请改用专为原生库设计的 DSL 方法 android.sourceSets.main.jniLibs.srcDirs。有关更多信息,请参阅如何配置源集

已知问题

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

与 1.4.x Kotlin Multiplatform plugin 不兼容

Android Gradle Plugin 7.0.0 与 Kotlin Multiplatform plugin 1.5.0 及更高版本兼容。使用 Kotlin Multiplatform 支持的项目需要更新到 Kotlin 1.5.0 才能使用 Android Gradle Plugin 7.0.0。作为一种解决方法,您可以将 Android Gradle plugin 降级到 4.2.x,但不建议这样做。

有关更多信息,请参阅 KT-43944

Lint 输出缺失

当 lint 任务处于最新状态时,stdout 上不会打印 lint 文本输出(问题 #191897708)。有关更多背景信息,请参阅Lint 的行为变化。此问题将在 Android Gradle plugin 7.1 中修复。

并非所有动态功能库依赖项都经过 lint 检查

当从应用模块使用 checkDependencies = true 运行 lint 时,动态功能库依赖项不会被检查,除非它们也是应用依赖项(问题 #191977888)。作为一种解决方法,可以在这些库上运行 lint 任务。有关更多背景信息,请参阅Lint 的行为变化