Android Gradle 插件版本说明

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

本页将介绍如何让 Gradle 工具保持最新状态，以及最近的更新都包含哪些内容。

要详细了解如何使用 Gradle 配置 Android 构建版本，请参阅以下页面：

要详细了解 Gradle 构建系统，请参阅 Gradle 用户指南。

更新 Android Gradle 插件

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

您可以在 Android Studio 的 File > Project Structure > Project 菜单中指定插件版本，也可以在顶级 build.gradle 文件中进行指定。该插件版本适用于在相应 Android Studio 项目中构建的所有模块。以下示例从 build.gradle 文件中将插件的版本设置为 3.5.2：

    buildscript {
        repositories {
            // Gradle 4.1 and higher include support for Google's Maven repo using
            // the google() method. And you need to include this repo to download
            // Android Gradle plugin 3.0.0 or higher.
            google()
            ...
        }
        dependencies {
            classpath 'com.android.tools.build:gradle:3.5.2'
        }
    }

注意：请勿在版本号中采用动态依赖项（例如 'com.android.tools.build:gradle:2.+'），否则可能会导致意外的版本更新和难以解析的版本差异。

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

更新 Gradle

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

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

插件版本所需的 Gradle 版本
1.0.0 - 1.1.32.2.1 - 2.3
1.2.0 - 1.3.12.2.1 - 2.9
1.5.02.2.1 - 2.13
2.0.0 - 2.1.22.10 - 2.13
2.1.3 - 2.2.32.14.1+
2.3.0+3.3+
3.0.0+4.1+
3.1.0+4.4+
3.2.0 - 3.2.14.6+
3.3.0 - 3.3.24.10.1+
3.4.0 - 3.4.15.1.1+
3.5.0+5.4.1-5.6.4

您可以在 Android Studio 的 File > Project Structure > Project 菜单中指定 Gradle 版本，也可以通过在 gradle/wrapper/gradle-wrapper.properties 文件中修改 Gradle 分发引用来指定。以下示例在 gradle-wrapper.properties 文件中将 Gradle 的版本设置为 5.4.1。

    ...
    distributionUrl = https\://services.gradle.org/distributions/gradle-5.4.1-all.zip
    ...

3.5.0（2019 年 8 月）

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

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

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

3.5.3（2019 年 12 月）

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

3.5.2（2019 年 11 月）

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

3.5.1（2019 年 10 月）

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

增量注释处理

如果您在 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.2（2019 年 7 月）

本次要更新支持 Android Studio 3.4.2，修复了各种错误并做出了多项性能改进。要查看重要问题修复列表，请阅读版本更新博客上的相关博文。

3.4.1（2019 年 5 月）

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

新功能

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

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

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

    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.2（2019 年 3 月）

本次要更新支持 Android Studio 3.3.2，修复了各种错误并做出了多项性能改进。要查看重要问题修复列表，请阅读版本更新博客上的相关博文。

3.3.1（2019 年 2 月）

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

新功能

  • 改进了类路径同步：在解析对运行时和编译时类路径的依赖项时，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 来避免初始化和配置完成当前编译不需要的任务（或执行任务图表上未列出的任务）。例如，如果您有多个编译变体（如“发布”和“调试”编译变体），并且正在编译应用的“调试”版本，则该插件会避免初始化和配置应用“发布”版本的任务。

    如果调用 Variants API 中的某些旧方法（例如 variant.getJavaCompile()），可能仍会强制执行任务配置。为了确保您的编译版本会针对延迟任务配置进行优化，请调用返回 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

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

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

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

    要手动启用此优化功能，请依次点击 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：Android App Bundle 是一种全新的上传格式，其中包含应用的所有经过编译的代码和资源，但 APK 生成及签名工作则由 Google Play 商店完成。您无需再编译、签署和管理多个 APK，而用户也可以获得更小且已针对其设备优化的下载内容。要了解详情，请阅读 Android App Bundle 简介一文。

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

  • 适用于 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 的预览版本：

    android.enableR8 = true

行为变更

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

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

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

  • 原生多 dex 处理现已默认处于启用状态。在将应用的调试版本部署到搭载 Android API 级别 21（或更高级别）的设备时，旧版 Android Studio 会启用原生多 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，如下所示：

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

  • 在为 Android 免安装应用编译配置 APK 时，针对语言的配置拆分项现在默认按根语言分组。例如，如果您的应用包含用于 zh-TW 或 zh-CN 语言区域的资源，Gradle 将在 zh 语言的配置拆分项中打包这些资源。您可以通过使用 include 属性定义自己的分组来替换此行为，如下所示：

    splits {
        language {
            enable true
            // Each string defines a group of locales that
            // Gradle should package together.
            include "in,id",
                    "iw,he",
                    "fil,tl,tgl",
                    "yue,zh,zh-TW,zh-CN"
        }
    }

  • 现在，Android 插件的编译缓存会排除超过 30 天的缓存条目。

  • 将 "auto" 传递给 resConfig 不会再自动选择要打包到 APK 中的字符串资源。如果继续使用 "auto"，该插件会打包应用及其依赖项提供的所有字符串资源。因此，您应该指定希望插件打包到 APK 中的各个语言区域。

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

      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 秒

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

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

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

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

