Android 项目Gradle文件讲解（Groovy和Kotlin）

前言正文一、Gradle的作用二、Gradle的种类① 工程build.gradle② 项目build.gradle③ settings.gradle④ gradle.properties⑤ gradle-wrapper.properties⑥ local.properties

三、Groovy和Kotlin的语言对比① 开启ViewBinding、DataBinding和buildConfig② 添加依赖库③ 添加lib库中的jar使用④ 配置Jitpack仓库⑤ 自定义打包信息

四、源码

前言

在Android应用开发中，Gradle是很重要的，它关系到你的项目能否正常编译运行，构建APK等等，而随着<code>Android Studio编辑器的更新，Gradle也发生了一些变化。

正文

Gradle 在 Android 开发中扮演了重要角色，它提供了灵活和可扩展的构建工具，使得 Android 项目的构建过程变得更加高效和便捷。

在很多版本中Android Studio中Gradle的主要语言都是Groovy，而在新版本的Android Studio，主要语言换成了Kotlin，虽然你仍然可以选择使用Groovy，但是我们是不是应该知道两者之间的编写方式和规则。出现了问题也要知道怎么解决。

一、Gradle的作用

Gradle 是一种基于 Groovy 的构建工具，被用于 Android 项目的构建、编译和打包。它提供了强大的构建自动化功能，使得在 Android 应用开发中管理依赖、设置环境和自定义构建流程变得更加方便和灵活。

在 Android 开发中，Gradle 被广泛用于构建项目、处理依赖、运行测试、生成 APK 等任务。下面是一些关于 Android 中的 Gradle 的重要说明：

构建脚本： Android 项目中的 build.gradle 文件是 Gradle 的核心配置文件。它定义了项目的构建设置、依赖关系和任务。通常，一个 Android 项目包含根目录下的 build.gradle 文件和每个模块（如 app 模块）下的 build.gradle 文件。

插件： Android Gradle 插件是为了与 Android 构建系统集成而设计的 Gradle 插件。在项目的 build.gradle 文件中，通过引入 com.android.application 或 com.android.library 插件，可以使 Gradle 成为适用于 Android 应用或库的构建工具。

任务： Gradle 使用任务（Task）来定义构建过程中需要执行的操作。常见的任务包括编译代码、打包应用、运行测试、生成 APK 等。Gradle 支持自定义任务，可以根据需要扩展构建过程。

依赖管理： Gradle 管理 Android 项目的依赖关系。通过 dependencies 块，可以指定项目所需的外部库和模块。Gradle 可以自动从远程 Maven 仓库或本地文件系统下载依赖项，并将其包含到项目的构建路径中。

变体： Android Gradle 插件引入了变体（Variant）的概念，用于管理不同构建类型（如 Debug 和 Release）和不同产品风味（如不同的应用标识符或资源配置）的构建变体。通过变体，可以针对不同的构建配置生成不同的 APK。

构建类型和产品风味： Android Gradle 插件允许定义多个构建类型和产品风味，以满足不同的需求。构建类型可以是 Debug、Release 或自定义的构建类型，而产品风味可以设置不同的应用标识符、资源和其他配置。

二、Gradle的种类

Gradle在Android项目中有两个比较重要的文件，那就是工程下的build.gradle和模块下的build.gradle，如下图所示：

当我们将项目结构切换为Android模式时，打开<code>Gradle Scripts，就可以看到排在最前面的是工程的build.gradle，然后是模块的build.gradle，只要看文件括号后面的内容就知道这个build.gradle作用的范围是什么，虽然两者都是build.gradle，但因为作用范围不同，实际的功能就不同。

① 工程build.gradle

在 Android 工程中，项目的根目录下有一个名为 build.gradle 的文件，通常称为 “工程级 build.gradle”，用于配置整个项目的构建设置。下面是一个简单的 Android 工程级 build.gradle 文件的示例：

// Top-level build file where you can add configuration options common to all sub-projects/modules.

