第 1 部分:初始化项目
在本教程中,你将从头开始创建一个简单的 Java 应用程序,通过构建和探索它来学习 Gradle 的核心概念。你将对 Gradle 任务、插件和项目结构有一个实际的理解。
步骤 0. 开始之前
-
确保你已经安装了 Gradle。
-
(可选)安装IntelliJ IDEA。社区版是免费的。
本教程主要使用 macOS 和命令行作为示例,但在 Windows 和 Linux 上的步骤类似。虽然我们偶尔使用 IntelliJ IDEA 来探索项目,但你也可以使用你喜欢的任何 IDE。 |
步骤 1. 初始化项目
为了测试 Gradle 安装,从命令行运行 Gradle
$ gradle
Welcome to Gradle 8.13.
Directory '/' does not contain a Gradle build.
To create a new build in this directory, run gradle init
如果未安装 Gradle,请参阅安装部分。
创建一个名为 tutorial
的新目录并 cd
进入该目录
$ mkdir tutorial
$ cd tutorial
运行 gradle init
并带上下面的参数来生成一个 Java 应用程序
$ gradle init --type java-application --dsl kotlin
对于任何额外的提示,选择默认值。
如果你想尝试一下,可以通过修改 init 参数选择不同的应用程序类型,例如 --type kotlin-application 。 |
完成后,目录应如下所示
tutorial
├── .gradle (1)
│ └── ⋮
├── gradle (2)
│ ├── libs.versions.toml (3)
│ └── wrapper
├── gradlew (4)
├── gradlew.bat (5)
├── settings.gradle.kts (6)
├── app (7)
│ ├── build.gradle.kts
│ └── src
└── ⋮ (8)
1 | 由 Gradle 生成的特定于项目的缓存目录。 |
2 | 包含 Gradle Wrapper 的 JAR 文件和配置。 |
3 | 版本目录,用于在中心位置定义一组依赖项版本。 |
4 | 用于使用 Gradle Wrapper 执行构建的 macOS 和 Linux 脚本。 |
5 | 用于使用 Gradle Wrapper 执行构建的 Windows 脚本。 |
6 | 项目的设置文件,其中定义了子项目列表。 |
7 | Java 应用程序的源代码和构建配置。 |
8 | 可能会存在一些额外的 Git 文件,例如 .gitignore 或 gradle.properties 。 |
tutorial
├── .gradle (1)
│ └── ⋮
├── gradle (2)
│ ├── libs.versions.toml (3)
│ └── wrapper
├── gradlew (4)
├── gradlew.bat (5)
├── settings.gradle (6)
├── app (7)
│ ├── build.gradle
│ └── src
└── ⋮ (8)
1 | 由 Gradle 生成的特定于项目的缓存目录。 |
2 | 包含 Gradle Wrapper 的 JAR 文件和配置。 |
3 | 版本目录,用于在中心位置定义一组依赖项版本。 |
4 | 用于使用 Gradle Wrapper 执行构建的 macOS 和 Linux 脚本。 |
5 | 用于使用 Gradle Wrapper 执行构建的 Windows 脚本。 |
6 | 项目的设置文件,其中定义了子项目列表。 |
7 | Java 应用程序的源代码和构建配置。 |
8 | 可能会存在一些额外的 Git 文件,例如 .gitignore 或 gradle.properties 。 |
步骤 2. 理解 Wrapper
Gradle Wrapper 是启动 Gradle 构建的首选方式。Wrapper 会下载(如果需要)然后调用构建中声明的特定 Gradle 版本。
在你新创建的项目中,首先查看 Gradle Wrapper 使用的文件。它包括一个用于 macOS 和 Linux 的 shell 脚本 以及一个用于 Windows 的批处理脚本 。
这些脚本允许你在系统上无需安装 Gradle 即可运行 Gradle 构建。它还有助于确保不同的开发者以及本地机器和 CI 机器之间使用相同的 Gradle 版本进行构建。
从现在开始,你将不再直接调用 Gradle;而是使用 Gradle wrapper。
步骤 3. 调用 Wrapper
通过输入以下命令来使用 wrapper
$ ./gradlew build
在 Windows 中,命令是
$ gradlew.bat build
第一次运行 wrapper 时,如果 Gradle 二进制文件尚未安装在你的机器上,它会下载并缓存这些文件。
Downloading https://services.gradle.org/distributions/gradle-8.13-bin.zip
...
Welcome to Gradle 8.13!
...
Calculating task graph as no cached configuration is available for tasks: build
BUILD SUCCESSFUL in 4s
7 actionable tasks: 7 executed
Configuration cache entry stored.
Gradle Wrapper 被设计用于提交到源代码管理中,这样任何人都可以在无需首先安装和配置特定版本的 Gradle 的情况下构建项目。
在本例中,我们通过 wrapper 调用 Gradle 来构建项目,因此可以看到 app
目录现在包含一个新的 build
文件夹
$ cd app
$ ls -al
drwxr-xr-x 10 gradle-user staff 320 May 24 18:07 build
-rw-r--r-- 1 gradle-user staff 862 May 24 17:45 build.gradle.kts
drwxr-xr-x 4 gradle-user staff 128 May 24 17:45 src
drwxr-xr-x 10 gradle-user staff 320 May 24 18:07 build
-rw-r--r-- 1 gradle-user staff 862 May 24 17:45 build.gradle
drwxr-xr-x 4 gradle-user staff 128 May 24 17:45 src
除非另有指定,构建过程中生成的所有文件都进入 build
目录。
步骤 4. 理解项目结构
让我们看一下标准的 Gradle 项目结构并与我们的教程项目进行比较