3.0.1（2017 年 11 月）

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

优化

  • 通过精细控制的任务图提升了多模块项目的并行性。
  • 更改依赖项时，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 Manager 下载）。要详细了解如何使用新插件创建功能模块，请参阅包含多个功能的免安装应用的结构。
  • 对使用某些 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，这会停用设备上的编配，并且是运行测试的标准方法。
    android {
      testOptions {
        execution 'ANDROID_TEST_ORCHESTRATOR'
      }
    }
  • 新的 androidTestUtil 依赖项配置允许您在运行插桩测试（例如 Android Test Orchestrator）之前安装其他测试辅助程序 APK：
    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。如需了解详情，请参阅为纯拆分项配置编译版本。
  • 您现在可以更改外部原生编译项目的输出目录，如下所示：
    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 项目：
    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，您的编译版本将会出现异常。例如，您无法再使用 Variants API 访问 outputFile() 对象，或使用 processManifest.manifestOutputFile() 获取各个变体的清单文件。要了解详情，请参阅 API 变更部分。
  • 您无需再指定 Build Tools 的版本（因此，您现在可以移除 android.buildToolsVersion 属性了）。默认情况下，插件会针对所用 Android 插件的版本自动使用所需的最低版 Build Tools。
  • 您现在可以在 buildTypes 块中启用 PNG 处理了。（如下所示）。默认情况下，会为所有编译版本启用 PNG 处理；但调试编译版本除外，因为它会增加包含许多 PNG 文件的项目的编译时间。因此，为了缩短其他编译类型的编译时间，您应该停用 PNG 处理或将图片转换成 WebP 格式。
    android {
      buildTypes {
        release {
          // Disables PNG crunching for the release build type.
          crunchPngs 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++ 代码一文。
  • 当您从命令行运行编译时，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 文件中： 
        android {
      ...
      signingConfigs {
        config {
          ...
          v2SigningEnabled false
        }
      }
    }
  • 对于多 dex 文件编译，您现在可以使用 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.gradle 文件中使用 javaCompileOptions.annotationProcessorOptions {} DSL 来传递参数： 
          android {
      ...
      defaultConfig {
        ...
        javaCompileOptions {
          annotationProcessorOptions {
            className 'com.example.MyProcessor'
            // Arguments are optional.
            arguments = [ foo : 'bar' ]
          }
        }
      }
    }

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

          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
    }
    • 您可以使用 jackOptions.additionalParameters() 来设置 Jack 的其他标记。以下代码段将 jack.incremental 参数设置为 true： 
          android {
      defaultConfig {
        ...
        jackOptions {
          enabled true
          additionalParameters("jack.incremental" : true)
        }
      }
    }

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

          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 文件中： 
        android {
      ...
      compileOptions {
        incremental false
      }
    }

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

        org.gradle.jvmargs = -Xmx2048m

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

        org.gradle.jvmargs = -Xmx3072m

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

        android {
      ...
      dexOptions {
          dexInProcess false
      }
    }

2.0.0（2016 年 4 月）

依赖项：
新变化：
  • 通过支持字节码注入，然后将代码和资源更新推送到模拟器或物理设备上正在运行的应用，来启用 Instant Run。
  • 添加了对增量编译的支持，即使应用未运行也支持。 通过 Android 调试桥将增量更改推送到连接的设备，缩短了完整编译的时间。
  • 添加了 maxProcessCount，以控制可以同时衍生多少个从属的 dex 处理进程。以下代码在模块级 build.gradle 文件中将最大并发进程数设置为 4： 
        android {
      ...
      dexOptions {
        maxProcessCount = 4 // this is the default value
      }
    }
  • 添加了实验性代码压缩器，以支持 dex 预处理和减少对依赖项的重复 dex 处理，而这些不受 Proguard 支持。这提高了调试编译变体的编译速度。由于实验性压缩器不支持优化和混淆，因此您应该为发布编译启用 Proguard。要为调试编译启用实验性压缩器，请将以下内容添加到模块级 build.gradle 文件中： 
        android {
      ...
      buildTypes {
        debug {
          minifyEnabled true
          useProguard false
        }
        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 密钥。

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

旧版本

السابق
SDK 构建工具
التالي
SDK 平台