Android 构建系统会编译应用资源和源代码,然后将它们打包成 APK 或 Android App Bundle 文件,供您测试、部署、签名和分发。
创建自定义 build 配置需要您对一个或多个 build 配置文件做出更改。这些纯文本文件使用领域特定语言 (DSL) 通过 Kotlin 脚本(Kotlin 语言的一种变种)来描述和操控构建逻辑。您还可以使用 Groovy(一种适用于 Java 虚拟机 [JVM] 的动态语言)来配置 build。包括以下配置文件。
您无需了解 Kotlin 脚本或 Groovy 便可开始配置 build,因为 Android Gradle 插件引入了您需要的大多数 DSL 元素。Kotlin 脚本还依赖于底层 Gradle Kotlin DSL。开始新项目时,Android Studio 会自动为您创建其中一些文件,并根据合理的默认值进行填充。
1 Gradle 封装容器文件
Gradle 封装容器 (gradlew
) 是源代码中包含的一个小型应用,用于下载和启动 Gradle 本身。这样可以实现更一致的 build 执行。开发者下载应用源代码并运行gradlew
。这会下载所需的 Gradle 发行版,并启动 Gradle 来构建应用。
gradle/wrapper/gradle-wrapper.properties
文件包含一个distributionUrl
属性,该属性描述了运行 build 时使用哪个版本的 Gradle。
提示:如果同时处理多个项目,请尽可能确保所有项目都使用相同的 Gradle 版本。否则,Gradle 会为每个 Gradle 版本创建 Gradle 守护程序的副本,此外还会为用于运行 Gradle 的每个 JDK创建单独的副本。这会增加内存和 CPU 用量,可能会减慢 build 速度或影响机器上的其他工作。
2 Gradle 设置文件
settings.gradle(.kts)
文件位于项目的根目录下。此设置文件用于定义项目级代码库设置,并告知 Gradle 在构建应用时应将哪些模块包含在内。多模块项目需要指定应包含在最终 build 中的每个模块。
3 顶层 build 文件
顶层build.gradle(.kts)
文件位于项目的根目录下。它通常用于定义项目中模块使用的常见插件版本。
3.1 模块级 build 文件
模块级build.gradle(.kts)
位于每个project/module/
目录中。用于为其所在的特定模块配置 build 设置。您可以通过配置这些 build 设置提供自定义打包选项(如额外的 build 类型和产品变种),以及替换main/
应用清单或顶级 build 脚本中的设置。
3.2 Android SDK 设置
应用的模块级 build 文件包含一些设置,这些设置会指明在编译、选择平台行为以及指定运行应用的最低版本时使用的 Android SDK 版本。
图 1.build 中的 Android SDK
3.3 compileSdk
compileSdk
决定在编译源代码时可用的 Android API 和 Java API。如需使用最新的 Android 功能,请在编译时使用最新的 Android SDK。
某些 Android 平台 API 在旧版 API 级别中可能不可用。您可以有条件地控制使用新功能,也可以使用 AndroidX 兼容库在较低 Android API 级别下使用新功能。
每个 Android SDK 都提供了一部分 Java API,供您在应用中使用。 我可以在 Java 或 Kotlin 源代码中使用哪些 Java API 部分中的表格显示了根据 Android SDK 版本可用的 Java API 级别。 早期版本的 Android 系统通过脱糖支持较新的 Java API,您必须在 build 中启用脱糖。
如果您的compileSdk
与当前版本的 Android Studio、AGP 或项目的库依赖项要求冲突,Android Studio 会显示警告。
3.4 minSdk
minSdk
用于指定您希望应用支持的最低 Android 版本。设置minSdk
可限制哪些设备可以安装您的应用。
如需支持较低版本的 Android,您可能需要在代码中添加更多条件检查,或更多地使用 AndroidX 兼容性库。您应将支持较低版本的维护费用与仍在使用这些较低版本的用户百分比进行权衡。如需了解当前的版本使用百分比,请参阅 Android Studio 的新建项目向导中的版本图表。
在 Android Studio 中修改代码或在构建期间运行检查时,lint 会针对您使用的 API 但minSdk
中未提供的 API 发出警告。您应通过将较新功能设为基于条件的或使用 Appcompat 实现向后兼容性来解决这些问题。
3.5 targetSdk
targetSdk
有以下两种用途:
- 它用于设置应用的运行时行为。
- 它用于证明您已针对哪个 Android 版本进行了测试。
如果您的应用在使用高于targetSdk
的 Android 版本的设备上运行,Android 会在兼容模式下运行您的应用,该模式的行为与 targetSdk 中所指示的较低版本类似。例如,当 API 23 引入运行时权限模型时,并非所有应用都已准备好立即采用该模型。 通过将 targetSdk 设置为 22,这些应用可以在不使用运行时权限的情况下在 API 级别为 23 的设备上运行,并且可以使用最新 compileSdk 版本中包含的功能。Google Play 分发政策会强制执行针对目标 API 级别的其他政策。
targetSdk
的值必须小于或等于 compileSdk 的值。
注意:compileSdk 和 targetSdk 的值不必相同。请谨记以下基本原则:
- 通过 compileSdk,您可以使用新的 API
- targetSdk 用于设置应用的运行时行为
- targetSdk 必须小于或等于 compileSdk
4 Gradle 属性文件
Gradle 还包含两个属性文件,它们位于项目的根目录下,可用于指定 Gradle 构建工具包本身的设置:
4.1 gradle.properties
您可以在其中配置项目全局 Gradle 设置,如 Gradle 守护程序的最大堆大小。
4.2 local.properties
为构建系统配置本地环境属性,其中包括:
ndk.dir
- NDK 的路径。此属性已被废弃。NDK 的所有下载版本都会安装在 Android SDK 目录下的 ndk 目录中。sdk.dir
- Android SDK 的路径。cmake.dir
- CMake 的路径。ndk.symlinkdir
- 在 Android Studio 3.5 及更高版本中,创建指向 NDK 的符号链接,该符号链接的路径可比 NDK 安装路径短。
注意:local.properties 文件专用于 Android Gradle 插件专用的属性。在此文件中添加您自己的值可能会导致出现问题。如果您需要定义自己的本地属性,请创建一个单独的属性文件并手动加载该文件。
5 将项目与 Gradle 文件同步
当您在项目中对 build 配置文件进行更改时,Android Studio 会要求您同步项目文件,以便它导入 build 配置更改并执行一些检查以确保您的配置不会造成 build 错误。
如要同步项目文件,请点击做出更改后显示的通知栏中的Sync Now
,或者点击菜单栏中的 Sync Project 图标 。如果 Android Studio 发现您的配置存在任何错误(例如,您的源代码使用了只有在 compileSdkVersion 以上的 API 级别中才会提供的 API 功能),Messages 窗口会显示相应问题。
6 源代码集
Android Studio 按逻辑关系将每个模块的源代码和资源分组为源代码集。当您创建新模块时,Android Studio 会在该模块内创建一个 main/ 源代码集。模块的 main/ 源代码集包含其所有 build 变体使用的代码和资源。
其他源代码集目录是可选的,在您配置新的 build 变体时,Android Studio 不会自动为您创建这些目录。不过,创建类似于 main/ 的源代码集有助于组织 Gradle 仅在构建特定应用版本时才应使用的文件和资源:
src/main/
:此源代码集包含所有 build 变体共用的代码和资源。src/buildType/
:创建此源代码集可加入特定 build 类型专用的代码和资源。src/productFlavor/
:创建此源代码集可加入特定产品变种专用的代码和资源。
注意:如果配置 build 以组合多个产品变种,则可以为变种维度之间的每个产品变种组合创建源代码集目录:src/productFlavor1ProductFlavor2/
src/productFlavorBuildType/
:创建此源代码集可加入特定 build 变体专用的代码和资源。
例如,如需生成应用的“fullDebug”版本,构建系统需要合并来自以下源代码集的代码、设置和资源:
src/fullDebug/
(build 变体源代码集)src/debug/
(build 类型源代码集)src/full/
(产品变种源代码集)src/main/
(主源代码集)
注意:当您在 Android Studio 中使用 File > New 菜单选项新建文件或目录时,可以针对特定源代码集进行创建。可供您选择的源代码集取决于您的 build 配置,如果所需的目录尚不存在,Android Studio 会自动创建。
如果不同源代码集包含同一文件的不同版本,Gradle 将按以下优先顺序决定使用哪一个文件。左侧源代码集替换右侧源代码集的文件和设置:
build 变体 > build 类型 > 产品变种 > 主源代码集 > 库依赖项
这样一来,Gradle 便可使用专用于您试图构建的 build 变体的文件,同时重用与其他应用版本共用的 activity、应用逻辑和资源。
在合并多个清单时,Gradle 会使用相同的优先顺序,这样每个 build 变体都能在最终清单中定义不同的组件或权限。