Android Gradle 插件版本说明

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

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

本页将介绍如何让 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 版本
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 版本 所需插件版本
Arctic Fox | 2020.3.1 3.1-7.0
Bumblebee | 2021.1.1 3.2-7.1
Chipmunk | 2021.2.1 3.2-7.2
Dolphin | 2021.3.1 3.2-7.3
Electric Eel | 2022.1.1 3.2-7.4
Flamingo | 2022.2.1 3.2-8.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 构建文件格式写入构建信息的 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 文件中进行设置。

7.2.0（2022 年 5 月）

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

7.2.2（2022 年 8 月）

本次要更新对应于 Android Studio Chipmunk 补丁 2，并包含以下 bug 修复：

  • 问题 232438924：与 ASM API 一起使用时，AndroidGradlePlugin 版本 7.2 会破坏转换 API
  • 问题 231037948：AGP 7.2.0-rc01 :buildSrc:generatePrecompiledScriptPluginAccessors - shadow/bundletool/com/android/prefs/AndroidLocation$AndroidLocationException
7.2.1（2022 年 5 月）

本次要更新对应于 Android Studio Chipmunk 补丁 1，并包含以下 bug 修复：

如需查看此版本中包含的其他 bug 修复，请参阅 Android Studio Chipmunk 补丁 1 版本说明。

兼容性

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

Build Analyzer 中的 Jetifier 警告和检查

现在，如果项目的 gradle.properties 文件包含 android.enableJetifier=true，Build Analyzer 会显示警告。该标志是在以前的 Android Studio 版本中引入的，可为不能原生支持 AndroidX 的库启用 AndroidX。不过，库生态系统大多已经变为能够原生支持 AndroidX，因此您的项目可能不再需要 Jetifier 标志了。此外，该标志可能会降低 build 性能。如果您看到此警告，可以在 Build Analyzer 中运行检查，以确认是否可以移除该标志。

支持测试固件

从 Android Studio Chipmunk Beta 1 开始，Android Studio 支持 Android 和 Java 测试固件。如需详细了解测试固件功能以及如何在 Java 项目中使用该功能，请参阅有关如何使用测试固件的 Gradle 指南。

如需在 Android 库模块中启用测试固件，请将以下代码添加到库级 build.gradle 文件中：

android {
    testFixtures {
        enable true

        // enable testFixtures's android resources (disabled by default)
        // androidResources true
    }
}

默认情况下，如果您发布库，则会同时发布测试固件 AAR 和主库。Gradle 模块元数据文件将包含 Gradle 的信息，以便在请求 testFixtures 组件时能够使用正确的工件。

如需停止在发布变体中发布库的测试固件 AAR，请将以下代码添加到库级 build.gradle 文件中：

afterEvaluate {
    components.release.withVariantsFromConfiguration(
        configurations.releaseTestFixturesVariantReleaseApiPublication) { skip() }
    components.release.withVariantsFromConfiguration(
        configurations.releaseTestFixturesVariantReleaseRuntimePublication) { skip() }
}

如需使用已发布 Android 库的测试固件 AAR，您可以使用 Gradle 的辅助方法 testFixtures()。

dependencies {
    testImplementation testFixtures('com.example.company:publishedLib:1.0')
}

默认情况下，lint 会分析测试固件来源。您可以对 lint 进行配置，指示其忽略测试固件来源，具体代码如下所示：

android {
    lint {
        ignoreTestFixturesSources true
    }
}

不支持重复的内容根

从 AGP 7.2 开始，您无法在多个源代码集之间共享同一个源目录。例如，您不能在单元测试和插桩测试中使用相同的测试源。如需了解详情，请参阅更改默认源代码集配置。

7.1.0（2022 年 1 月）

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

7.1.3（2022 年 4 月）

本次要更新包含以下 bug 修复：

  • R8 报告的重复类问题

如需查看此版本中的完整 bug 修复列表，请参阅 Android Studio Bumblebee Patch 3 博文。

7.1.2（2022 年 2 月）

本次要更新包含以下 bug 修复：

  • Android Gradle 插件 7.1.0-rc01 在单元测试期间无法执行 ASM 字节码转换
  • Gradle 同步失败，并显示“无法加载类‘com.android.build.api.extension.AndroidComponentsExtension’”消息。
  • 无法在 Android Gradle 插件 7.0.0 中通过 Groovy DSL 使用部分新的 DSL 代码块
  • AGP 7.1 新发布的 API：创建的 javadoc jar 没有签名
  • ClassesDataSourceCache 应使用最新的 ASM 版本
  • Android Studio BumbleBee 并非总是部署最新的更改

如需查看此版本中的完整 bug 修复列表，请参阅 Android Studio Bumblebee Patch 2 博文。

7.1.1（2022 年 2 月）

本次要更新对应于 Android Studio Bumblebee 补丁程序 1 版本。

如需查看此版本中的 bug 修复列表，请参阅 Android Studio Bumblebee Patch 1 博文。

兼容性

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

Lint 分析任务现在可缓存

AndroidLintAnalysisTask 现在与 Gradle 构建缓存兼容。如果您通过在 gradle.properties 文件中设置 org.gradle.caching=true 来启用构建缓存，lint 分析任务将尽可能从构建缓存中获取其输出。

使用 Android Gradle 插件运行 lint 时，lint 分析任务通常是最大的瓶颈，因此在许多情况下，启用构建缓存可提高运行 lint 时的构建速度。例如，如果您有多模块项目，并在使用 CI 服务器运行 lint 之前清理了构建目录，性能应该会得到显著提升。

C/C++ 模块现在可引用同一项目中的其他 C/C++ 模块

现在，包含 C/C++ 代码的 Gradle Android 模块可设置为引用其他 Gradle 模块中的头文件和库代码。Prefab 协议用于在 Gradle 模块之间传递头文件和库。

要求

  • 使用方模块必须为 CMake，而非 ndk-build。对 ndk-build 的支持将需要未来 NDK 更新。发布方模块可以是 CMake 或 ndk-build。

  • 使用方模块必须在 build.gradle 文件中启用 prefab。

android {
  buildFeatures {
    prefab true
  }
}
  • 发布方模块必须在 build.gradle 文件中启用 prefabPublishing。
android {
  buildFeatures {
    prefabPublishing true
  }
}
  • 使用方模块必须通过在 build.gradle 文件的 dependencies 代码块中添加一行代码来引用发布方模块。例如：
dependencies {
  implementation project(':mylibrary')
}
  • 发布方模块必须使用 prefab 部分公开软件包。例如：
android {
  prefab {
    mylibrary {
      libraryName "libmylibrary"
      headers "src/main/cpp/include"
    }
  }
}
  • 使用方模块的 CMakeLists.txt 文件可以使用 find_package() 来查找提供方模块发布的软件包。例如：
find_package(mylibrary REQUIRED CONFIG)
target_link_libraries(
        myapplication
        mylibrary::mylibrary)

   android {
defaultConfig {
        externalNativeBuild {
          cmake {
            arguments '-DANDROID_STL=c++_shared'
          }
        }
      }
    }

如需详细了解如何使用 AGP 配置原生 AAR 使用方和提供方，请参阅原生依赖项与 AGP。

settings.gradle 文件中的代码库设置

在 Android Studio Bumblebee 中创建新项目时，顶层 build.gradle 文件包含 plugins 代码块，后跟用于清理构建目录的代码：

plugins {
    id 'com.android.application' version '7.1.0-beta02' apply false
    id 'com.android.library' version '7.1.0-beta02' apply false
    id 'org.jetbrains.kotlin.android' version '1.5.30' apply false
}

task clean(type: Delete) {
  delete rootProject.buildDir
}

以前位于顶级 build.gradle 文件中的代码库设置现在位于 settings.gradle 文件中：

pluginManagement {
  repositories {
    gradlePluginPortal()
    google()
    mavenCentral()
  }
}

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
  }
}
rootProject.name = 'GradleManagedDeviceTestingNew'
include ':app'

模块级 build.gradle 文件未更改。因此，请使用顶级 build.gradle 文件和 settings.gradle 文件定义将应用于项目中所有模块的 build 配置，或定义适用于 Gradle 本身的代码库和依赖项；使用模块级 build.gradle 文件定义特定于项目中的给定模块的 build 配置。

改进了资源缩减器

Android Studio Bumblebee 包含一个经过改进的资源缩减器，可以帮助您缩减应用大小。

支持具有动态功能的应用

Android Gradle 插件 7.1.0-alpha09 更新了 Android 资源缩减器的默认实现。新的实现支持缩减具有动态功能的应用。

进一步缩减应用大小实验性功能

新的资源缩减器实现可以修改资源表来移除未使用的值资源以及对未使用文件资源的引用，从而进一步缩减应用大小。新的资源缩减器可以完全删除未使用的文件资源，从而进一步缩减应用的大小。默认情况下，此行为尚未启用，但您可以向项目的 gradle.properties 文件中添加实验性选项 android.experimental.enableNewResourceShrinker.preciseShrinking=true 来选择启用此行为。

请报告您使用新资源缩减器或实验性标志时遇到的任何问题。为帮助诊断问题，或者作为临时解决方法，您可以通过将 android.enableNewResourceShrinker=false 添加到项目的 gradle.properties 来切换回之前的实现。新的缩减器会将未使用的文件资源替换为与先前的资源缩减器相比略有不同的最小文件，但这不会对运行时产生任何影响。

我们计划在 Android Gradle 插件 8.0.0 中移除旧实现。

发布 build 变体

Android Gradle 插件 7.1.0 及更高版本允许您配置要发布到 Apache Maven 代码库的 build 变体。AGP 会根据新的发布 DSL 创建具有一个或多个 build 变体的组件，您可以使用这些组件自定义要发布到 Maven 代码库的内容。与先前版本相比，这样还可以避免不必要的工作，因为默认情况下不会创建任何组件。如需了解详情，请参阅发布代码示例。

发布 Javadoc JAR

AGP 7.1.0 及更高版本允许您从 Java 和 Kotlin 源代码生成 Javadoc，并为库项目发布 Javadoc JAR 文件和 AAR。Javadoc 已添加到 POM 和 Gradle Module Metadata 文件中。如需启用此功能，请在 singleVariant 或 multipleVariants 发布块中添加 withJavadocJar()。如需了解详情，请参阅发布选项代码示例。

发布源代码 JAR

除了 AAR 之外，AGP 7.1.0 及更高版本还支持为库项目发布 Java 和 Kotlin 源代码 JAR 文件。这些源代码会添加到 POM 和 Gradle Module Metadata 文件中。如需启用此功能，您可以在 singleVariant 或 multipleVariants 发布块中添加 withSourcesJar()。如需了解详情，请参阅发布选项代码示例。

Lint 块语义变更

覆盖问题指定严重级别（enable、disable/ignore、informational、warning、error、fatal）的所有 lint 方法现在遵循配置顺序。例如，在 finalizeDsl() 中将某个问题设置为严重问题会覆盖在主 DSL 中停用该问题的行为。如需了解详情，请参阅 lint{} 块参考文档以及 Android 构建流程和扩展点。

移除了 Navigation Safe Args Gradle 插件所依赖的 AGP API。AGP 7.1 不适用于 Navigation Safe Args 版本 2.4.0-rc1 或 2.4.0，但支持版本 2.5.0-alpha01 和 2.4.1。在此期间，作为替代解决方案，您可以将 AGP 7.1 与 Navigation Safe Args 的快照 build (Navigation 2.5.0-SNAPSHOT) 搭配使用。如需使用快照 build，请按照快照说明操作，其中 build ID 为 8054565。