plugins {

id 'com.android.application' version '8.1.3' apply false

id 'org.jetbrains.kotlin.android' version '1.9.0' apply false

}

上述示例中的 plugins 块配置了插件，并指定插件的版本，这是新版本的工程build.gradle，它将一些功能放到settings.gradle中，下面我们会说到。

② 项目build.gradle

在 Android 项目中，每个模块（如 app 模块、library 模块等）都有一个对应的模块级 build.gradle 文件，用于配置该模块的构建设置和依赖项。下面是一个简单的 Android 模块级 build.gradle 文件的示例：

plugins {

id 'com.android.application'

id 'org.jetbrains.kotlin.android'

}

android {

namespace 'com.example.hellokotlin'

compileSdk 33 // 指定编译使用的 Android SDK 版本

defaultConfig {

applicationId "com.example.hellokotlin" // 应用的唯一标识符

minSdk 24 // 最低支持的 Android 版本

targetSdk 33 // 目标 Android 版本

versionCode 1 // 版本号

versionName "1.0" // 版本名称

testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"

}

buildTypes {

release {

minifyEnabled false // 是否开启代码混淆

proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' // 混淆规则文件

}

}

compileOptions { //编译选项

sourceCompatibility JavaVersion.VERSION_1_8

targetCompatibility JavaVersion.VERSION_1_8

}

kotlinOptions { //Kotlin编译基于Jvm的版本

jvmTarget = '1.8'

}

// 其他配置项，如构建变体、签名配置等

}

dependencies { // 依赖项

implementation 'androidx.core:core-ktx:1.9.0'

implementation 'androidx.appcompat:appcompat:1.6.1'

implementation 'com.google.android.material:material:1.8.0'

implementation 'androidx.constraintlayout:constraintlayout:2.1.4'

testImplementation 'junit:junit:4.13.2'

androidTestImplementation 'androidx.test.ext:junit:1.1.5'

androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'

}

plugins 声明了所应用的插件，例如 'com.android.application' 表示应用 Android 应用插件，org.jetbrains.kotlin.android表示Kotlin语言插件，如果你使用Java语言开发，则不需要这个插件。android 块用于配置 Android 构建设置，其中包括编译和构建的相关配置。例如，compileSdkVersion 指定了编译使用的 Android SDK 版本，defaultConfig 定义了默认的配置项，如应用标识符、最低支持版本、目标版本等。buildTypes 块用于定义不同构建类型（如 release、debug）的配置。通过这个块，可以控制是否开启代码混淆、添加混淆规则等。dependencies 声明了该模块的依赖项。使用 implementation 关键字可以引入所需的库和模块。例如，androidx.appcompat:appcompat:1.6.1' 引入了 AndroidX AppCompat 库。可以在文件的其他部分定义自定义任务和其他配置块。这些可以根据项目需求进行个性化配置，例如添加构建任务、自定义变体等。

需要注意的是，每个模块都有自己的 build.gradle 文件，但具体的配置选项和依赖项可能因模块类型和项目需求而有所不同。建议参考具体模块的 build.gradle 文件和官方文档来了解和调整配置。

③ settings.gradle

settings.gradle 是 Android 项目的根目录下的一个重要文件，它用于配置项目的模块和构建设置。

这里需要说明一下，实际上关于settings.gradle项目在旧版本的Android Studio上没有这么多内容，只是对工程下面的模块进行管理，我们看看之前的settings.gradle中有什么内容，如下所示：

rootProject.name = "HelloKotlin"

include ':app'

之前的内容比较简单，当你需要改动项目名称或者增加项目中的模块时这个文件才会发生变化。大概是在大黄蜂版本开始发生了变化，将原本属于工程级build.gradle中的一些功能挪到了settings.gradle中，新版本代码如下所示：

下面是一个常见的 Android settings.gradle 文件的示例及其说明：

pluginManagement {

repositories {

google()

mavenCentral()

gradlePluginPortal()

}

}

