更新 Gradle

更新 Gradle

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

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

插件版本	所需的 Gradle 版本
1.0.0 - 1.1.3	2.2.1 - 2.3
1.2.0 - 1.3.1	2.2.1 - 2.9
1.5.0	2.2.1 - 2.13
2.0.0 - 2.1.2	2.10 - 2.13
2.1.3 - 2.2.3	2.14.1+
2.3.0+	3.3+
3.0.0+	4.1+
3.1.0+	4.4+
3.2.0 - 3.2.1	4.6+
3.3.0 - 3.3.3	4.10.1+
3.4.0 - 3.4.3	5.1.1+
3.5.0 - 3.5.4	5.4.1+
3.6.0 - 3.6.4	5.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 插件包含以下新功能。

新功能

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

Kotlin 脚本 DSL 支持

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

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

重要提示：如果您已采用 KTS 构建脚本或在 buildSrc 中使用 Kotlin，这样可能会因某些错误而导致源代码兼容性被破坏，这些错误在以前的版本中原本表现为运行时错误。

在 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 中的 mylibrary 和 myotherlibrary 库会打包到您的 build 生成的 AAR 中，并且各自会将头文件从指定的目录导出到依赖于它们的项。

注意：对于 Android Gradle 插件 4.0 及更高版本的用户，导入预构建原生库的配置设置已发生更改。如需了解详情，请参阅 4.0 版本说明。

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_NAME 和 BuildConfig.VERSION_CODE 属性已从生成的 BuildConfig 类中移除，因为这些静态值过去并不反映应用版本代码和名称的最终值，因此具有误导性。此外，这些值过去在清单合并期间会被舍弃。

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

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

设置 NDK 路径

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

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 插件需要使用以下工具：

• Gradle 6.1.1。如需了解详情，请阅读有关更新 Gradle 的部分。

• SDK Build Tools 29.0.2 或更高版本。

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 中的软件包可见性。