Gradle 配置文件详解：build.gradle vs. settings.gradle vs. gradle.properties

1. 概述

在本文中，我们将深入探讨 Gradle Java 项目的几种核心配置文件 的作用与区别，并简要分析 Gradle 构建过程的执行流程。

如果你对 Gradle 还不熟悉，可以先参考这篇基础介绍。

2. `build.gradle`

我们通过运行 gradle init --type java-application 命令初始化一个 Java 项目，得到如下目录结构：

build.gradle
gradle    
    wrapper
        gradle-wrapper.jar
        gradle-wrapper.properties
gradlew
gradlew.bat
settings.gradle
src
    main
        java  
            App.java
    test      
        java
            AppTest.java

其中，✅ build.gradle 是整个项目的核心配置文件。它本质上是一个 Groovy 脚本（或 Kotlin 脚本），使用的是基于 Groovy 的 DSL（领域特定语言）来描述构建逻辑。

示例内容如下：

plugins {
    id 'java'
    id 'application'
}

mainClassName = 'App'

dependencies {
    compile 'com.google.guava:guava:23.0'

    testCompile 'junit:junit:4.12'
}

repositories {
    jcenter()
}

在这个文件中我们可以：

定义插件（如 java、application）
设置依赖项（dependencies）
配置仓库（repositories）

⚠️ 注意：从 Gradle 7.x 开始，compile 已被弃用，请改用 implementation 或 api。

任务（Tasks）

Gradle 的核心概念是项目（Project）和任务（Task）。应用 java 插件后，会自动生成一系列标准任务，例如：

assemble
check
build
jar
javadoc
clean

这些任务之间已经建立了合理的依赖关系图谱，通常我们只需要执行 gradle build，Gradle 就会自动完成编译、测试、打包等步骤。

如果需要添加自定义任务，比如构建 Docker 镜像，也可以写在 build.gradle 中：

task hello {
    doLast {
        println 'Hello Baeldung!'
    }
}

然后运行：

$ gradle -q hello
Hello Baeldung!

✅ 简单粗暴，但有效。

对于多模块项目，每个子项目都会有一个自己的 build.gradle 文件。

执行上下文

build.gradle 是在一个 Project 实例上执行的，每一个子项目对应一个 Project 实例。

任务（Task）作为 Project 的一部分存在，是一个包含多个 Action 的有序列表。我们通过调用 doLast {} 将闭包添加到任务的最后阶段，Gradle 在执行时会依次调用每个 Action 的 execute() 方法。

3. `settings.gradle`

✅ settings.gradle 是 Gradle 构建的入口配置文件，用于定义哪些项目参与构建。

生成的内容通常是这样的：

rootProject.name = 'gradle-example'

多项目构建中的作用

在单项目构建中它是可选的，但在多项目构建中是必须存在的。我们可以通过它来声明所有子项目：

include 'foo', 'bar'

这行代码等价于调用了 Settings 对象上的 include(String... projectPaths) 方法。

生命周期钩子支持

你还可以在这个文件中注册一些生命周期回调逻辑，比如：

rootProject.buildFileName = 'build.gradle.kts'

该文件是在创建 Settings 实例之后被执行的，因此非常适合用来控制整个构建结构。

4. `gradle.properties`

❌ Gradle 默认不会创建这个文件，但它非常有用，可以放在以下位置之一：

项目根目录下
GRADLE_USER_HOME 目录下（默认为 ~/.gradle）
通过 -Dgradle.user.home 指定的位置

配置项格式

这是一个键值对格式的纯文本文件，可用于：

✅ 控制 Gradle 行为（替代命令行参数）
✅ 设置 JVM 参数
✅ 向 Project 注入属性

常见配置项包括：

属性	说明
`org.gradle.caching=true`	启用构建缓存
`org.gradle.daemon=true`	启用守护进程加速构建
`org.gradle.parallel=true`	并行构建
`org.gradle.logging.level=info`	日志级别

还可以设置 JVM 参数：

org.gradle.jvmargs=-Xmx2g -XX:MaxPermSize=256m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

⚠️ 注意：由于解析此文件需要启动 JVM，所以这些 JVM 参数仅影响后续单独启动的 JVM 进程。

5. 构建流程概览

假设我们不是以守护进程方式运行 Gradle，其大致流程如下：

✅ 启动一个新的 JVM 进程
✅ 解析并加载 gradle.properties 配置
✅ 创建 Settings 实例
✅ 执行 settings.gradle 文件以配置 Settings 实例
✅ 根据 Settings 创建项目层次结构
✅ 为每个项目执行对应的 build.gradle 文件

6. 总结

我们已经介绍了 Gradle 中三个关键配置文件的作用：

文件名	用途
`build.gradle`	定义项目构建逻辑、依赖、任务等
`settings.gradle`	定义项目结构（尤其适用于多模块项目）
`gradle.properties`	控制 Gradle 自身行为、JVM 参数、项目属性

合理使用这些文件，可以让你的 Gradle 构建更加灵活、高效。

Persistence

REST

Security