dependencyResolutionManagement {

repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

repositories {

google()

mavenCentral()

}

}

rootProject.name = "HelloKotlin"

include ':app'

我们着重说明一下增加的部分， settings.gradle 文件中的 pluginManagement 和 dependencyResolutionManagement 配置块中的内容。这些配置块用于配置 Gradle 插件的仓库和依赖项的解析方式。

在 pluginManagement 配置块中：

repositories 声明了用于解析 Gradle 插件的仓库。示例中的配置包括 google()、mavenCentral() 和 gradlePluginPortal()。通过这些仓库，Gradle 将查找并下载所需的插件。

在 dependencyResolutionManagement 配置块中：

repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) 设置了仓库模式为 RepositoriesMode.FAIL_ON_PROJECT_REPOS。这表示如果项目中存在本地的仓库，则构建过程将失败。该配置用于强制 Gradle 仅使用远程仓库解析依赖项，而不依赖本地仓库。

repositories 声明了用于解析项目依赖项的仓库。示例中的配置包括 google() 和 mavenCentral()。通过这些仓库，Gradle 将查找并下载项目所需的依赖项。

这些配置块的作用是为 Gradle 构建过程提供正确的插件和依赖项解析环境。配置中的仓库声明可以根据项目的需求进行调整，以确保构建正常进行。

④ gradle.properties

gradle.properties 文件是一个位于根目录下的重要配置文件，用于设置 Gradle 构建系统的全局属性。它可以包含一些常用的配置属性和自定义属性，以影响项目的构建过程。其中让人印象最深刻的莫过于Google将库统一迁移到AndroidX下，当时就需要改一个属性android.useAndroidX=true，现在这已经是一个常驻属性了，之前的V4、V7的库你只会在一些老项目上看到，属于时代的眼泪了，下面我们看看这个gradle.properties中的内容

# 指定用于守护进程的 JVM 参数。

org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8

# 使用AndroidX

android.useAndroidX=true

# Kotlin 代码样式：“official 官方”或“obsolete 过时”：

kotlin.code.style=official

# 启用每个库的 R 类的命名空间，以便其 R 类仅包含库本身中声明的资源，而不包含库依赖项中的资源，从而减小该库的 R 类的大小

android.nonTransitiveRClass=true

实际上就4行代码，我将一些内容翻译了一下，可能不是那么准确，但是差不太多，平时这里改动比较少。

⑤ gradle-wrapper.properties

在 Android 项目中，gradle-wrapper.properties 文件位于根目录下的 gradle/wrapper 文件夹中，它用于配置 Gradle Wrapper。Gradle Wrapper 是一个与项目一起分发的 Gradle 版本管理工具，它可以确保每个构建都使用指定版本的 Gradle，而无需手动安装或配置 Gradle。

gradle-wrapper.properties 文件包含了一些重要的配置属性，用于指定 Gradle Wrapper 的行为和使用的 Gradle 版本。下面看一个示例：

#Fri Dec 15 15:44:43 CST 2023

distributionBase=GRADLE_USER_HOME

distributionPath=wrapper/dists

distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip

zipStoreBase=GRADLE_USER_HOME

zipStorePath=wrapper/dists

上述示例中的 gradle-wrapper.properties 文件包含了以下重要配置和说明：

distributionBase 和 distributionPath 配置了 Gradle Wrapper 下载和缓存 Gradle 发行版本的基本路径。默认情况下，它们指向 GRADLE_USER_HOME，即用户的 Gradle 目录。

zipStoreBase 和 zipStorePath 配置了压缩文件的基本路径，Gradle Wrapper 会将下载的 Gradle 发布文件存储在这里。默认情况下，它们也指向 GRADLE_USER_HOME。

distributionUrl 指定了要使用的 Gradle 发布版本的 URL。通过指定这个 URL，Gradle Wrapper 会自动下载并使用该版本构建项目。

