Google 致力于为黑人社区推动种族平等。查看具体举措

Android Gradle 插件版本说明

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

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

如需详细了解如何使用 Gradle 配置 Android build,请参阅以下页面:

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

更新 Android Gradle 插件

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

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

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:4.0.0'
    }
}

注意:不应在版本号中使用动态依赖项(如 '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.34.10.1+
3.4.0 - 3.4.35.1.1+
3.5.0 - 3.5.45.4.1+
3.6.0 - 3.6.45.6.4+
4.0.0+6.1.1+
4.1.0+6.5+

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

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

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 Surface,以使未来扩展 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 代码块中:

buildFeatures {
    prefabPublishing true
}

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

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

在本例中,您的 ndk-build 或 CMake 外部原生 build 中的 mylibrarymyotherlibrary 库会打包到您的 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 库和应用大小

行为变更

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

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

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

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

设置 NDK 路径

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

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

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

库单元测试行为变更

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

在某些情况下,使用数据绑定的库单元测试可能会遇到缺少 DataBindingComponentBR 类的情况。这些测试需要移植到 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 分析您的 build 时,它会计算决定 build 时长的一组任务,并提供直观的图表,以帮助您了解其中每项任务所产生的影响。您也可以展开 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.Optionaljava.util.OptionalIntjava.util.OptionalDouble)以及对上述 API 很有用的一些其他新类
  • java.util.concurrent.atomic 的一些新增内容(AtomicIntegerAtomicLongAtomicReference 的新方法)
  • ConcurrentHashMap(包含 Android 5.0 的问题修复)

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

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

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'
}

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

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

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 的依赖性,如下所示:

// 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 文件中添加以下代码来选择退出:

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.solibcurl.so 并将 libcurl.so 打包在 APK 或 App Bundle 中。如需了解详情,请参阅 curl prefab 示例

行为变更

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

移除了“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 文件中配置的某个其他目录中:

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']
    }
}

有了 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 文件中添加以下代码:

android {
    viewBinding.enabled = true
}

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

支持 Maven Publish 插件

Android Gradle 插件支持 Maven Publish Gradle 插件,可让您将构建工件发布到 Apache Maven 代码库。Android Gradle 插件会为应用或库模块中的每个构建变体工件创建一个组件,您可以使用它来自定义要发布到 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 单元测试在内的所有单元测试都可以完全缓存。如需了解详情,请参阅问题 #126775542

问题修复

此版本的 Android Gradle 插件包含以下问题修复:

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

已知问题

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

Android Lint 任务的执行速度过慢

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

此问题会报告为 IDEA 错误,并将在 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 开发者工具的三大核心领域进行改进,分别是系统运行状况、功能完善和错误修复。值得注意的是,本次更新的重中之重是提高项目的构建速度

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

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

3.5.4(2020 年 7 月)

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

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

3.5.3(2019 年 12 月)

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

3.5.2(2019 年 11 月)

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

3.5.1(2019 年 10 月)

本次要更新对 Android Studio 3.4.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.3(2020 年 7 月)

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

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

3.4.2(2019 年 7 月)

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

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.3(2020 年 7 月)

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

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

3.3.2(2019 年 3 月)

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

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()),可能仍会强制执行任务配置。为了确保您的 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
    
  • 插件会强制实施某些第三方插件的最低版本。

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

    您需要结合使用 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,这可让您或注释处理器作者使用增量构建属性类型注释来注释处理器的参数。使用这些注释可提高增量和缓存整洁编译的正确性和性能。如需了解详情,请阅读向注释处理器传递参数部分。

  • 适用于 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 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:mipsmips64armeabi

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

    splits {
      abi {
          include 'armeabi', 'mips', 'mips64'
          ...
      }
    }
    
  • 在为 Android 免安装应用构建配置 APK 时,针对语言的配置拆分项现在默认按根语言分组。例如,如果您的应用包含用于 zh-TWzh-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 秒

其中某些更改会让现有 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,修复了各种错误并做出了多项性能改进。

优化

  • 通过精细控制的任务图提升了多模块项目的并行性。
  • 更改依赖项时,Gradle 通过不重新编译无法访问该依赖项 API 的模块来加快构建速度。您应利用 Gradle 的新依赖项配置implementationapicompileOnlyruntimeOnly)限制哪些依赖项会将其 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,这会停用设备上的编配,并且是运行测试的标准方法。
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。如需了解详情,请参阅为纯拆分项配置 build
  • 您现在可以更改外部原生构建项目的输出目录,如下所示:
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,您的 build 将会出现异常。例如,您无法再使用 Variants API 访问 outputFile() 对象,或使用 processManifest.manifestOutputFile() 获取各个变体的清单文件。如需了解详情,请参阅 API 变更部分。
  • 您无需再指定 Build Tools 的版本(因此,您现在可以移除 android.buildToolsVersion 属性了)。默认情况下,插件会针对所用 Android 插件的版本自动使用所需的最低版 Build Tools。
  • 现在,您可以在 buildTypes 代码块中启用/停用 PNG 处理(如下所示)。默认情况下,会为所有 build 启用 PNG 处理;但调试 build 除外,因为它会增加包含许多 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++ 代码一文。
  • 当您从命令行运行 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 文件中:
    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 复制到设备的文件系统,同时还有助于减小应用增量更新。
  • 您现在可以针对产品变种指定 versionNameSuffixapplicationIdSuffix。(问题 59614
变更:
  • getDefaultProguardFile 现在会返回 Android Plugin for Gradle 提供的默认 ProGuard 文件,并且不再使用 Android SDK 中的那些文件。
  • 改进了 Jack 编译器的性能和功能:
    • 在将 testCoverageEnabled 设置为 true 后,Jack 现在支持 Jacoco 测试覆盖率。
    • 改进了对注释处理器的支持。类路径上的注释处理器(例如任意 compile 依赖项)会自动应用于您的 build。您还可以在 build 中指定注释处理器,并通过在模块级 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 守护进程的最大堆大小设置为不小于 2048MB 的项目,该功能默认处于启用状态。如需进行设置,您可以将以下代码添加到项目的 gradle.properties 文件中:

    org.gradle.jvmargs = -Xmx2048m
    

    如果您已经在模块级 build.gradle 文件中为 javaMaxHeapSize 定义值,则需要将 org.gradle.jvmargs 的值设置为“javaMaxHeapSize + 1024MB”的结果。例如,如果您将 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 支持。这提高了调试构建变体的构建速度。由于实验性缩减器不支持优化和混淆处理功能,因此您应该为发布 build 启用 Proguard。如需为调试 build 启用实验性缩减器,请将以下代码添加到模块级 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 依赖项的问题。

旧版本