0. 前言
自从将 Android 开发工具从 eclipse 迁移到 AndroidStudio 中之后，Android 工程构建越来越方便。见过很多项目中各式各样的 Gradle 配置语法，懵懵懂懂。遂花费近两周时间将官方文档通读一遍并整理出常用 Gradle 配置 Demo，以此博客作为说明。
1. 准备工作
一个最新版本的 AndroidStudio 毋庸置疑。下载地址：请戳。此处使用 3.5 版本。
Gradle 版本 5.4.1 ，无须单独下载，在工程中配置好即可。
2. 基本概念
2.1. Module
软件工程中，通常采用模块化开发的策略，将一个项目划分成若干部分，多人协作开发中，每人完成一部分，最终完成整个项目。因此 AndroidStudio 也采用模块化管理的方式编译 Android 工程 。各个模块之间的依赖关系类似于树形结构，主 Module 作为根节点，其余多个库 Module 都直接或简介的被主 Module 引用。
2.2. Project
基于前面的描述，Project 即 AndroidStudio 打开的一个目录，其中包含 N+1 个 Module ，通过 Gradle 构建多个 Module 并最终合并成一个 apk 文件。
其实，在一个 Project 目录中，可以有多个主 Module ，每个主 Module 可以依赖相同的库 Module 并负责生成一个 apk 文件。通常不建议这么使用，因为这样会破坏 Module 之间的树形依赖关系，不利于后期维护。推荐将复用频率较高的库 Module 封装成 aar 文件，通过直接依赖或远程依赖的方式用于不同的主 Module 之中。
2.3. buildType & productFlavor
通过直译的方式 ，可以理解成 构建类型 和 产品特性 。构建类型中，默认包含 debug 和 release 两种类型。一些基本的差异如 ：debug 包允许调试，release 包不允许调试。产品特性可以根据实际需要自行定义，如：收费和免费版本，汉语、英语及日语。不同的特性之间通过维度的概念区分。
最终如上图所示，生成 2x3x2 共 12 种不同的 apk 文件。
3. 工程结构
精简后的 AndroidStudio 工程结构如下：
├── app
│ ├── build.gradle
│ ├── proguard-project.txt
│ └── src
│ └── main
│ ├── AndroidManifest.xml
│ ├── java
│ │ └── com
│ │ └── flueky
│ │ └── demo
│ │ └── MainActivity.java
│ └── res
│ ├── layout
│ │ └── activity_main.xml
│ └── values
│ ├── strings.xml
│ └── styles.xml
├── build.gradle
├── gradle
│ └── wrapper
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
└── settings.gradle
- 文件夹 app 作为一个 Module ，必须有 build.gradle 文件，src 文件夹包含全部源文件：Java 文件、资源文件、清单文件等。
- 文件 build.gradle 不同于 app/build.gradle , 它用于整个工程的配置，而 app/build.gradle 只作用于 app Module 的配置。
- gradle 包含使用的 gradle 插件版本 。若未指定 ，AndroidStudio 会自动生成最新的 gradle 插件目录。
- gradlew、gradlew.bat 分别是 Mac/Linux 和 Windows 的脚本文件。关联于 gradle 插件版本，不可单独删除。
- settings.gradle 包含整个工程的所有 Module 的声明。
settings.gradle 示例：
// 主Module
include ':app'
// 库Module
include ':library'
// 添加外部库
include 'other-lib'
project(':other-lib').projectDir = new File(rootDir, "../other-sample/library")
4. 配置 Project
4.1. 构建脚本
buildscript {
repositories {
// 仓库地址
google()
jcenter()
mavenCentral()
}
// 工程的依赖配置
dependencies {
// 必须包含的 gradle 版本的构建工具。
classpath 'com.android.tools.build:gradle:3.4.1'
}
}
4.2. 全工程配置
// 全部工程配置，作用于每个 Module
allprojects {
repositories {
// 仓库地址
google()
jcenter()
mavenCentral()
// 依赖仓库，添加用于查找依赖项的目录，可以多个。
flatDir {
// jar、aar 存放的目录
dirs 'libs'
}
}
}
4.3. 扩展变量
// 扩展变量，用于统一管理每个 Module 的有关配置
ext {
// 应用 id
applicationId = "com.flueky.demo"
// 统一控制各个 Module 使用的 SDK 版本
compileSdkVersion = 29
buildToolsVersion = "29.0.0"
minSdkVersion = 19
targetSdkVersion = 29
// 定义 Module 的版本号
app = [
versionCode: 1,
versionName: '1.0.0'
]
}
4.4. 加载配置文件
// 加载其他的 gradle 配置文件，可选
apply from: "config.gradle"
5. 配置 Module
5.1. 加载插件
// 声明 Module 是主 Module，生成 apk 文件
apply plugin: 'com.android.application'
// 声明 Module 是库 Module，生成 aar 文件
apply plugin: 'com.android.library'
// 声明 Module 是 Java 库，生成 jar 文件
apply plugin: 'java-library'
还有很多 Plugin 可以用，如： java web maven-publish 等。
另一种写法，一个 Module 中使用多个插件，如：
plugins {
id 'java'
id 'war'
id 'maven-publish'
}
5.2. 使用SDK
android {
// 定义编译的 sdk 版本，只有使用最新版本的sdk，才能在代码中只用最新的 api 方法
compileSdkVersion rootProject.ext.compileSdkVersion
// 定义构建工具的版本
buildToolsVersion rootProject.ext.buildToolsVersion
}
rootProject.ext 是在 Project 的 build.gradle 文件中声明。
5.3. 默认配置
android{
defaultConfig {
// 应用 id
applicationId rootProject.ext.applicationId
// 最小 sdk 版本，低于此 Android 版本的手机不能安装
minSdkVersion rootProject.ext.minSdkVersion
// 目标 sdk 版本，低于此 Android 版本的手机完美兼容，高于此 Android 版本的手机，部分特性不能使用
// 升级 target 需要针对高版本做兼容。
targetSdkVersion rootProject.ext.targetSdkVersion
// 应用版本号，覆盖安装时，升级版本依据
versionCode rootProject.ext.app.versionCode
// 版本名称，
versionName rootProject.ext.app.versionName
// 指定需要编译 abi 版本的 so
ndk{
abiFilters 'armeabi-v7a'
}
// 设置编译的资源
resConfigs "zh-rCN"
// 多 dex 支持 ，minSdkVersion >= 20 使用
multiDexEnabled true
}
}
5.4. 签名配置
签名文件，至少配置一个。如未使用，debug 包，会使用 user home/.android/debug.keystore 的签名文件。 release 包默认不签名。
// 可以将签名文件信息配置在 keystore.properties 文件中
def ksPropFile = rootProject.file("keystore.properties")
def ksProp = new Properties()
// 加载签名配置文件
ksProp.load(new FileInputStream(ksPropFile))
android{
signingConfigs {
// 生产签名，读取配置文件
release {
keyAlias ksProp['keyAlias']
keyPassword ksProp['keyPassword']
storeFile file(ksProp['storeFile'])
storePassword ksProp['storePassword']
}
// 测试签名，静态配置
debug {
keyAlias 'flueky'
keyPassword 'android'
storeFile file('../demo.keystore')
storePassword 'android'
}
}
}
使用配置的好处是，将生产签名文件信息保存在配置文件中，不添加到版本控制工具中，可以有效防范签名文件信息泄露，被他人使用。
针对签名文件的校验，会有专门的防篡改技术，防止应用被反编译 apk 后二次打包。如签名文件泄露，会构成很大威胁。
5.5. 构建类型
android{
buildTypes {
// 测试版本
debug {
// 允许 Java 代码调试（默认允许）
debuggable true
// 允许 JNI 代码调试（默认允许）
jniDebuggable true
// 签名 信息
signingConfig signingConfigs.debug
// 版本名称后缀
versionNameSuffix = '-beta'
// 应用 Id 后缀
applicationIdSuffix '.debug'
}
// 发行版本
release {
// 禁止 Java 代码调试（默认禁止）
debuggable false
// 禁止 JNI 代码调试 （默认禁止）
jniDebuggable false
signingConfig signingConfigs.release
// build/intermediates/proguard-files 目录下存在三个混淆配置文件
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-project.txt'
// 允许代码压缩、混淆、优化,默认情况下会使用 R8 压缩
minifyEnabled true
// 允许资源压缩，包括清理无用资源。在生成 apk 时，如需保留被删除的图片使用，keep.xml 声明 。
shrinkResources true
// 配置需要放在主 dex 中的类
// multiDexKeepFile file('multidex-config.txt')
// 或者使用下面的配置，语法同 proguard file
// multiDexKeepProguard file('multidex-config.pro')
}
// 内部使用版本
inner {
// 使用 debug 的配置
initWith debug
applicationIdSuffix '.inner'
}
}
}
AndroidStudio 默认支持 debug 和 release 两种类型。并有一些默认的配置。常用配置见上。
5.6. 产品特性
android{
// 定义两种纬度
flavorDimensions 'stage', 'api'
productFlavors {
// 开发阶段
dev {
dimension 'stage'
}
// 生产阶段
pro {
dimension 'stage'
}
minApi21 {
dimension 'api'
minSdkVersion 21
}
minApi23 {
dimension 'api'
minSdkVersion 23
}
minApi26 {
dimension 'api'
minSdkVersion 26
}
}
}
产品特性和构建类型，不仅仅是在构建的时候修改些配置，还可以在 src 目录下，定义同名的文件夹，存放 java 、res 、assets 和 AndroidManifest.xml 等。用于实现不同的业务逻辑，资源图片等。
5.7. 过滤变体
产品特性和构建类型可以通过组合的方式生成多个 apk 文件。但在实际中可能不需要部分组合方式。忽略后，可加速编译过程。
如，内部使用不需要生产阶段的 apk 文件，配置如下：
android{
// 设置不需要生成 apk 的类型和特性
variantFilter { variant ->
// 将多个 flavor 组合转成字符串数组
def names = variant.flavors*.name
// 获取到 buildType 名称
def type = variant.buildType.name
// 忽略部分不需要生成的 apk
if (names.contains('pro') && type.equals("inner")) {
setIgnore(true)
}
}
}
5.8. 细分APK
android{
splits {
// 注意和 nkd.abiFilters 的冲突
abi {
enable true
// 包含所有版本so 的apk 文件。此配置仅用于 abi 。
// density 中默认会生成包含所有资源的 apk
universalApk true
// 去除 x86 和 x86_64
exclude 'x86', 'x86_64'
}
// 注意和 resConfigs 的冲突
density {
enable true
reset()
include "xhdpi"
// compatibleScreens 'small', 'normal', 'large', 'xlarge'
}
}
}
universalApk 只用在 abi 的配置中。true 表示按照默认的方式将全部 so 打包 。density 中，此值必须为 true。 使用 abi 和 density 要注意同 ndk.abiFilters 和 resConfigs 使用的冲突。
5.9. 添加依赖
依赖第三方库，在新版本 Gradle 中，常用的有 implementation 和 api 。
它们区别是：
- A 中 implementation B , B 中 implementation C 。 B 可以使用 C 的类和方法，A 可以使用 B 的类和方法。
- A 中 implementation B , B 中 api C 。 B 可以使用 C 的类和方法，A 可以使用 B 的类和方法。A 还可以使用 C 的类和方法。
这样的好处是，如果只修改了 Module C , 情况 1 只会重新编译 B 和 C ，情况 2 会重新编译 A B C 。 因此在实际应用中，避免大量使用 api 的方式。
下面列举了对 jar 文件、 aar 文件和 maven 库文件的依赖方式。
dependencies {
// 依赖同级的 libs 目录，只包含jar
implementation fileTree(include: '*.jar', dir: 'libs')
// 依赖同级的 libs 目录，包含 jar 和 aar，还可以选择不包含指定文件
implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'], exclude: [])
// debug 类型的依赖
debugImplementation fileTree(include: '*.jar', dir: 'src/debug/libs')
// release 类型的依赖
releaseImplementation fileTree(include: '*.jar', dir: 'src/release/libs')
// 同理 devImplementation minApi21Implementation innerImplementation
// 如果 需要组合使用，如 devMinApi21DebugImplementation，见 configurations
// 依赖本地 module
implementation project(':library')
implementation project(':other-lib')
// 等同于带 path 参数
// implementation project(path: ':library')
// 依赖远程库，不建议在版本号中使用 + 通配符,括号可以省略
implementation 'com.android.support:appcompat-v7:28.0.0'
implementation('com.android.support:support-v4:28.0.0') {
// 一个远程库可能包含多个第三方库，可以排除指定库
exclude group: 'com.android.support', module: 'collections'
}
// 等同于复杂形势
// implementation group: 'com.android.support', name: 'support-v4', version: '28.0.0'
implementation 'com.google.dagger:dagger:2.24'
annotationProcessor 'com.google.dagger:dagger-compiler:2.24'
// 5.0 之前多 dex 支持，minSdkVersion < 20 必须使用。
implementation 'androidx.multidex:multidex:2.0.1'
}
注意到上面的配置中存在 debugImplementation 和 releaseImplementation 。这是对不同构建类型单独指定的依赖方式。
产品特性也可以使用上面的配置，但是需要先声明，方式如下：
configurations {
// 添加多个依赖项配置
devMinApi21DebugImplementation {}
devMinApi21Api {}
devDebugCompileOnly {}
minApi21DebugRuntimeOnly {}
}
篇幅有限 ，以上介绍均是常用配置。更多配置请见源码。
- 修改生成的 apk 文件目录。
- 修改生成的 apk 文件名称。
- 动态修改版本号。
- 替换 build 缓存目录。
- AndroidManifest.xml 注入变量。
关于 AndroidManifest.xml 合并冲突，有机会在后面的文章中讲。
6. 常见问题
6.1. 问题1
主 Module 有 inner 的构建类型，库 Module 中、没有 ，构建 app 时会报错。
可在库 Module 中添加 inner 的构建类型，或者在主 Module 的 inner 类型中，添加下面的配置。
// inner 匹配失败 ， debug 匹配成功， release 忽略
matchingFallbacks = ['inner', 'debug', 'release']
如需匹配 release 时，将 release 放在 debug 前，或者直接删除 debug 。
6.2. 问题2
主 Module 有的产品特性，库 Module 中没有，构建 app 时会报错。
错误原因同 问题 1 。如，库 Module 中存在其他类似的产品特性，可使用匹配的方式 ，如下：
android{
productFlavor{
minApi21 {
minSdkVersion 21
// 库 module 没有 minApi21 ，匹配较高版本
// 同时需要在 AndroidManifest.xml 中使用 overrideLibrary
matchingFallbacks = ['minApi23']
}
minApi26 {
minSdkVersion 26
// 库 module 没有 minApi26 ，匹配较低版本，可兼容
matchingFallbacks = ['minApi23']
}
}
}
如，库 Module 中没有定义任何产品特性，可以直接在 defauleConfig 中，忽略对维度的依赖 。
android{
defauleConfig{
// 库 module 没有开发进度的维度，因此忽略
missingDimensionStrategy 'dev', 'pro'
}
}
6.3. 问题3
主 Module 的 minSdk 小于 库 Module 的 minSdk。
使用 overrideLibrary ，指定复写库 Module 的 packageName 。
<manifest xmlns:tools="http://schemas.android.com/tools">
<!-- minSdkVersion 存在冲突的解决方案-->
<uses-sdk tools:overrideLibrary="com.flueky.library" />
</manifest>
源码地址。
觉得有用？那打赏一个呗。去打赏