gradle-wrapper.properties 文件的作用是为项目提供一个指定版本的 Gradle。当你使用 Gradle Wrapper 执行构建时，它会根据该文件中的配置自动下载所需版本的 Gradle。这有助于项目的一致性和可移植性，因为每个开发者都可以使用相同的 Gradle 版本构建项目，无需手动配置。

需要注意的是，如果需要更改 Gradle 版本或其他配置属性，可以在 gradle-wrapper.properties 文件中进行相应的修改。比如我可能Gradle需要升级8.1，那么你在改动之后点击Sync Now进行下载配置，具体的配置方式和详细说明可以参考官方文档。

⑥ local.properties

local.properties 文件是一个位于根目录下的本地配置文件，它用于指定本地开发环境中的一些路径和属性。该文件通常用于定义 SDK 和其他构建工具的位置，以便 Gradle 可以正确定位并使用它们。

以下是一个示例 local.properties 文件的内容及其说明：

sdk.dir=D\:\\Android\\Sdk

ndk.dir=D\:\\Android\\Sdk\\ndk\\26.1.10909125

上述示例中的 local.properties 文件包含了以下重要配置和说明：

sdk.dir 配置了 Android SDK 的位置。这个配置属性指定了 Android SDK 的根目录路径，Gradle 将使用该路径来查找构建所需的 Android 库和工具。

ndk.dir 配置了 Android NDK 的位置。这个配置属性指定了 Android NDK 的根目录路径，Gradle 将使用该路径来支持使用 C/C++ 编写的本地代码。

通过在 local.properties 文件中设置这些属性，Android 开发工具链（如 Android Studio 和 Gradle）可以找到和使用正确的 SDK、NDK 版本，并确保项目的构建过程能够正常进行。

请注意，local.properties 文件通常是在 Android 项目的每个开发者的本地环境中设置。这意味着每个开发者可以根据自己的系统配置和需求来设置这些属性，而不会影响到其他开发者。默认情况下你是不需要配置ndk的路径的，需要根据你的实际开发环境和需求来设置 local.properties 文件中的属性。确保路径和属性值与你的系统配置和目录结构一致。

三、Groovy和Kotlin的语言对比

在一开始build.gradle中是使用Groovy作为构建语言的，而在后面Google主推Kotlin为主要编程语言之后，就开始推荐使用Kotlin去构建build.gradle。对于开发者来说你目前熟悉什么就使用什么，下面我们来看一下一个Android工程中，使用Groovy和Kotlin去构建Gradle文件的区别。

要进行对比，首先我们创建两个项目，编写语言都使用Kotlin，Gradle的语言一个使用传统的Groovy，一个使用新的Kotlin。

首先说明一下我使用的Android Studio的版本：

算是比较新的版本了，下面我们来创建项目，首先创建使用Groovy作为Gradle编辑语言的项目。

然后我们再创建使用Kotlin作为Gradle编辑语言的项目。

OK，等两个项目都创建好之后，建议你先依次运行一次，看看刚创建的项目是否异常，这可以帮助你规避一些问题。同时为什么几张图就能解决的问题，我要创建两个项目来说明呢？是不是为了水篇幅，你要是这么想格局就小了，创建项目有什么好处的，那就是你可以拿到我这里的源码，两个项目的源码都可以进行对比，对比之后你就能知道当前项目有什么问题，同时如果说后续有什么新的需求要添加的话就可以很方便的更新代码和更新文章，我就不用再去重新创建项目了。说了这么多废话，下面我们进入对比环节。

要对比两个语言在Gradle文件中的不同使用方式最好的方法就是通过一些实际中的使用功能来进行，后面的内容也是基于这一点。

① 开启ViewBinding、DataBinding和buildConfig

对于两个功能，相应使用过的开发者应该不陌生，对于ViewBinding来说，极力推荐，如果你还在使用findViewById这种方式的话，建议你替换，而DataBinding相较来说有一定的使用门槛，用不好会出一堆问题，建议研究过再去使用。而buildConfig开启之后则会在编译时生成一个BuildConfig的类，在之前的Android Studio中，这个是默认生成的，而新版中需要手动配置才能生成，里面主要的功能就是可以让你知道当前运行的是正式环境还是开发环境，对于一些日志的控制还是有帮助的。