此外，Navigation Safe Args 版本 2.4.1 和 2.5.0 将不再适用于 AGP 4.2；要使用这些版本的 Safe Args，您必须使用 AGP 7.0 及更高版本。

停用自动组件创建功能

从 AGP 8.0 开始，默认情况下，系统会停用自动组件创建功能。目前，AGP 7.1 会自动为每个 build 变体创建一个组件，其名称与 build 变体相同，并创建一个包含所有 build 变体的 all 组件。此自动组件创建功能将被停用。若要过渡到新行为，您应将 android.disableAutomaticComponentCreation 设置为 true. 以手动停用自动组件创建功能。如需了解详情，请参阅使用 Maven Publish 插件。

Firebase Performance Monitoring 兼容性

AGP 7.1 与 Firebase Performance Monitoring Gradle 插件版本 1.4.0 及更低版本不兼容。AGP 升级助理不会自动将插件更新到版本 1.4.1，因此，如果您使用的是 firebase-perf，并且希望将 AGP 升级到 7.1，则需要手动进行这一升级。

已知问题

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

对使用 Hilt 插件的应用项目进行单元测试时出现问题

单元测试类路径包含非插桩应用类，这意味着，运行单元测试时，Hilt 不会插桩应用类来处理依赖项注入。

此问题将在 7.1.1 版本中得到解决，请参阅问题 213534628。

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 或更高：

Groovy

// build.gradle

android {
    compileSdkVersion 30

    compileOptions {
      sourceCompatibility JavaVersion.VERSION_11
      targetCompatibility JavaVersion.VERSION_11
    }

    // For Kotlin projects
    kotlinOptions {
      jvmTarget = "11"
    }
}

Kotlin

// 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 的行为变更。

4.2.0（2021 年 3 月）

兼容性

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

新功能

此版本的 Android Gradle 插件包含以下新功能。

默认情况下使用 Java 语言版本 8

从 4.2 版本开始，AGP 将默认使用 Java 8 语言级别。Java 8 提供对一些更新语言功能（包括 lambda 表达式、方法引用和静态接口方法）的访问权限。如需查看受支持功能的完整列表，请参阅 Java 8 文档。

如需保留旧行为，请在模块级 build.gradle.kts 或 build.gradle 文件中显式指定 Java 7：

Groovy

// build.gradle

android {
  ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_7
    targetCompatibility JavaVersion.VERSION_1_7
  }
  // For Kotlin projects, compile to Java 6 instead of 7
  kotlinOptions {
    jvmTarget = "1.6"
  }
}

Kotlin

// build.gradle.kts

android {
  ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_1_7
    targetCompatibility = JavaVersion.VERSION_1_7
  }
  // For Kotlin projects, compile to Java 6 instead of 7
  kotlinOptions {
    jvmTarget = "1.6"
  }
}

新增的 JVM 资源编译器

Android Gradle 插件 4.2 工具中新增了一个 JVM 资源编译器，它取代了 AAPT2 资源编译器的部分功能，有助于提升构建性能，尤其是在 Windows 计算机上。新增的 JVM 资源编译器默认处于启用状态。

现在支持 v3 和 v4 签名

Android Gradle 插件 4.2 现在支持 APK v3 和 APK v4 签名格式。 如需在 build 中启用这两种格式之一或同时启用这两种格式，请将以下属性添加到模块级 build.gradle 或 build.gradle.kts 文件中：

Groovy

// build.gradle

android {
  ...
  signingConfigs {
    config {
        ...
        enableV3Signing true
        enableV4Signing true
    }
  }
}

Kotlin

// build.gradle.kts

android {
   ...
   signingConfigs {
      config {
          ...
          enableV3Signing = true
          enableV4Signing = true
      }
   }
}

通过 APK v4 签名，您可以使用 Android 11 中的 ADB 增量 APK 安装快速部署大型 APK。此新标志负责部署过程中的 APK 签名步骤。

按变体配置应用签名

现在可以按变体在 Android Gradle 插件中启用或停用应用签名。

以下示例展示了如何在 Kotlin 或 Groovy 中使用 onVariants() 方法按变体设置应用签名：

