一文了解 Gradle 配置文件

在使用 Gradle 中，我们会看到 gradle 存在很多的配置文件。如下图所示，有6种配置文件，分别是 gradle-wrapper、项目根目录下的 build.gradle、模块中的 build.gradle、setting.gradle 、local.properties、gradle.properties。为什么 Gradle 需要这么多配置文件呢？它们的作用是什么呢？这篇文章会一一介绍。

gradle-wrapper

gradle-wrapper 简单来说就是对 Gradle 的一层封装。为什么需要再封装一层呢？主要有三点原因：

1. 确保 版本一致性： 让团队成员都使用项目指定的相同版本进行构建，避免因版本差异导致的构建问题
2. 方便 项目迁移和共享：当项目需要迁移到其他环境或与他人共享时，不需要担心 Gradle 版本的问题，因为 Wrapper 会处理好版本的适配。
3. 版本更新管理：项目可以方便地更新 Gradle 版本，只需在 Wrapper 的配置中修改版本号，所有使用 Wrapper 的开发者在下次构建时都会自动获取并使用新的版本。

从上图可以看到，gradle-wrapper 相关的文件有四种，分别是：

• gradle-wrapper.jar：主要是Gradle的运行逻辑，包含下载Gradle；
• gradle-wrapper.properties：gradle-wrapper 的配置文件，核心是定义了Gradle版本；
• gradlew：gradle wrapper的简称，linux下的执行脚本
• gradlew.bat：windows下的执行脚本

由于这篇文章主要是讲配置文件的，这里就主要看看 gradle-wrapper.properties 的文件：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-all.zip

参数介绍如下

• distributionBase：下载的Gradle的压缩包解压后的主目录；
• zipStoreBase：同distributionBase，不过是存放zip压缩包的主目录；
• distributionPath：相对于distributionBase的解压后的Gradle的路径，为wrapper/dists；
• zipStorePath：同distributionPath，不过是存放zip压缩包的；
• distributionUrl：Gradle版本的下载地址，所有的版本可以看Gradle Distributions。这里有几种类型，分别为：doc：用户文档；bin：二进制文件；all：包含源码、用户文档、二进制文件等；

项目根目录下的 build.gradle

项目根目录下的 build.gradle的文件内容如下所示：

plugins {
    id 'com.android.application' version '8.2.2' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.0' apply false
}

plugins 声明的是用来构建应用的插件列表。其中 apply false 表示不将该 plugin 应用于当前项目，一般是在需要使用的模块的 build.gradle 文件中声明使用。

在7.0以前，Gradle 可以设置很多通用的配置；现在在 7.0 版本之后，这些配置移动到了 setting.gradle 文件。

setting.gradle

setting.gradle 文件内容如下所示：

pluginManagement { // 插件管理
    repositories { // 设置下载插件的仓库
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}
dependencyResolutionManagement { // 依赖管理
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories { // 设置下载依赖的仓库
        google()
        mavenCentral()
    }
}

rootProject.name = "TestAndroid" // 设置项目名称
include ':app' // 用于指定构建应用时应将哪些模块包含在内

顾名思义，setting.gradle 文件主要存储项目相关的设置信息。比如说可以在 setting.gradle 文件中设置了插件仓库位置、依赖仓库位置这些通用的配置；以及指定项目构建需要依赖哪些模块。

模块中的 build.gradle

plugins { // 当前模块应用的插件
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

android { // android 相关的配置信息，会被引入的 com.android.application 插件使用
    ...
}

dependencies { // 引入的依赖
    ...
}

如上代码所示，模块中的 build.gradle 文件中主要设置了构建需要的信息，这些信息最后会被应用的插件来使用。

local.properties 和 gradle.properties

local.properties 和 gradle.properties 文件都是存储配置信息。不同的是，local.properties 设置的是本地的特殊配置，比如sdk的位置；而gradle.properties 设置的是项目相关的配置。

// local.properties 文件
sdk.dir=C\:\\Users\\28967\\AppData\\Local\\Android\\Sdk

// gradle.properties 文件
org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8  
android.useAndroidX=true  
kotlin.code.style=official  
android.nonTransitiveRClass=true

在使用上， local.properties 设置的属性不能直接使用，只能通过文件读取。而 gradle.properties中自定义属性，可以在gradle中可以直接使用。但是对于 xxx.xxx 格式的属性，需要读取文件获取它的属性值，不能直接使用。 local.properties 示例如下：

// local.properties 通过文件读取配置
Properties properties = new Properties()
properties.load(project.rootProject.file('local.properties').newDataInputStream())
def sdkDir = properties.getProperty('sdk.dir')
println("sdkDir = $sdkDir")

gradle.properties 读取配置示例如下：

//在build.gradle脚本中使用
//直接使用属性值
println("test = $test")

//读取gradle.properties 文件
Properties properties = new Properties()
properties.load(project.rootProject.file('gradle.properties').newDataInputStream())
def androidx = properties.getProperty('android.useAndroidX')
println("androidx = $androidx")