Groovy

<code> // 添加配置 开启ViewBinding

buildFeatures {

viewBinding true

// dataBinding true

// buildConfig true

}

Kotlin

// 添加配置 开启ViewBinding

buildFeatures {

viewBinding = true

// dataBinding = true

// buildConfig = true

}

下图为具体添加的位置，左为Groovy，右为Kotlin （后面的图也是这个方式，就不赘述说明）

同时要注意的是在app模块下的build.gradle。

② 添加依赖库

在Android开发中我们会使用很多依赖库，由第三方也有Google提供的，下面我们添加一个比较常用的Gson库。

Groovy

<code>// Gson库

implementation 'com.google.code.gson:gson:2.11.0'

Kotlin

// Gson库

implementation("com.google.code.gson:gson:2.11.0")

我们可以看到区别，在于Groovy可以使用单引号或者双引号，但是Kotlin只能使用双引号，同时左右需要加上括号，注意是在dependencies{}下进行配置，如下图所示：

注意，当gradle文件改动之后你都需要点击<code>Sync Now进行同步配置，否则配置不生效，这也是很多人问过我的问题。

③ 添加lib库中的jar使用

例如我们这里下载Gson的jar包，然后将这个包复制到app下的libs包，如果没有这个包就创建它，两个项目都完成这一步操作。

在老版本的Android Studio中默认有这个libs，还有默认将libs中的文件配置的代码，在版本迭代中首先是去掉了配置的代码，再来就是去掉了这个libs文件。那么现在我们创建了这个libs文件夹，下一步就是增加配置的代码了。

Groovy

<code>// 使用libs中的jar包

implementation fileTree(include: ['*.jar'], dir: 'libs')

Kotlin

// 使用libs中的jar包

implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar"))))

可以看到，在kotlin中使用是就是作为map进行配置的，如果你想使用libs中的aar包，那么就将，*.jar改成*.aar，配置如下图所示：

这里我将之前的依赖库代码注释掉了，因为都是使用的gson的库，如果你同时使用的话，可能会存在依赖冲突的问题，尽量避免这么做。当你使用成功时，你的jar文件就是可以展开的，如下图所示：

而aar文件则不会有变化，需要通过使用里面的API来判断是否正常导入。

④ 配置Jitpack仓库

使用依赖库的时候的，依赖库是存在于某一个远程仓库中的，目前新版本的Android Studio，自带了<code>google()、mavenCentral()这两个仓库，如果你使用的是官方的依赖库，那么基本上做什么配置，直接使用就行了，而如果是一些第三方库，例如早期的BaseRecyclerViewAdapterHelper库，当时就在Jitpack库下面，不过新版本已经迁移到了MavenCentral()库下面，具体的你可以去Github上查看这个库的更新记录就知道了。

Groovy

// 添加 jitpack库

maven { url 'https://jitpack.io' }

Kotlin

// 添加 jitpack

maven("https://jitpack.io")

注意这里是在settings.gradle中了，如下图所示：

⑤ 自定义打包信息

通过项目编译成apk文件，我们可以修改apk的文件名称，如下所示：

Groovy

<code>// 自定义打包

android.applicationVariants.all { variant ->

variant.outputs.all {

outputFileName = "GradleGroovy${ variant.versionName}.apk"

}

}

Kotlin

// 自定义打包

android.applicationVariants.all {

outputs.all {

if (this is com.android.build.gradle.internal.api.ApkVariantOutputImpl) {

this.outputFileName = "GradleKotlin${ versionName}.apk"

}

}

}

注意是在app模块下的build.gradle

如果你生成Apk之后没有看到app下有一个debug或release的文件夹，那么你可以刷新以下项目，前提是你生成APK提示成功了。

四、源码

GradleGroovy

GradleKotlin