一个构建 (build) 包含
-
一个顶级的
settings.gradle(.kts)
文件。 -
一个根项目 (root project)。
-
一个或多个子项目 (subprojects),每个项目都有自己的
build.gradle(.kts)
文件。
有些构建可能在根项目中包含 build.gradle(.kts)
文件,但不建议这样做。
libs.versions.toml
文件是一个版本目录,用于依赖管理,你将在本教程的后续章节中了解它。
在本教程中
-
根项目名为 tutorial,并在
settings.gradle
文件中使用rootProject.name = "tutorial"
定义。 -
子项目名为 app,并在
settings.gradle
文件中使用include("app")
定义。
根项目可以位于顶级目录或有自己的目录。
一个构建 (build)
-
代表一组相关的软件,你可以一起构建、测试和/或发布它们。
-
可以选择性地包含其他构建(即额外的软件,如库、插件、构建时工具等)。
一个项目 (project)
-
代表你的架构中的一个独立部分——一个库、一个应用程序、一个 Gradle 插件等。
-
可以选择性地包含其他项目。
步骤 5. 在 IDE 中查看文件(可选)
通过双击 tutorial
目录中的 settings.gradle.kts
文件在 IntelliJ IDEA 中打开项目。对于 Groovy DSL 用户,你可能需要在点击 settings.gradle
文件时选择 IntelliJ IDEA 应用程序

在 IDE 中打开 settings.gradle(.kts)
和 build.gradle(.kts)
文件

步骤 6. 理解设置文件
一个项目由一个或多个子项目(有时称为模块)组成。
Gradle 读取 settings.gradle(.kts)
文件以确定哪些子项目构成一个项目构建。
查看项目中的文件
plugins {
// Apply the foojay-resolver plugin to allow automatic download of JDKs
id("org.gradle.toolchains.foojay-resolver-convention") version "0.9.0"
}
rootProject.name = "tutorial"
include("app")
plugins {
// Apply the foojay-resolver plugin to allow automatic download of JDKs
id 'org.gradle.toolchains.foojay-resolver-convention' version '0.9.0'
}
rootProject.name = 'tutorial'
include('app')
tutorial
根项目包含 app
子项目。include
调用的存在将 app
目录转变为一个子项目。
步骤 7. 理解构建脚本
每个子项目都有自己的 build.gradle(.kts)
文件。
build.gradle(.kts)
文件是构建过程的核心组成部分,并定义了构建项目所需的任务。
build.gradle(.kts)
文件由 Gradle 读取并执行。
仔细查看你的 app
子项目(在 app
目录下)中的构建文件
plugins { (1)
// Apply the application plugin to add support for building a CLI application in Java.
application
}
repositories {
// Use Maven Central for resolving dependencies.
mavenCentral()
}
dependencies { (2)
// Use JUnit Jupiter for testing.
testImplementation(libs.junit.jupiter)
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
// This dependency is used by the application.
implementation(libs.guava)
}
// Apply a specific Java toolchain to ease working on different environments.
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
application { (3)
// Define the main class for the application.
mainClass = "org.example.App"
}
tasks.named<Test>("test") {
// Use JUnit Platform for unit tests.
useJUnitPlatform()
}
plugins { (1)
// Apply the application plugin to add support for building a CLI application in Java.
id 'application'
}
repositories {
// Use Maven Central for resolving dependencies.
mavenCentral()
}
dependencies { (2)
// Use JUnit Jupiter for testing.
testImplementation libs.junit.jupiter
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
// This dependency is used by the application.
implementation libs.guava
}
// Apply a specific Java toolchain to ease working on different environments.
java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}
application { (3)
// Define the main class for the application.
mainClass = 'org.example.App'
}
tasks.named('test') {
// Use JUnit Platform for unit tests.
useJUnitPlatform()
}
此构建脚本告知 Gradle app
子项目正在使用哪些依赖项和插件以及在哪里找到它们。
我们将在接下来的章节中更详细地探讨这一点。
下一步: 运行任务 >>