androidComponents {
    onVariants(selector().withName("fooDebug"), {
        signingConfig.enableV1Signing.set(false)
        signingConfig.enableV2Signing.set(true)
    })

新增的 Gradle 属性：android.native.buildOutput

为了减少构建输出中的杂乱现象，AGP 4.2 会过滤来自使用 CMake 和 ndk-build 的原生 build 的消息，从而在默认情况下仅显示 C/C++ 编译器输出。以前，系统会为构建的每个文件生成一行输出，导致生成大量信息性消息。

如果您想查看完整的原生输出，请将新的 Gradle 属性 android.native.buildOutput 设置为 verbose。

您可以在 gradle.properties 文件中或通过命令行设置此属性。

gradle.properties
android.native.buildOutput=verbose

命令行
-Pandroid.native.buildOutput=verbose

此属性的默认值为 quiet。

gradle.properties 文件的行为变更

从 AGP 4.2 开始，无法再从子项目中替换 Gradle 属性。也就是说，如果您在子项目（而不是根项目）上的 gradle.properties 文件中声明某个属性，该属性将被忽略。

例如，在以前的版本中，AGP 会从 projectDir/gradle.properties、projectDir/app/gradle.properties、projectDir/library/gradle.properties 等文件中读取值。对于应用模块，如果同一 Gradle 属性同时存在于 projectDir/gradle.properties 和 projectDir/app/gradle.properties 中，projectDir/app/gradle.properties 中的值优先。

在 AGP 4.2 中已更改此行为，AGP 不会从子项目内的 gradle.properties 中加载值（例如，子项目为projectDir/app/gradle.properties）。此更改反映了新的 Gradle 行为并支持配置缓存。

如需详细了解如何在 gradle.properties 文件中设置值，请参阅 Gradle 文档。

Gradle 兼容性和配置变更

在 Android Studio 中运行时，Gradle 构建工具会使用 Studio 所捆绑的 JDK。在之前的版本中，与 Studio 捆绑的是 JDK 8。但在 4.2 中，现在捆绑的版本为 JDK 11。使用捆绑的新 JDK 运行 Gradle 时，由于对垃圾回收器的变更，这可能会导致某些不兼容问题或影响 JVM 性能。这些问题的说明如下。

注意：虽然我们建议使用 JDK 11 运行 Gradle，但您也可以在项目结构对话框中更改用于运行 Gradle 的 JDK。更改此设置只会更改用于运行 Gradle 的 JDK，而不会改变用于运行 Studio 自身的 JDK。

Studio 与 Android Gradle 插件 (AGP) 的兼容性

Android Studio 4.2 可以打开使用 AGP 3.1 及更高版本的项目，前提是 AGP 运行的是 Gradle 4.8.1 及更高版本。如需详细了解 Gradle 兼容性，请参阅更新 Gradle。

针对 JDK 11 优化 Gradle 构建

JDK 11 的这项更新会影响 JVM 垃圾回收器的默认配置，因为 JDK 8 使用并行垃圾回收器，而 JDK 11 使用 G1 垃圾回收器。

为提高构建性能，我们建议您使用并行垃圾回收器测试 Gradle 构建。在 gradle.properties 中设置以下内容：

org.gradle.jvmargs=-XX:+UseParallelGC

如果此字段中已设置了其他选项，请添加一个新选项：

org.gradle.jvmargs=-Xmx1536m -XX:+UseParallelGC

如需使用不同的配置检测构建速度，请参阅分析 build 性能。

当 minSdk 为 28 或更高级别时，系统会在 APK 中解压缩 DEX 文件

现在，当 minSdk 为 28 或更高级别时，AGP 默认在 APK 中打包未压缩的 DEX 文件。这会导致 APK 大小增大，但会使设备上的安装大小变小，并且下载大小大致相同。

如需强制 AGP 改为打包压缩后的 DEX 文件，您可以将以下这段代码添加到 build.gradle 文件中：

android {
    packagingOptions {
        dex {
            useLegacyPackaging true
        }
    }
}

使用 DSL 打包压缩后的原生库

我们建议以未压缩的形式打包原生库，因为这会减小应用安装大小，缩减应用下载大小，并缩短用户的应用加载时间。不过，如果您希望 Android Gradle 插件在构建应用时打包压缩后的原生库，请在应用的 build.gradle 文件中将 useLegacyPackaging 设置为 true：

android {
    packagingOptions {
        jniLibs {
            useLegacyPackaging true
        }
    }
}

useLegacyPackaging 标记会替换 extractNativeLibs 清单属性。如需了解更多背景信息，请参阅版本说明默认情况下，原生库以未压缩的形式打包。

4.1.0（2020 年 8 月）

兼容性

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

新功能

此版本的 Android Gradle 插件包含以下新功能。

Kotlin 脚本 DSL 支持

为了帮助改进 Kotlin 构建脚本用户的修改体验，现在 Android Gradle 插件 4.1 的 DSL 和 API 在一组 Kotlin 接口中与其实现类分开定义。这意味着：

  • 现在，在 Kotlin 类型上明确声明了是否可为 null 和可变性。
  • Kotlin API 参考文档中发布了根据这些接口生成的文档。
  • 明确定义了 Android Gradle 插件的 API 接口，使未来扩展 Android build 不那么脆弱。

在 DSL 中设计为改变的集合类型现在一律定义为：

val collection: MutableCollectionType

这意味着，对于以前支持 DSL 的某些集合，无法再在 Kotlin 脚本中编写以下代码：

collection = collectionTypeOf(...)

不过，一律支持改变集合，因此 collection += … 和 collection.add(...) 现在应处处适用。

如果您在升级使用 Android Gradle 插件 Kotlin API 和 DSL 的项目时发现任何问题，请报告错误。

从 AAR 导出 C/C++ 依赖项

Android Gradle 插件 4.0 添加了将 Prefab 软件包导入 AAR 依赖项的功能。在 AGP 4.1 中，现在可以将外部原生 build 中的库导出到 Android 库项目的 AAR 中。

如需导出原生库，请将以下代码添加到库项目的 build.gradle 文件的 android 代码块中：

Groovy


buildFeatures {
    prefabPublishing true
}

prefab {
    mylibrary {
      headers "src/main/cpp/mylibrary/include"
    }

    myotherlibrary {
        headers "src/main/cpp/myotherlibrary/include"
    }
}

Kotlin


buildFeatures {
    prefabPublishing = true
}

prefab {
    create("mylibrary") {
      headers = "src/main/cpp/mylibrary/include"
    }

    create("myotherlibrary") {
        headers = "src/main/cpp/myotherlibrary/include"
    }
}

在本例中，您的 ndk-build 或 CMake 外部原生 build 中的 mylibrary 和 myotherlibrary 库会打包到您的 build 生成的 AAR 中，并且各自会将头文件从指定的目录导出到依赖于它们的项。

R8 对 Kotlin 元数据的支持

Kotlin 使用 Java 类文件中的自定义元数据标识 Kotlin 语言结构。R8 现在支持维护和重新编写 Kotlin 元数据，以完全支持缩减使用 kotlin-reflect 功能的 Kotlin 库和应用大小。

如需保留 Kotlin 元数据，请添加以下保留规则：

-keep class kotlin.Metadata { *; }

-keepattributes RuntimeVisibleAnnotations

这将指示 R8 保留直接保留的所有类的 Kotlin 元数据。

如需了解详情，请参阅 Medium 上的借助 R8 缩减使用 Kotlin 反射功能的 Kotlin 库和应用大小。

调试 build 中的断言

当您使用 Android Gradle 插件 4.1.0 及更高版本构建应用的调试版本时，内置编译器 (D8) 会重写应用代码以在编译时启用断言，因此您始终要将断言检查置于启用状态。

行为变更

移除了 Android Gradle 插件构建缓存

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

cleanBuildCache 任务以及 android.enableBuildCache 和 android.buildCacheDir 属性已被废弃，将在 AGP 7.0 中移除。android.enableBuildCache 属性目前不起任何作用，而 android.buildCacheDir 属性和 cleanBuildCache 任务在 AGP 7.0 之前将一直发挥作用，用于删除任何现有的 AGP 构建缓存内容。

使用代码缩减功能后应用的体量显著减小

从此版本开始，默认不再保留 R 类中的字段。这样一来，启用代码缩减的应用的 APK 大小将会显著减少。这应该不会导致行为变更，除非您通过反射功能访问 R 类；如果您通过反射功能访问 R 类，就必须针对这些 R 类添加保留规则。

android.namespacedRClass 属性已重命名为 android.nonTransitiveRClass

实验性标记 android.namespacedRClass 已重命名为 android.nonTransitiveRClass。

此标志在 gradle.properties 文件中设置，可启用每个库的 R 类的命名空间，以便其 R 类仅包含库本身中声明的资源，而不包含库的依赖项中的任何资源，从而缩减相应库的 R 类大小。

Kotlin DSL：coreLibraryDesugaringEnabled 已重命名

Kotlin DSL 编译选项 coreLibraryDesugaringEnabled 已更改为 isCoreLibraryDesugaringEnabled。如需详细了解此标记，请参阅 Java 8+ API 脱糖支持 (Android Gradle 插件 4.0.0+)。

从库项目中的 BuildConfig 类中移除了版本属性

仅对于库项目而言，BuildConfig.VERSION_NAME 和 BuildConfig.VERSION_CODE 属性已从生成的 BuildConfig 类中移除，因为这些静态值过去并不反映应用版本代码和名称的最终值，因此具有误导性。此外，这些值过去在清单合并期间会被舍弃。

在将来的 Android Gradle 插件版本中，versionName 和 versionCode 属性也会从库的 DSL 中移除。目前，无法从库子项目自动获取应用版本代码/名称。

对于应用模块而言，没有发生变化，您仍然可以在 DSL 中为 versionCode 和 versionName 赋值，这些值将传播到应用的清单和 BuildConfig 字段。

设置 NDK 路径

您可以使用模块的 build.gradle 文件中的 android.ndkPath 属性设置本地 NDK 安装的路径。

Groovy

android {
   ndkPath "your-custom-ndk-path"
}

Kotlin

android {
   ndkPath = "your-custom-ndk-path"
}

如果您将此属性与 android.ndkVersion 属性一起使用，则此路径必须包含与 android.ndkVersion 匹配的 NDK 版本。

库单元测试行为变更

我们更改了如何编译和运行库单元测试的行为。库的单元测试现在针对库本身的编译/运行时类编译和运行，使得单元测试以与外部子项目相同的方式使用库。此配置通常会使测试效果更好。

在某些情况下，使用数据绑定的库单元测试可能会遇到缺少 DataBindingComponent 或 BR 类的情况。这些测试需要移植到 androidTest 项目中的插桩测试，因为在单元测试中针对这些类编译和运行可能会生成错误的输出。

废弃了 io.fabric Gradle 插件

io.fabric Gradle 插件已废弃，与 Android Gradle 插件版本 4.1 不兼容。如需详细了解已废弃的 Fabric SDK 以及如何迁移到 Firebase Crashlytics SDK，请参阅升级到 Firebase Crashlytics SDK。

4.0.0（2020 年 4 月）

此版本的 Android 插件需要使用以下工具：

4.0.1（2020 年 7 月）

本次要更新支持与 Android 11 中软件包可见性的新默认设置和功能兼容。

在以前的 Android 版本中，可以查看设备上安装的所有应用的列表。从 Android 11（API 级别 30）开始，默认情况下，应用只能访问经过过滤的已安装软件包列表。如需查看系统上更广泛的应用列表，您现在需要在应用或库的 Android 清单中添加 <queries> 元素。

Android Gradle 插件 4.1 及更高版本已与新的 <queries> 声明兼容；不过，较低的版本不兼容。如果您添加 <queries> 元素或者开始依赖于支持以 Android 11 为目标平台的库或 SDK，在构建应用时可能会遇到清单合并错误。

为了解决此问题，我们将针对 AGP 3.3 及更高版本发布一组补丁程序。如果您使用的是旧版 AGP，请升级到以下某个版本：

如果您使用的是
AGP 版本... 		...请升级到
4.0.* 4.0.1
3.6.* 3.6.4
3.5.* 3.5.4
3.4.* 3.4.3
3.3.* 3.3.3

如需详细了解这项新功能，请参阅 Android 11 中的软件包可见性。

新功能

此版本的 Android Gradle 插件包含以下新功能。

对 Android Studio Build Analyzer 的支持

Build Analyzer 窗口可帮助您了解和诊断与构建流程有关的问题，如优化被停用和任务配置不当问题。当您将 Android Studio 4.0 及更高版本与 Android Gradle 插件 4.0.0 及更高版本一起使用时，此功能可用。您可以从 Android Studio 中打开 Build Analyzer 窗口，具体操作步骤如下：

  1. 通过从菜单栏中依次选择 Build > Make Project 来构建应用（如果您尚未这样做）。
  2. 从菜单栏中依次选择 View > Tool Windows > Build。
  3. 在 Build 窗口中，通过以下某种方式打开 Build Analyzer 窗口：
    • Android Studio 构建完您的项目后，点击 Build Analyzer 标签页。
    • Android Studio 构建完您的项目后，点击 Build Output 窗口右侧的链接。

Build Analyzer 窗口将可能存在的构建问题整理成左侧的树状图。您可以检查并点击每个问题，以在右侧的面板中调查其详细信息。当 Android Studio 分析您的构建时，它会计算决定构建时长的一组任务，并提供直观的图表来帮助您了解其中每项任务所产生的影响。您也可以展开 Warnings 节点，以获取有关警告的详细信息。

如需了解详情，请参阅发现构建速度减慢的问题。

D8 和 R8 中的 Java 8 库脱糖

Android Gradle 插件现在支持使用多种 Java 8 语言 API，而无需为应用设置最低 API 级别。

通过一个称为“脱糖”的过程，Android Studio 3.0 及更高版本中的 DEX 编译器 D8 已经为 Java 8 语言功能（如 lambda 表达式、默认接口方法、try-with-resources 等等）提供了大量的支持。在 Android Studio 4.0 中，脱糖引擎经过扩展，能够使 Java 语言 API 脱糖。这意味着，您现在可以在支持旧版 Android 的应用中添加过去仅在最新 Android 版本中可用的标准语言 API（如 java.util.streams）。

此版本支持下面一组 API：

  • 顺序流 (java.util.stream)
  • java.time 的子集
  • java.util.function
  • java.util.{Map,Collection,Comparator} 的最近新增内容
  • 可选内容（java.util.Optional、java.util.OptionalInt 和 java.util.OptionalDouble）以及对上述 API 很有用的一些其他新类
  • java.util.concurrent.atomic 的一些新增内容（AtomicInteger、AtomicLong 和 AtomicReference 的新方法）
  • ConcurrentHashMap（包含 Android 5.0 的 bug 修复）

为了支持这些语言 API，D8 编译了一个单独的 DEX 文件（其中包含缺失 API 的实现），并将其添加到您的应用中。脱糖过程会重新编写应用的代码，以便在运行时改用此库。

如需启用对这些语言 API 的支持，请在应用模块的 build.gradle 文件中添加以下代码：

Groovy


android {
  defaultConfig {
    // Required when setting minSdkVersion to 20 or lower
    multiDexEnabled true
  }

  compileOptions {
    // Flag to enable support for the new language APIs
    coreLibraryDesugaringEnabled true
    // Sets Java compatibility to Java 8
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

dependencies {
  coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.0.4'
}

Kotlin


android {
  defaultConfig {
    // Required when setting minSdkVersion to 20 or lower
    multiDexEnabled = true
  }

  compileOptions {
    // Flag to enable support for the new language APIs
    isCoreLibraryDesugaringEnabled = true
    // Sets Java compatibility to Java 8
    sourceCompatibility = JavaVersion.VERSION_1_8
    targetCompatibility = JavaVersion.VERSION_1_8
  }
}

dependencies {
  coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.0.4")
}

请注意，在以下情况下，您可能还需要在相应库模块的 build.gradle 文件中添加以上代码段：

  • 库模块的插桩测试会使用这些语言 API（直接使用，或者通过库模块或其依赖项使用）。这是为了向您的插桩测试 APK 提供缺失的 API。

  • 您想单独在该库模块上运行 lint。这是为了帮助 lint 识别出对语言 API 的有效使用，并避免错误地发出警告。

用于启用或停用构建功能的新选项

Android Gradle 插件 4.0.0 引入了一种新方法来控制您要启用和停用哪些构建功能，如视图绑定和数据绑定。添加新功能后，默认情况下，这些功能处于停用状态。您随后可以使用 buildFeatures 代码块来仅启用所需的功能，它可以帮助您优化项目的构建性能。您可以在模块级 build.gradle 文件中为每个模块设置相应的选项，如下所示：

Groovy


android {
    // The default value for each feature is shown below. You can change the value to
    // override the default behavior.
    buildFeatures {
        // Determines whether to generate a BuildConfig class.
        buildConfig = true
        // Determines whether to support View Binding.
        // Note that the viewBinding.enabled property is now deprecated.
        viewBinding = false
        // Determines whether to support Data Binding.
        // Note that the dataBinding.enabled property is now deprecated.
        dataBinding = false
        // Determines whether to generate binder classes for your AIDL files.
        aidl = true
        // Determines whether to support RenderScript.
        renderScript = true
        // Determines whether to support injecting custom variables into the module’s R class.
        resValues = true
        // Determines whether to support shader AOT compilation.
        shaders = true
    }
}

Kotlin


android {
    // The default value for each feature is shown below. You can change the value to
    // override the default behavior.
    buildFeatures {
        // Determines whether to generate a BuildConfig class.
        buildConfig = true
        // Determines whether to support View Binding.
        // Note that the viewBinding.enabled property is now deprecated.
        viewBinding = false
        // Determines whether to support Data Binding.
        // Note that the dataBinding.enabled property is now deprecated.
        dataBinding = false
        // Determines whether to generate binder classes for your AIDL files.
        aidl = true
        // Determines whether to support RenderScript.
        renderScript = true
        // Determines whether to support injecting custom variables into the module’s R class.
        resValues = true
        // Determines whether to support shader AOT compilation.
        shaders = true
    }
}

您还可以为项目中的所有模块指定这些功能的默认设置，方法是在项目的 gradle.properties 文件中添加下面的一项或多项，如下所示。请注意，您仍然可以使用模块级 build.gradle 文件中的 buildFeatures 代码块替换这些项目范围的默认设置。

android.defaults.buildfeatures.buildconfig=true
android.defaults.buildfeatures.aidl=true
android.defaults.buildfeatures.renderscript=true
android.defaults.buildfeatures.resvalues=true
android.defaults.buildfeatures.shaders=true

功能对功能的依赖性

在以前的 Android Gradle 插件版本中，所有功能模块都只能依赖于应用的基本模块。使用 Android Gradle 插件 4.0.0 时，您现在可以添加依赖于其他功能模块的功能模块。也就是说，:video 功能可以依赖于 :camera 功能，而后者依赖于基本模块，如下图所示。

功能对功能的依赖性

:video 功能模块依赖于 :camera 功能，而后者依赖于 :app 基本模块。

这意味着，当您的应用请求下载某个功能模块时，它也会下载该模块所依赖的其他功能模块。为您的应用创建功能模块后，您可以在模块的 build.gradle 文件中声明功能对功能的依赖性。例如，:video 模块声明对 :camera 的依赖性，如下所示：

Groovy


// In the build.gradle file of the ':video' module.
dependencies {
    // All feature modules must declare a dependency
    // on the base module.
    implementation project(':app')
    // Declares that this module also depends on the 'camera'
    // feature module.
    implementation project(':camera')
    ...
}

Kotlin


// In the build.gradle file of the ':video' module.
dependencies {
    // All feature modules must declare a dependency
    // on the base module.
    implementation(project(":app"))
    // Declares that this module also depends on the 'camera'
    // feature module.
    implementation(project(":camera"))
    ...
}

此外，您还应在 Android Studio 中启用功能对功能的依赖性功能（例如，为了在修改运行配置时支持该功能），方法是从菜单栏中依次点击 Help > Edit Custom VM Options，并添加以下代码：

-Drundebug.feature.on.feature=true

依赖项元数据

使用 Android Gradle 插件 4.0.0 及更高版本构建应用时，该插件包含描述已编译到应用中的依赖项的元数据。上传应用时，Play 管理中心会检查此元数据，以便为您提供以下优势：

  • 获取有关您的应用使用的 SDK 和依赖项的已知问题的提醒
  • 接收切实可行的反馈来解决这些问题

数据经过压缩，并由 Google Play 签名密钥加密，然后存储在您的发布应用的签名分块中。但是，您可以在以下目录中的本地中间构建文件中自行检查元数据：<project>/<module>/build/outputs/sdk-dependencies/release/sdkDependency.txt。

如果您不希望分享这些信息，您可以通过在模块的 build.gradle 文件中添加以下代码来选择退出：

Groovy


android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Kotlin


android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

从 AAR 依赖项导入原生库

您现在可以从应用的 AAR 依赖项导入 C/C++ 库。当您按照下述配置步骤操作时，Gradle 会自动使这些原生库可供您的外部原生构建系统（如 CMake）使用。请注意，Gradle 仅向您的 build 提供这些库；您仍然必须配置构建脚本才能使用它们。

系统会以 Prefab 软件包格式将库导出。

每个依赖项最多可公开一个 Prefab 软件包，该软件包由一个或多个模块组成。Prefab 模块是一个库，它可以是共享库或静态库，也可以是仅包含头文件的库。

通常，软件包名称与 Maven 工件名称匹配，模块名称与库名称匹配，但并不总是如此。由于您需要知道库的软件包和模块名称，因此您可能需要参考依赖项文档以确定这些名称。

配置外部原生构建系统

如需查看您需要遵循的步骤，请点击您计划使用的外部原生构建系统。

AAR 中包含的原生依赖项通过 CMAKE_FIND_ROOT_PATH 变量向您的 CMake 项目公开。当系统调用 CMake 时，Gradle 会自动设置此值，因此如果您的构建系统修改了此变量，请务必对其附加相应值而不是直接赋值。

每个依赖项都会向您的 CMake build 公开 config-file 软件包，您可以使用 find_package 命令将其导入。此命令会搜索与给定软件包名称和版本匹配的 config-file 软件包，并公开它定义的要在您的 build 中使用的目标。例如，如果您的应用定义了 libapp.so 并且使用了 curl，您应在 CMakeLists.txt 文件中添加以下代码：

add_library(app SHARED app.cpp)

# Add these two lines.
find_package(curl REQUIRED CONFIG)
target_link_libraries(app curl::curl)

您现在可以在 app.cpp 中指定 #include "curl/curl.h"。当您构建项目时，您的外部原生构建系统会自动关联 libapp.so 与 libcurl.so 并将 libcurl.so 打包在 APK 或 app bundle 中。如需了解详情，请参阅 curl prefab 示例。

行为变更

使用此版本的插件时，您可能会遇到以下行为方面的变更。

v1/v2 签名配置更新

signingConfig 块中应用签名配置的行为变更如下：

v1 签名
  • 如果 v1SigningEnabled 已显式启用，AGP 会执行 v1 应用签名。
  • 如果用户显式停用了 v1SigningEnabled，v1 应用签名便不会执行。
  • 如果用户未显式启用 v1 签名，系统可能会根据 minSdk 和 targetSdk 自动停用 v1 签名。
v2 签名
  • 如果 v2SigningEnabled 已显式启用，AGP 会执行 v2 应用签名。
  • 如果用户显式停用了 v2SigningEnabled，v2 应用签名便不会执行。
  • 如果用户未显式启用 v2 签名，系统可能会根据 targetSdk 自动停用 v2 签名。

这些变更可让 AGP 根据用户是否已显式启用这些标志来停用相应签名机制，从而优化 build。在此版本之前，即使 v1Signing 已获显式启用，也可能会被停用，这会使用户感到迷惑。

移除了 feature 和 instantapp Android Gradle 插件

Android Gradle 插件 3.6.0 废弃了功能插件 (com.android.feature) 和免安装应用插件 (com.android.instantapp)，改为使用动态功能插件 (com.android.dynamic-feature)，以通过 Android App Bundle 构建和打包免安装应用。

在 Android Gradle 插件 4.0.0 及更高版本中，完全移除了这些已废弃的插件。因此，如需使用最新的 Android Gradle 插件，您需要迁移免安装应用以支持 Android App Bundle。通过迁移免安装应用，您可以利用 App Bundle 的优势，并简化应用的模块化设计。

移除了“分离注释处理”功能

移除了将注释处理分离到一项专门任务中的功能。此选项过去用于在纯 Java 项目中使用非增量注解处理器时维持增量 Java 编译；过去的启用方法是在 gradle.properties 文件中将 android.enableSeparateAnnotationProcessing 设为 true，但这种方法不再起作用。

您应改为使用增量注解处理器来提升构建性能。

废弃了 includeCompileClasspath

Android Gradle 插件不再检查或添加您在编译类路径上声明的注解处理器，并且 annotationProcessorOptions.includeCompileClasspath DSL 属性不再有任何作用。如果您在编译类路径上添加注解处理器，可能会遇到以下错误：

Error: Annotation processors must be explicitly declared now.

如需解决此问题，您必须在 build.gradle 文件中使用 annotationProcessor 依赖项配置添加注解处理器。如需了解详情，请参阅添加注释处理器。

自动打包 CMake 使用的预构建依赖项

早期版本的 Android Gradle 插件要求您使用 jniLibs 明确打包您的 CMake 外部原生 build 使用的所有预构建库。您的库可能位于模块的 src/main/jniLibs 目录中，也可能位于在 build.gradle 文件中配置的某个其他目录中：

Groovy

sourceSets {
    main {
        // The libs directory contains prebuilt libraries that are used by the
        // app's library defined in CMakeLists.txt via an IMPORTED target.
        jniLibs.srcDirs = ['libs']
    }
}

Kotlin

sourceSets {
    main {
        // The libs directory contains prebuilt libraries that are used by the
        // app's library defined in CMakeLists.txt via an IMPORTED target.
        jniLibs.setSrcDirs(listOf("libs"))
    }
}

有了 Android Gradle 插件 4.0，上述配置不再是必需的，并且会导致构建失败：

* What went wrong:
Execution failed for task ':app:mergeDebugNativeLibs'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.Workers$ActionFacade
   > More than one file was found with OS independent path 'lib/x86/libprebuilt.so'

外部原生 build 现在会自动打包这些库，因此使用 jniLibs 明确打包库会导致重复。为了避免构建错误，请将预构建库移至 jniLibs 之外的位置，或从 build.gradle 文件中移除 jniLibs 配置。

已知问题

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

Gradle 工作器机制中的竞态条件

Android Gradle 插件 4.0 中的变更会在采用 --no-daemon 配置运行的 Gradle 和 Gradle 6.3 或更低版本中触发一种竞态条件，导致 build 在完成后挂起。

此问题将在 Gradle 6.4 中修复。

3.6.0（2020 年 2 月）

此版本的 Android 插件需要使用以下工具：

3.6.4（2020 年 7 月）

本次要更新支持与 Android 11 中软件包可见性的新默认设置和功能兼容。

如需了解详情，请参阅 4.0.1 版本说明。

新功能

此版本的 Android Gradle 插件包含以下新功能。

视图绑定

在代码中引用视图时，视图绑定可确保编译时安全性。您现在可以将 findViewById() 替换为自动生成的绑定类引用。如需开始使用视图绑定，请在每个模块的 build.gradle 文件中添加以下代码：

Groovy


android {
    viewBinding.enabled = true
}

Kotlin


android {
    viewBinding.enabled = true
}

如需了解详情，请阅读视图绑定文档。

支持 Maven Publish 插件

Android Gradle 插件支持 Maven Publish Gradle 插件，可让您将构建工件发布到 Apache Maven 制品库。Android Gradle 插件会为应用或库模块中的每个 build 变体工件创建一个组件，您可以使用它来自定义要发布到 Maven 制品库的发布内容。

如需了解详情，请转到介绍如何使用 Maven Publish 插件的页面。

新的默认打包工具

在构建应用的调试版本时，该插件会使用一个新的打包工具 zipflinger 来构建 APK。这一新工具应该能够提高构建速度。如果新的打包工具无法正常运行，请报告错误。您可以通过在 gradle.properties 文件中添加以下代码来恢复使用旧的打包工具：

android.useNewApkCreator=false

原生构建属性

您现在可以确定 Clang 构建和链接项目中的每个 C/C++ 文件所需的时间。Gradle 可以生成包含这些编译器事件时间戳的 Chrome 跟踪记录，以便您更好地了解构建项目所需的时间。如需生成此构建属性文件，请执行以下操作：

  1. 在运行 Gradle build 时添加标记 -Pandroid.enableProfileJson=true。例如：

    gradlew assembleDebug -Pandroid.enableProfileJson=true

  2. 打开 Chrome 浏览器，然后在搜索栏中输入 chrome://tracing。

  3. 点击 Load 按钮并导航到 project-root/build/android-profile 以查找文件。该文件的名称为 profile-timestamp.json.gz。

您可以在查看器顶部附近查看原生构建属性数据：

Chrome 中的原生构建属性跟踪记录

行为变更

使用此版本的插件时，您可能会遇到以下行为方面的变更。

默认情况下，原生库以未压缩的形式打包

在构建应用时，插件现在默认会将 extractNativeLibs 设置为 "false"。也就是说，您的原生库将保持页面对齐状态并以未压缩的形式打包。虽然这样会增加上传大小，但您的用户会从以下优势中受益：

  • 减小应用安装大小，因为平台可以直接从已安装的 APK 访问原生库，而无需创建库的副本。
  • 减小下载文件大小，因为在 APK 或 Android App Bundle 中添加未压缩的原生库通常可提高 Play 商店的压缩率。

如果您希望 Android Gradle 插件改为打包压缩后的原生库，请在应用的清单中添加以下代码：

<application
    android:extractNativeLibs="true"
    ... >
</application>

默认 NDK 版本

现在，如果您下载了多个版本的 NDK，Android Gradle 插件会选择一个默认版本来编译源代码文件。以前，该插件选择的是最新下载的 NDK 版本。使用模块的 build.gradle 文件中的 android.ndkVersion 属性可替换插件选择的默认版本。

简化了 R 类的生成过程

Android Gradle 插件通过仅为项目中的每个库模块生成一个 R 类并与其他模块依赖项共享这些 R 类，简化了编译类路径。这项优化应该会加快构建速度，但您需要注意以下事项：

  • 由于编译器与上游模块依赖项共享 R 类，因此项目中的每个模块都必须使用独一无二的软件包名称。
  • 库的 R 类对其他项目依赖项的可见性取决于用于将库添加为依赖项的配置。例如，如果库 A 将库 B 添加为“api”依赖项，则库 A 和其他依赖于库 A 的库都可以访问库 B 的 R 类。不过，如果库 A 使用 implementation 依赖项配置，其他库可能就无权访问库 B 的 R 类。如需了解详情，请参阅依赖项配置。

移除默认配置中缺少的资源

对于库模块，如果您添加了未包含在默认资源集内的语言资源（例如，将 hello_world 作为字符串资源添加到 /values-es/strings.xml 中，但未在 /values/strings.xml 中定义该资源），Android Gradle 插件在编译项目时将不会再添加该资源。这种行为变更应该会减少 Resource Not Found 运行时异常，并提高构建速度。

D8 现在遵循注解的类保留政策

现在，在编译应用时，D8 会遵循注释应用的类保留政策，并且这些注释在运行时不再可用。将应用的目标 SDK 设置为 API 级别 23 时，也存在此行为；此前，在使用旧版本的 Android Gradle 插件和 D8 编译应用时，会允许在运行时访问这些注释。

其他行为变更

  • aaptOptions.noCompress 在所有平台（针对 APK 和软件包）上都不再区分大小写，并且遵循使用大写字符的路径。
  • 现在，数据绑定默认为增量式。如需了解详情，请参阅问题 #110061530。
  • 现在，包括 Roboelectric 单元测试在内的所有单元测试都可以完全缓存。如需了解详情，请参阅问题 #115873047。

问题修复

此版本的 Android Gradle 插件包含以下 bug 修复：

  • 现在，使用数据绑定的库模块支持 Robolectric 单元测试。如需了解详情，请参阅问题 #126775542。
  • 现在，您可在启用 Gradle 的并行执行模式的情况下跨多个模块运行 connectedAndroidTest 任务。

已知问题

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

Android Lint 任务的执行速度过慢

Android Lint 由于解析基础架构性能降低，导致在某些代码构造中对 lambda 的推断类型的计算速度变慢，因此可能需要更长时间才能完成某些项目。

此问题会报告为 IDEA bug，并将在 Android Gradle 插件 4.0 中修复。

缺少清单类

如果您的应用在其清单中定义自定义权限，Android Gradle 插件通常会生成 Manifest.java 类，用于以字符串常量的形式添加您的自定义权限。该插件会将此类与您的应用打包在一起，以便于您在运行时更轻松地引用这些权限。

在 Android Gradle 插件 3.6.0 中无法生成清单类。如果您使用此版本的插件构建应用，并且该应用引用了清单类，您可能会看到 ClassNotFoundException 异常。如需解决此问题，请执行以下某项操作：

  • 通过完全限定名称引用自定义权限。例如，"com.example.myapp.permission.DEADLY_ACTIVITY"。

  • 定义您自己的常量，如下所示：

    public final class CustomPermissions {
  public static final class permission {
    public static final String DEADLY_ACTIVITY="com.example.myapp.permission.DEADLY_ACTIVITY";
  }
}

3.5.0（2019 年 8 月）

Android Gradle 插件 3.5.0 和 Android Studio 3.5 是一个重大版本，同时也是 Project Marble 计划的成果，该计划主要围绕 Android 开发者工具的三大核心领域进行改进，分别是系统运行状况、功能完善和 bug 修复。值得注意的是，本次更新的重中之重是提高项目的构建速度。

如需详细了解这些更新以及其他 Project Marble 更新，请参阅 Android 开发者博文或以下几个部分。

此版本的 Android 插件需要使用以下工具：

3.5.4（2020 年 7 月）

本次要更新支持与 Android 11 中软件包可见性的新默认设置和功能兼容。

如需了解详情，请参阅 4.0.1 版本说明。

3.5.3（2019 年 12 月）

本次要更新对 Android Studio 3.5.3 构成补充，修复了各种 bug 并做出了多项性能改进。

3.5.2（2019 年 11 月）

本次要更新对 Android Studio 3.5.2 构成补充，修复了各种 bug 并做出了多项性能改进。如需查看重要 bug 修复列表，请阅读版本更新博客上的相关博文。

3.5.1（2019 年 10 月）

本次要更新对 Android Studio 3.5.1 构成补充，修复了各种 bug 并做出了多项性能改进。如需查看重要 bug 修复列表，请阅读版本更新博客上的相关博文。

增量注解处理

如果您在 gradle.properties 文件中设置了 android.databinding.incremental=true，数据绑定注解处理器支持增量注解处理。这项优化提高了增量构建的性能。如需查看经过优化的注释处理器的完整列表，请参阅增量注释处理器表格。

此外，KAPT 1.3.30 及更高版本也支持增量注释处理器，您可以通过在 gradle.properties 文件中添加 kapt.incremental.apt=true 来启用此支持。

可缓存的单元测试

通过将 includeAndroidResources 设置为 true，您可以允许单元测试使用 Android 资源、资产和清单，此时 Android Gradle 插件会生成包含绝对路径的测试配置文件，绝对路径会打破缓存可再定位性。您可以指示插件使用相对路径生成测试配置，以便通过在 gradle.properties 文件中添加以下代码来完全缓存 AndroidUnitTest 任务：

android.testConfig.useRelativePath = true

已知问题

  • 在使用 Kotlin Gradle 插件 1.3.31 或更早版本时，您可能会在构建或同步项目时看到以下警告：

    WARNING: API 'variant.getPackageLibrary()' is obsolete and has been replaced
         with 'variant.getPackageLibraryProvider()'.

    如需解决此问题，请将插件升级到 1.3.40 或更高版本。

3.4.0（2019 年 4 月）

此版本的 Android 插件需要使用以下工具：

3.4.3（2020 年 7 月）

本次要更新支持与 Android 11 中软件包可见性的新默认设置和功能兼容。

如需了解详情，请参阅 4.0.1 版本说明。

3.4.2（2019 年 7 月）

本次要更新对 Android Studio 3.4.2 构成补充，修复了各种 bug 并做出了多项性能改进。如需查看重要 bug 修复列表，请阅读版本更新博客上的相关博文。

3.4.1（2019 年 5 月）

本次要更新对 Android Studio 3.4.1 构成补充，修复了各种 bug 并做出了多项性能改进。如需查看重要 bug 修复列表，请阅读版本更新博客上的相关博文。

新功能

  • 新的 lint 检查依赖项配置：更改了 lintChecks 的行为并引入了新的依赖项配置 lintPublish，以便您可以更好地控制要将哪些 lint 检查打包到 Android 库中。

    • lintChecks：您应该将这个现有配置用于您想仅在本地构建项目时运行的 Lint 检查。您如果之前使用 lintChecks 依赖项配置将 lint 检查包含在已发布的 AAR 中，需要迁移这些依赖项并改用新的 lintPublish 配置（如下所述）。
    • lintPublish：针对您想要在已发布的 AAR 中包含的 lint 检查，在库项目中使用这个新配置（如下所示）。这意味着，使用库的项目也会应用那些 Lint 检查。

    以下代码示例在本地 Android 库项目中使用这两个依赖项配置。

    Groovy

    
dependencies {
// Executes lint checks from the ':lint' project at build time.
lintChecks project(':lint')
// Packages lint checks from the ':lintpublish' in the published AAR.
lintPublish project(':lintpublish')
}

    Kotlin

    
dependencies {
// Executes lint checks from the ':lint' project at build time.
lintChecks(project(":lint"))
// Packages lint checks from the ':lintpublish' in the published AAR.
lintPublish(project(":lintpublish"))
}

  • 一般来说，打包任务和为任务签名应该会加快整体构建速度。如果您发现与这些任务相关的性能退化，请报告错误。

行为变更

  • Android 免安装应用功能插件废弃警告：如果您仍在使用 com.android.feature 插件构建免安装应用，Android Gradle 插件 3.4.0 会向您发出废弃警告。为了确保您仍然可以在未来版本的插件上构建您的免安装应用，请迁移免安装应用，以使用动态功能插件，这样您还可以通过单个 Android App Bundle 发布安装版应用和免安装应用。

  • R8 默认处于启用状态：R8 将脱糖、压缩、混淆、优化和 dex 处理整合到了一个步骤中，从而显著提升了构建性能。R8 是在 Android Gradle 插件 3.3.0 中引入的，对于使用插件 3.4.0 及更高版本的应用和 Android 库项目，R8 现已默认处于启用状态。

    下图是 R8 引入之前的编译流程的简要概览。

    在 R8 之前，ProGuard 是一个与 dex 处理和脱糖不同的编译步骤。

    现在，有了 R8，可以在一个步骤中完成脱糖、压缩、混淆、优化和 dex 处理 (D8)，如下图所示。

    有了 R8，可以在一个编译步骤中执行脱糖、压缩、混淆、优化和 dex 处理。

    请注意，R8 旨在与您现有的 ProGuard 规则配合使用，因此您可能不需要采取任何操作即可从 R8 中受益。但是，相对专为 Android 项目设计的 ProGuard 而言，R8 是一项不同的技术，因此压缩和优化可能会导致移除 ProGuard 可能没有的代码。因此，在这种情况（尽管不太可能发生）下，您可能需要添加其他规则，以在构建输出中保留这些代码。

    如果您在使用 R8 时遇到问题，请阅读 R8 兼容性常见问题解答一文，以检查是否有针对您的问题的解决方案。如果没有记录的解决方案，请报告错误。您可以停用 R8，只需将以下其中一行代码添加到项目的 gradle.properties 文件即可：

    # Disables R8 for Android Library modules only.
android.enableR8.libraries = false
# Disables R8 for all modules.
android.enableR8 = false

  • ndkCompile 已废弃：现在，如果您尝试使用 ndkBuild 编译原生库，就会遇到构建错误。您应改用 CMake 或 ndk-build 将 C 和 C++ 代码添加到项目中。

已知问题

  • 虽然目前并未强制要求正确使用唯一软件包名称，但在以后的插件版本中这项要求会变得更为严格。在 Android Gradle 插件版本 3.4.0 上，您可以将下面这行代码添加到 gradle.properties 文件中，选择检查项目是否声明了可接受的软件包名称。

    android.uniquePackageNames = true

    如需详细了解如何通过 Android Gradle 插件设置软件包名称，请参阅设置应用 ID 一文。

3.3.0（2019 年 1 月）

此版本的 Android 插件需要使用以下工具：

3.3.3（2020 年 7 月）

本次要更新支持与 Android 11 中软件包可见性的新默认设置和功能兼容。

如需了解详情，请参阅 4.0.1 版本说明。

3.3.2（2019 年 3 月）

本次要更新对 Android Studio 3.3.2 构成补充，修复了各种 bug 并做出了多项性能改进。如需查看重要 bug 修复列表，请阅读版本更新博客上的相关博文。

3.3.1（2019 年 2 月）

本次要更新对 Android Studio 3.3.1 构成补充，修复了各种 bug 并做出了多项性能改进。

新功能

  • 改进了类路径同步：在解析对运行时和编译时类路径的依赖项时，Android Gradle 插件会尝试解决出现在多个类路径中的依赖项的某些下游版本冲突问题。

    例如，如果运行时类路径包含库 A 版本 2.0，而编译类路径包含库 A 版本 1.0，则插件会自动将对编译类路径的依赖关系更新为库 A 版本 2.0，以避免错误。

    不过，如果运行时类路径包含库 A 版本 1.0，而编译类路径包含库 A 版本 2.0，则插件不会将编译类路径的依赖项降级为库 A 版本 1.0，并且您会遇到错误。如需了解详情，请参阅解决类路径之间的冲突问题部分。

  • 改进了使用注解处理器时的增量 Java 编译：此更新改进了对使用注解处理器时的增量 Java 编译的支持，从而缩短了构建时间。

    • 对于使用 Kapt 的项目（大多数仅使用 Kotlin 的项目和混合使用 Kotlin-Java 的项目）：即使使用数据绑定或 retro-lambda 插件，也会启用增量 Java 编译。Kapt 任务进行的注解处理尚非增量处理。

    • 对于不使用 Kapt 的项目（仅使用 Java 的项目）：如果您使用的注解处理器都支持增量注解处理，就会默认启用增量 Java 编译。如需监控增量注释处理器的采用情况，请查看 Gradle 问题 5277。

      但是，如果有一个或多个注解处理器不支持增量构建，便不会启用增量 Java 编译。不过，您可以在 gradle.properties 文件中添加以下标记：

      android.enableSeparateAnnotationProcessing=true

      添加此标志后，Android Gradle 插件会在一个单独的任务中执行注解处理器，并允许 Java 编译任务以增量方式运行。

  • 使用过时 API 时显示更详细的调试消息：现在，当插件检测到您使用的 API 已不再受支持时，会提供更详细的信息，以帮助您确定该 API 的使用位置。如需查看其他信息，您需要在项目的 gradle.properties 文件中添加以下代码：

    android.debug.obsoleteApi=true

    您还可以通过在命令行中传递 -Pandroid.debug.obsoleteApi=true 来启用该标记。

  • 您可以从命令行对功能模块运行插桩测试。

行为变更

  • 延迟任务配置：现在，插件会使用 Gradle 的新任务创建 API 来避免初始化和配置完成当前编译不需要的任务（或执行任务图表上未列出的任务）。例如，如果您有多个 build 变体（如“发布”和“调试”build 变体），并且正在构建应用的“调试”版本，插件会避免初始化和配置应用“发布”版本的任务。

    如果调用 Variants API 中的某些旧方法（例如 variant.getJavaCompile()），可能仍会强制执行任务配置。为了确保您的 build 会针对延迟任务配置进行优化，请调用返回 TaskProvider 对象（例如 variant.getJavaCompileProvider()）的新方法。

    如果您执行自定义编译任务，请了解如何适应 Gradle 的新任务创建 API。

  • 对于指定的编译类型，在设置 useProguard false 时，插件现在会使用 R8（而不是 ProGuard）压缩和混淆应用的代码和资源。如需详细了解 R8，请阅读 Android 开发者博客上的这篇博文。

  • 为库项目更快地生成 R 类：以前，Android Gradle 插件会为项目的每个依赖项生成一个 R.java 文件，然后将这些 R 类和应用的其他类一起编译。现在，插件会直接生成包含应用的已编译 R 类的 JAR，而不会先编译中间的 R.java 类。这项优化不仅可以显著提升包含多个库子项目和依赖项的项目的编译性能，还可以加快在 Android Studio 中编制索引的速度。

  • 构建 Android App Bundle 时，由以 Android 6.0（API 级别 23）或更高版本为目标平台的 app bundle 生成的 APK 现在默认包含原生库的未压缩版本。这项优化无需设备创建库的副本，因此减少了应用占用的存储空间。如果您想要停用此优化，请在 gradle.properties 文件中添加以下代码：

    android.bundle.enableUncompressedNativeLibs = false

  • 插件会强制实施某些第三方插件的最低版本。

  • 单变体项目同步：将项目与 build 配置同步是让 Android Studio 了解项目结构的重要步骤。不过，对于大型项目，此过程可能非常耗时。如果您的项目使用了多个 build 变体，那么您现在可以限定仅同步当前所选的变体，从而优化项目同步操作。

    您需要结合使用 Android Studio 3.3 或更高版本与 Android Gradle 插件 3.3.0 或更高版本，才能启用此优化。满足这些要求后，Android Studio 会在您同步项目时提示您启用此优化。默认情况下，新项目也会启用此优化。

    如需手动启用此优化功能，请依次点击 File > Settings > Experimental > Gradle（在 Mac 上，则依次点击 Android Studio > Preferences > Experimental > Gradle），然后选中 Only sync the active variant 复选框。

    注意：此优化完全支持包含 Java 和 C++ 语言的项目，部分支持包含 Kotlin 语言的项目。在为包含 Kotlin 内容的项目启用此优化时，Gradle 同步会回退到在内部使用完整的变体。

  • 自动下载缺失的 SDK 软件包：此功能已经过扩展，可支持 NDK。如需了解详情，请阅读 Gradle 自动下载缺失软件包部分。

问题修复

  • Android Gradle 插件 3.3.0 修复了以下问题：

    • 尽管启用了 Jetifier，但构建流程调用的是 android.support.v8.renderscript.RenderScript，而不是 AndroidX 版本
    • 由于以下原因引起的冲突：androidx-rs.jar 包含静态绑定的 annotation.AnyRes
    • 使用 RenderScript 时，不必再在 build.gradle 文件中手动设置 Build Tools 版本

3.2.0（2018 年 9 月）

此版本的 Android 插件需要使用以下工具：

3.2.1（2018 年 10 月）

通过此次更新，您无需再为 SDK Build Tools 指定版本。Android Gradle 插件现在默认使用版本 28.0.3。

新功能

  • 支持构建 Android App Bundle：App Bundle 是一种全新的上传格式，其中包含应用的所有经过编译的代码和资源，但 APK 生成及签名工作则由 Google Play 商店完成。您无需再构建、签署和管理多个 APK，而用户也可以获得更小且已针对其设备优化的下载内容。如需了解详情，请阅读 Android App Bundle 简介一文。

  • 支持在使用注解处理器时加快增量构建速度：AnnotationProcessorOptions DSL 现在会扩展 CommandLineArgumentProvider，这可让您或注解处理器创建者使用增量构建属性类型注解来注解处理器的参数。使用这些注解可提高增量和缓存整洁 build 的正确性和性能。如需了解详情，请阅读向注释处理器传递参数部分。

  • 适用于 AndroidX 的迁移工具：在搭配使用 Android Gradle 插件 3.2.0 与 Android 3.2 及更高版本时，您可迁移项目的本地依赖项和 Maven 依赖项，以使用新的 AndroidX 库，方法是从菜单栏中依次选择 Refactor > Migrate to AndroidX。使用此迁移工具还会在 gradle.properties 文件中将以下标记设置为 true：

    • android.useAndroidX：如果设置为 true，Android 插件会使用对应的 AndroidX 库，而非支持库。如未指定此标记，该插件会默认将其设置为 false。
    • android.enableJetifier：如果设置为 true，Android 插件会通过重写其二进制文件来自动迁移现有的第三方库，以使用 AndroidX。如未指定此标记，该插件会默认将其设置为 false。只有在 android.useAndroidX 也被设置为 true 时，您才能将此标记设置为 true，否则会遇到构建错误。

    如需了解详情，请参阅 AndroidX 概览。

  • 新的代码缩减器 R8：R8 是一种执行代码缩减和混淆的新工具，替代了 ProGuard。您只需将以下代码添加到项目的 gradle.properties 文件中，即可开始使用 R8 的预览版本：

    Groovy

    
android.enableR8 = true

    Kotlin

    
android.enableR8 = true

行为变更

  • 使用 D8 进行脱糖的功能现已默认处于启用状态。

  • AAPT2 现在位于 Google 的 Maven 代码库中。如需使用 AAPT2，请确保您的 build.gradle 文件中包含 google() 依赖项，如下所示：

    Groovy

    
buildscript {
    repositories {
        google() // here
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.2.0'
    }
}
allprojects {
    repositories {
        google() // and here
        jcenter()
}

    Kotlin

    
buildscript {
    repositories {
        google() // here
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.2.0'
    }
}
allprojects {
    repositories {
        google() // and here
        jcenter()
}

  • 原生 MultiDex 现已默认处于启用状态。以前版本的 Android Studio 会在将应用的调试版本部署到搭载 Android API 级别 21 或更高级别的设备时启用原生多 dex 处理。现在，无论您是要部署到设备，还是要编译 APK 以供发布，Android Gradle 插件都会针对所有设置为 minSdkVersion=21（或更高版本）的模块启用原生多 dex 处理。

  • 该插件现在会强制执行最低版本的 protobuf 插件 (0.8.6)、Kotlin 插件 (1.2.50) 和 Crashlytics 插件 (1.25.4)。

  • 在指定模块名称时，功能模块插件 com.android.feature 现在强制要求仅使用字母、数字和下划线。例如，如果功能模块名称包含短划线，您会遇到构建错误。此行为与动态功能插件的行为相符。

问题修复

  • JavaCompile 现在可以在具有数据绑定的项目中缓存。（问题 #69243050）
  • 为启用了数据绑定的库模块提供更好的避免编译功能。（问题 #77539932）
  • 如果您因为一些不可预知的构建错误而在早期版本中停用了按需配置，现在可以重新启用。（问题 77910727）

3.1.0（2018 年 3 月）

此版本的 Android 插件需要使用以下工具：

  • Gradle 4.4 或更高版本。如需了解详情，请阅读有关更新 Gradle 的部分。
  • Build Tools 27.0.3 或更高版本。请注意，您不必再使用 android.buildToolsVersion 属性指定 Build Tools 的版本。默认情况下，该插件会使用所需的最低版本。

新的 DEX 编译器 (D8)

默认情况下，Android Studio 现在会使用名为 D8 的新 DEX 编译器。DEX 编译是指针对 Android 运行时（对于较早版本的 Android，则针对 Dalvik）将 .class 字节码转换为 .dex 字节码的过程。与之前的编译器（称为 DX）相比，D8 的编译速度更快，输出的 DEX 文件更小，同时却能保持相同甚至更出色的应用运行时性能。

D8 应该不会改变您的日常应用开发工作流程。但是，如果您遇到与新编译器有关的任何问题，请报告错误。您可以在项目的 gradle.properties 文件中添加以下代码，暂时停用 D8 并使用 DX：

android.enableD8=false

对于使用 Java 8 语言功能的项目，系统会默认启用增量脱糖。您可以在项目的 gradle.properties 文件中添加以下代码，停用增量脱糖：

android.enableIncrementalDesugaring=false.

预览版用户：如果您已在使用预览版 D8，则请注意，D8 现在会针对 SDK Build Tools（而非 JDK）中包含的库进行编译。因此，如果您访问的 API 存在于 JDK 而非 SDK Build Tools 库中，您会遇到编译错误。

行为变更

  • 在构建分别以不同 ABI 为目标的多个 APK 时，默认情况下，插件不会再针对以下 ABI 生成 APK：mips、mips64 和 armeabi。

    如果您想构建以上述 ABI 为目标的 APK，必须使用 NDK r16b 或更低版本，并在 build.gradle 文件中指定这些 ABI，如下所示：

Groovy

  splits {
      abi {
          include 'armeabi', 'mips', 'mips64'
          ...
      }
  }

Kotlin

  splits {
      abi {
          include("armeabi", "mips", "mips64")
          ...
      }
  }
  • 现在，Android 插件的构建缓存会排除超过 30 天的缓存条目。
  • 将 "auto" 传递给 resConfig 不会再自动选择要打包到 APK 中的字符串资源。如果继续使用 "auto"，该插件会打包应用及其依赖项提供的所有字符串资源。因此，您应该指定希望插件打包到 APK 中的各个语言区域。

  • 由于本地模块不能依赖应用的测试 APK，因此使用 androidTestApi 配置（而非 androidTestImplementation）将依赖项添加到插桩测试中会导致 Gradle 发出以下警告：

    Groovy

    


    WARNING: Configuration 'androidTestApi' is obsolete
  and has been replaced with 'androidTestImplementation'

    Kotlin

    


    WARNING: Configuration 'androidTestApi' is obsolete
  and has been replaced with 'androidTestImplementation'

修复

  • 修复了 Android Studio 无法正确识别复合构建中的依赖项问题。
  • 修复了以下问题：如果在进行单次构建时多次加载 Android 插件（例如，有多个子项目，并且每个子项目的构建脚本类路径中都包含 Android 插件），您会遇到项目同步错误。

3.0.0（2017 年 10 月）

Android Gradle 插件 3.0.0 包含各种旨在解决大型项目性能问题的更改。

例如，在一个具有大约 130 个模块和大量外部依赖项但没有代码或资源的示例框架项目上，您可以体验到与以下类似的性能提升：

Android 插件版本 + Gradle 版本 Android 插件 2.2.0 + Gradle 2.14.1 Android 插件 2.3.0 + Gradle 3.3 Android 插件 3.0.0 + Gradle 4.1
配置（例如，运行 ./gradlew --help） 大约 2 分钟 大约 9 秒 大约 2.5 秒
1 行 Java 更改（实现更改） 大约 2 分 15 秒 大约 29 秒 大约 6.4 秒

其中某些更改会让现有 build 出现异常。因此，您应该考虑在使用新插件之前迁移您的项目。

如果您没有体验到上述性能提升，请提交错误并使用 Gradle 性能剖析器添加 build 的跟踪记录。

此版本的 Android 插件需要使用以下工具：

  • Gradle 4.1 或更高版本。如需了解详情，请阅读有关更新 Gradle 的部分。
  • Build Tools 26.0.2 或更高版本。经过此次更新，您无需再指定 Build Tools 的版本。默认情况下，该插件会使用所需的最低版本。因此，您现在可以移除 android.buildToolsVersion 属性了。

3.0.1（2017 年 11 月）

本次要更新支持 Android Studio 3.0.1，修复了各种 bug 并做出了多项性能改进。

优化

  • 通过精细控制的任务图提升了多模块项目的并行性。
  • 更改依赖项时，Gradle 通过不重新编译无法访问该依赖项 API 的模块来加快构建速度。您应利用 Gradle 的新依赖项配置（implementation、api、compileOnly 和 runtimeOnly）限制哪些依赖项会将其 API 泄露给其他模块。
  • 借助每个类的 dex 处理，可加快增量构建速度。每个类现在都会编译成单独的 DEX 文件，并且只会对修改过的类重新进行 dex 处理。对于将 minSdkVersion 设置为 20（或更低数值）并使用旧版多 dex 处理的应用，编译速度应该也会得到改善。
  • 通过优化某些任务来使用缓存的输出，从而加快构建速度。如需利用此项优化，您需要先启用 Gradle 构建缓存。
  • 使用 AAPT2（现已默认处于启用状态）改进了增量资源处理。如果您在使用 AAPT2 时遇到问题，请报告错误。您也可以停用 AAPT2，方法是在 gradle.properties 文件中设置 android.enableAapt2=false，然后通过在命令行中运行 ./gradlew --stop 来重启 Gradle 守护进程。

新功能

  • 变体感知依赖项管理。现在，在构建某个模块的特定变体时，插件会自动将本地库模块依赖项的变体与您正在构建的模块变体进行匹配。
  • 加入了新的功能模块插件，以支持 Android 免安装应用和 Android 免安装应用 SDK（您可以使用 SDK 管理器下载）。如需详细了解如何使用新插件创建功能模块，请参阅包含多个功能的免安装应用的结构。
  • 对使用某些 Java 8 语言功能和 Java 8 库提供内置支持。Jack 现已废弃且无需再使用，您应先停用 Jack，才能使用默认工具链内置的已改进 Java 8 支持。有关详情，请阅读使用 Java 8 语言功能一文。
  • 添加了对使用 Android Test Orchestrator 运行测试的支持，可让您在测试自己的 Instrumentation 调用中运行每一项应用测试。因为每个测试都是在自己的 Instrumentation 实例中运行，所以测试之间的共享状态也不会在设备的 CPU 或内存上累积。而且，即使有一个测试崩溃了，也只会破坏它自己的 Instrumentation 实例，而其他测试仍会正常运行。
    • 添加了 testOptions.execution，以确定是否使用设备上的测试编排。如果您想使用 Android Test Orchestrator，则需要指定 ANDROID_TEST_ORCHESTRATOR（如下所示）。默认情况下，此属性会设置为 HOST，这会停用设备上的编配，并且是运行测试的标准方法。

Groovy

android {
  testOptions {
    execution 'ANDROID_TEST_ORCHESTRATOR'
  }
}

Kotlin

android {
  testOptions {
    execution = "ANDROID_TEST_ORCHESTRATOR"
  }
}
  • 新的 androidTestUtil 依赖项配置允许您在运行插桩测试（例如 Android Test Orchestrator）之前安装其他测试辅助程序 APK：

Groovy

dependencies {
  androidTestUtil 'com.android.support.test:orchestrator:1.0.0'
  ...
}

Kotlin

dependencies {
  androidTestUtil("com.android.support.test:orchestrator:1.0.0")
  ...
}
  • 添加了 testOptions.unitTests.includeAndroidResources，以支持需要 Android 资源（例如 Roboelectric）的单元测试。如果您将此属性设置为 true，插件便会在运行单元测试之前执行资源、资产和清单合并。然后，测试便会检查 com/android/tools/test_config.properties 的类路径是否具有以下键：
    • android_merged_assets：已合并资产目录的绝对路径。

      注意：对于库模块，已合并资产不会包含依赖项的资产（详见问题 #65550419）。

    • android_merged_manifest：已合并清单文件的绝对路径。
    • android_merged_resources：已合并资源目录的绝对路径，其中包含模块中的所有资源以及模块的所有依赖项。
    • android_custom_package：最终 R 类的软件包名称。如果动态修改应用 ID，则此软件包名称可能与应用清单中的 package 属性不匹配。
  • 支持以资源形式使用字体（这是在 Android 8.0（API 级别 26） 中推出的新功能）。
  • 支持集成了 Android 免安装应用 SDK 1.1 及更高版本的特定语言 APK。
  • 您现在可以更改外部原生构建项目的输出目录，如下所示：

Groovy

android {
    ...
    externalNativeBuild {
        // For ndk-build, instead use the ndkBuild block.
        cmake {
            ...
            // Specifies a relative path for outputs from external native
            // builds. You can specify any path that's not a subdirectory
            // of your project's temporary build/ directory.
            buildStagingDirectory "./outputs/cmake"
        }
    }
}

Kotlin

android {
    ...
    externalNativeBuild {
        // For ndk-build, instead use the ndkBuild block.
        cmake {
            ...
            // Specifies a relative path for outputs from external native
            // builds. You can specify any path that's not a subdirectory
            // of your project's temporary build/ directory.
            buildStagingDirectory = "./outputs/cmake"
        }
    }
}
  • 现在，从 Android Studio 中构建原生项目时，您可以使用 CMake 3.7 或更高版本。
  • 您可以使用新的 lintChecks 依赖项配置构建用于定义自定义 lint 规则的 JAR，并将其打包到您的 AAR 和 APK 项目中。您的自定义 lint 规则必须属于单独的项目，该项目输出单个 JAR 并且仅包含 compileOnly 依赖项。然后，其他应用和库模块可以依赖于使用 lintChecks 配置的 lint 项目：

Groovy

dependencies {
    // This tells the Gradle plugin to build ':lint-checks' into a lint.jar file
    // and package it with your module. If the module is an Android library,
    // other projects that depend on it automatically use the lint checks.
    // If the module is an app, lint includes these rules when analyzing the app.
    lintChecks project(':lint-checks')
}

Kotlin

dependencies {
    // This tells the Gradle plugin to build ':lint-checks' into a lint.jar file
    // and package it with your module. If the module is an Android library,
    // other projects that depend on it automatically use the lint checks.
    // If the module is an app, lint includes these rules when analyzing the app.
    lintChecks(project(":lint-checks"))
}

行为变更

  • Android 插件 3.0.0 移除了某些 API。如果您使用这些 API，您的 build 将会出现异常。例如，您无法再使用 Variants API 访问 outputFile() 对象，或使用 processManifest.manifestOutputFile() 获取各个变体的清单文件。如需了解详情，请参阅 API 变更部分。
  • 您无需再指定 Build Tools 的版本（因此，您现在可以移除 android.buildToolsVersion 属性了）。默认情况下，插件会针对所用 Android 插件的版本自动使用所需的最低版 Build Tools。
  • 现在，您可以在 buildTypes 代码块中启用/停用 PNG 处理（如下所示）。默认情况下，会为所有 build 启用 PNG 处理；但调试 build 除外，因为它会增加包含许多 PNG 文件的项目的构建时间。因此，为了缩短其他 build 类型的构建时间，您应该停用 PNG 处理或将图片转换成 WebP 格式。

Groovy

android {
  buildTypes {
    release {
      // Disables PNG crunching for the release build type.
      crunchPngs false
    }
  }
}

Kotlin

android {
  buildTypes {
    release {
      // Disables PNG crunching for the release build type.
      isCrunchPngs = false
    }
  }
}
  • Android 插件现在会自动构建您在外部 CMake 项目中配置的可执行目标。
  • 现在，您必须使用 annotationProcessor 依赖项配置将注解处理器添加到处理器类路径中。
  • 现在，使用已废弃的 ndkCompile 会受到更多限制。您应该改用 CMake 或 ndk-build 来编译要打包到 APK 中的原生代码。如需了解详情，请阅读从 ndkcompile 迁移。

2.3.0（2017 年 2 月）

2.3.3（2017 年 6 月）

本次要更新添加了与 Android Studio 2.3.3 的兼容性。

2.3.2（2017 年 5 月）

本次要更新添加了与 Android Studio 2.3.2 的兼容性。

2.3.1（2017 年 4 月）

这是针对 Android 插件 2.3.0 的次要更新，修复了某些 Android 物理设备无法正确使用 Instant Run 的问题（详见问题 #235879）。

依赖项：
新变化：
  • 使用 Gradle 3.3，其中包括性能改进和新功能。如需了解详情，请参阅 Gradle 版本说明。
  • 构建缓存：存储构建项目时 Android 插件生成的特定输出（例如，未打包的 AAR 和经过 dex 预处理的远程依赖项）。使用缓存时，干净构建的速度会显著加快，因为构建系统在进行后续构建时可以直接重用这些缓存的文件，而无需重新创建。使用 Android 插件 2.3.0 及更高版本的项目在默认情况下会使用构建缓存。如需了解详情，请参阅有关使用构建缓存加快构建速度的文章。
    • 加入了清除构建缓存的 cleanBuildCache 任务。
    • 如果您使用的是构建缓存的实验性版本（包含在早期版本的插件中），则应将插件更新到最新版本。
变更：

2.2.0（2016 年 9 月）

依赖项：
新变化：
  • 使用 Gradle 2.14.1，其中加入了一些性能改进和新功能，并修复了在使用 Gradle 守护程序时允许获取本地特权的安全漏洞。如需了解详情，请参阅 Gradle 版本说明。
  • 利用 externalNativeBuild {} DSL，Gradle 现在可让您链接到自己的原生源代码，并使用 CMake 或 ndk-build 编译原生库。构建原生库后，Gradle 会将它们打包到您的 APK 中。如需详细了解如何在 Gradle 中使用 CMake 和 ndk-build，请阅读向您的项目添加 C 和 C++ 代码一文。
  • 当您从命令行运行 build 时，Gradle 现在会尝试自动下载项目依赖但缺失的 SDK 组件或更新。如需了解详情，请阅读 Gradle 自动下载缺失软件包部分。
  • 新的实验性缓存功能可让 Gradle 通过 dex 预处理、存储和重复使用库的 dex 预处理版本来缩短构建时间。如需详细了解如何使用此实验性功能，请阅读构建缓存指南。
  • 通过采用在一个任务中处理压缩、签名和压缩对齐操作的新默认打包管道，提升了构建性能。您可以通过在 gradle.properties 文件中添加 android.useOldPackaging=true 来恢复使用旧的打包工具。在使用新的打包工具时，zipalignDebug 任务将不可用。不过，您可以调用 createZipAlignTask(String taskName, File inputFile, File outputFile) 方法来自己创建一个。
  • 除了传统的 JAR 签名，APK 签名现在还会使用 APK 签名方案 v2。所有 Android 平台都接受生成的 APK。如果在签名后修改这些 APK，那么它们的 v2 签名便会失效，并会阻止在设备上安装。如需停用此功能，请将以下代码添加到模块级 build.gradle 文件中：

    Groovy

    android {
  ...
  signingConfigs {
    config {
      ...
      v2SigningEnabled false
    }
  }
}

    Kotlin

    android {
  ...
  signingConfigs {
    create("config") {
      ...
      v2SigningEnabled = false
    }
  }
}
  • 对于 MultiDex 构建，您现在可以使用 ProGuard 规则来确定 Gradle 应该将哪些类编译到应用的主 DEX 文件中。因为 Android 系统在启动应用时会先加载主 DEX 文件，所以您可以在启动时通过将它们编译到主 DEX 文件中来确定某些类的优先级。在您专门为主 DEX 文件创建 ProGuard 配置文件后，请使用 buildTypes.multiDexKeepProguard 将该配置文件的路径传递给 Gradle。使用此 DSL 与使用 buildTypes.proguardFiles 不同，后者会提供应用的常规 ProGuard 规则，并且不会指定主 DEX 文件的类。
  • 添加了对 android:extractNativeLibs 标记的支持，该标记可在应用安装到设备的过程中缩小应用的大小。如果您在应用清单的 <application> 元素中将此标志设置为 false，Gradle 会将未压缩的对齐版原生库和 APK 打包在一起。这可防止 PackageManager 在安装过程中将原生库从 APK 复制到设备的文件系统，同时还有助于减小应用增量更新。
  • 您现在可以针对产品变种指定 versionNameSuffix 和 applicationIdSuffix。（问题 59614）
变更：
  • getDefaultProguardFile 现在会返回 Android Plugin for Gradle 提供的默认 ProGuard 文件，并且不再使用 Android SDK 中的那些文件。
  • 改进了 Jack 编译器的性能和功能：
    • 在将 testCoverageEnabled 设置为 true 后，Jack 现在支持 Jacoco 测试覆盖率。
    • 改进了对注解处理器的支持。类路径上的注解处理器（例如任意 compile 依赖项）会自动应用于您的 build。您还可以在 build 中指定注解处理器，并通过在模块级 build.gradle 文件中使用 javaCompileOptions.annotationProcessorOptions {} DSL 来传递参数：

      Groovy

      android {
  ...
  defaultConfig {
    ...
    javaCompileOptions {
      annotationProcessorOptions {
        className 'com.example.MyProcessor'
        // Arguments are optional.
        arguments = [ foo : 'bar' ]
      }
    }
  }
}

      Kotlin

      android {
  ...
  defaultConfig {
    ...
    javaCompileOptions {
      annotationProcessorOptions {
        className = "com.example.MyProcessor"
        // Arguments are optional.
        arguments(mapOf(foo to "bar"))
      }
    }
  }
}

      如果要在编译时应用注解处理器，但不将其包含在 APK 中，请使用 annotationProcessor 依赖项范围：

      Groovy

      dependencies {
    compile 'com.google.dagger:dagger:2.0'
    annotationProcessor 'com.google.dagger:dagger-compiler:2.0'
   // or use buildVariantAnnotationProcessor to target a specific build variant
}

      Kotlin

      dependencies {
    implementation("com.google.dagger:dagger:2.0")
    annotationProcessor("com.google.dagger:dagger-compiler:2.0")
   // or use buildVariantAnnotationProcessor to target a specific build variant
}

      • 如需查看您可以设置的参数的列表，请从命令行中运行以下命令： 

      java -jar /build-tools/jack.jar --help-properties
    • 默认情况下，如果 Gradle 守护进程的堆大小至少为 1.5 GB，那么 Jack 现在会与 Gradle 在同一进程中运行。如需调整守护进程的堆大小，请将以下代码添加到 gradle.properties 文件中： 
      # This sets the daemon heap size to 1.5GB.
org.gradle.jvmargs=-Xmx1536M

2.1.0（2016 年 4 月）

2.1.3（2016 年 8 月）

此更新需要使用 Gradle 2.14.1 及更高版本。Gradle 2.14.1 加入了一些性能改进、新功能和一个重要的安全修复程序。如需了解详情，请参阅 Gradle 版本说明。

依赖项：
新变化：
  • 添加了对 N 开发者预览版、JDK 8 以及使用 Jack 工具链的 Java 8 语言功能的支持。如需了解详情，请阅读 N 预览版指南。

    注意：Instant Run 目前无法用于 Jack，在使用新的工具链时将被停用。如果您正在为 N 预览版开发应用，并希望使用受支持的 Java 8 语言功能，只需使用 Jack 即可。

  • 添加了对增量 Java 编译的默认支持，以在开发过程中缩短编译时间。这种编译方式仅对已发生变化或需要重新编译的那部分源代码进行重新编译。如需停用此功能，请将以下代码添加到模块级 build.gradle 文件中：

    Groovy

    android {
  ...
  compileOptions {
    incremental false
  }
}

    Kotlin

    android {
  ...
  compileOptions {
    incremental = false
  }
}

  • 添加了对 dexing-in-process 的支持。dexing-in-process 会在构建流程（而不是单独的外部虚拟机流程）中执行 dex 处理。这样不仅可以让增量构建更快，还可以加快完整构建的速度。对于已将 Gradle 守护程序的最大堆大小设置为不小于 2048MB 的项目，该功能默认处于启用状态。如需进行设置，您可以将以下代码添加到项目的 gradle.properties 文件中：

    ```none org.gradle.jvmargs = -Xmx2048m ```

    如果您已经在模块级 build.gradle 文件中为 javaMaxHeapSize 定义值，则需要将 org.gradle.jvmargs 的值设置为“javaMaxHeapSize + 1024MB”的结果。例如，如果您将 javaMaxHeapSize 设置为“2048m”，则需要将以下代码添加到项目的 gradle.properties 文件中：

    ```none org.gradle.jvmargs = -Xmx3072m ```

    如需停用 dexing-in-process，请将以下代码添加到模块级 build.gradle 文件中：

    Groovy

    android {
  ...
  dexOptions {
      dexInProcess false
  }
}

    Kotlin

    android {
  ...
  dexOptions {
      dexInProcess = false
  }
}

2.0.0（2016 年 4 月）

依赖项：
新变化：
  • 通过支持字节码注入，然后将代码和资源更新推送到模拟器或物理设备上正在运行的应用，来启用 Instant Run。
  • 添加了对增量构建的支持，即使应用未运行也支持。 通过 Android 调试桥将增量更改推送到连接的设备，缩短了完整构建的时间。
  • 添加了 maxProcessCount，以控制可以同时衍生多少个工作器 dex 处理进程。以下代码在模块级 build.gradle 文件中将最大并发进程数设置为 4：

    Groovy

    android {
  ...
  dexOptions {
    maxProcessCount = 4 // this is the default value
  }
}

    Kotlin

    android {
  ...
  dexOptions {
    maxProcessCount = 4 // this is the default value
  }
}
  • 添加了实验性代码缩减器，以支持 dex 预处理和减少对依赖项的重复 dex 处理，而这些不受 Proguard 支持。这提高了调试 build 变体的构建速度。由于实验性缩减器不支持优化和混淆处理功能，因此您应该为发布 build 启用 Proguard。如需为调试 build 启用实验性缩减器，请将以下代码添加到模块级 build.gradle 文件中：

    Groovy

    android {
  ...
  buildTypes {
    debug {
      minifyEnabled true
      useProguard false
    }
    release {
      minifyEnabled true
      useProguard true // this is a default setting
    }
  }
}

    Kotlin

    android {
  ...
  buildTypes {
    getByName("debug") {
      minifyEnabled = true
      useProguard = false
    }
    getByName("release") {
      minifyEnabled = true
      useProguard = true // this is a default setting
    }
  }
}
  • 为资源缩减器添加了日志记录支持并提升了性能。资源压缩器现在会将其所有操作记录到与 Proguard 日志文件位于同一文件夹的 resources.txt 文件中。
改变的行为：
  • 如果将 minSdkVersion 设置为 18 或更高，APK 签名会使用 SHA256。
  • DSA 和 ECDSA 密钥现在可对 APK 软件包进行签名。

    注意：从 Android 6.0（API 级别 23）开始，Android Keystore 提供程序不再支持 DSA 密钥。

修复的问题：
  • 修复了导致在测试和主 build 配置中出现重复 AAR 依赖项的问题。

旧版本

上一页
SDK 构建工具
下一页
Android Gradle 插件路线图