开发日常
开发工具篇
构建工具
Gradle相关

Gradle安装与项目结构

# Gradle 安装与项目结构

# Gradle 安装

# 方式一：手动安装

官网：https://gradle.org/ (opens new window)
下载地址：https://services.gradle.org/distributions/ (opens new window)

下载解压后配置环境变量：

环境变量	说明
`GRADLE_HOME`	指定 Gradle 的安装路径
`PATH`	将 `%GRADLE_HOME%\bin` 添加到 PATH 中

Gradle 依赖 JDK 8 及以上版本，运行前请确保已配置 JAVA_HOME。

配置完成后执行 gradle -v，显示版本信息即安装成功：

------------------------------------------------------------
Gradle 9.6.1
------------------------------------------------------------
Build time:    2024-09-20
Kotlin:        2.0.20
Groovy:        3.0.22
Ant:           Apache Ant(TM) version 1.10.14
JVM:           25 (Oracle Corporation 25)
OS:            Windows 11 10.0 amd64

1
2
3
4
5
6
7
8
9

# 方式二：使用 Gradle Wrapper（推荐）

实际项目中几乎不使用本地安装的 Gradle，而是使用 Gradle Wrapper。Wrapper 会自动下载项目指定版本的 Gradle，确保团队成员和 CI 环境使用一致的 Gradle 版本。

这类似于 Maven 的 mvnw，但 Gradle Wrapper 的使用更加普遍，几乎是项目标配。

# Wrapper 的文件组成

项目根目录/
├── gradlew                  # Linux/Mac 下的 Wrapper 启动脚本
├── gradlew.bat              # Windows 下的 Wrapper 启动脚本
└── gradle/
    └── wrapper/
        ├── gradle-wrapper.jar       # Wrapper 核心逻辑
        └── gradle-wrapper.properties # 指定 Gradle 版本和下载地址

1
2
3
4
5
6
7

# gradle-wrapper.properties 详解

以 interview-guide 项目的配置为例：

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
# Gradle 发行版下载地址
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-9.6.1-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

1
2
3
4
5
6
7
8

配置项	说明
`distributionUrl`	Gradle 发行版的下载地址，决定项目使用的 Gradle 版本
`distributionBase`	下载的 Gradle 存放基础目录，默认 `GRADLE_USER_HOME`
`distributionPath`	相对于 distributionBase 的存放路径
`networkTimeout`	网络超时时间（毫秒）
`validateDistributionUrl`	是否校验下载地址有效性

国内加速：官方地址下载慢，可替换为国内镜像。interview-guide 项目使用了腾讯云镜像：
# 腾讯云（首选）
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-9.6.1-bin.zip
# 阿里云（备选）
#distributionUrl=https\://mirrors.aliyun.com/gradle/gradle-9.6.1-bin.zip
1
2
3
4

# 生成 Wrapper

在已有项目中生成或更新 Wrapper：

# 指定版本生成
gradle wrapper --gradle-version 9.6.1

# 使用当前安装的 Gradle 版本生成
gradle wrapper

1
2
3
4
5

生成后，将 gradlew、gradlew.bat 和 gradle/wrapper/ 目录提交到版本库，团队成员拉取代码后直接使用 ./gradlew 即可，无需本地安装 Gradle。

# 使用 Wrapper 执行构建

# Windows
gradlew build

# Linux/Mac
./gradlew build

1
2
3
4
5

后文所有命令均以 gradlew 形式给出，实际使用时 Windows 直接 gradlew，Linux/Mac 用 ./gradlew。

# Gradle 目录结构

# 安装目录结构

手动安装的 Gradle，解压后目录结构如下：

gradle-9.6.1/
├── bin/          # 可执行脚本（gradle、gradle.bat）
├── lib/          # Gradle 核心库和依赖
├── init.d/       # 初始化脚本目录
├── LICENSE / NOTICE
└── README

1
2
3
4
5
6

# GRADLE_USER_HOME

GRADLE_USER_HOME 是 Gradle 的用户级主目录，类似于 Maven 的 ~/.m2。默认路径为 ~/.gradle，结构如下：

~/.gradle/
├── caches/           # 缓存目录（下载的依赖、构建缓存等）
│   ├── modules-2/    # 依赖包缓存
│   └── builds-1/     # 构建缓存
├── wrapper/          # Wrapper 下载的 Gradle 发行版
│   └── dists/
│       └── gradle-9.6.1-bin/
└── daemon/           # Gradle Daemon 进程相关文件

1
2
3
4
5
6
7
8

可以通过环境变量 GRADLE_USER_HOME 自定义此目录位置。

# Gradle 项目结构

# 标准单模块项目

使用 java 插件的项目，标准目录结构如下（与 Maven 一致）：

my-project/
├── build.gradle              # 项目构建脚本（核心）
├── settings.gradle           # 项目设置（项目名、子项目）
├── gradle.properties         # Gradle 属性配置
├── gradlew / gradlew.bat     # Wrapper 脚本
├── gradle/
│   ├── libs.versions.toml    # Version Catalog（依赖版本管理）
│   └── wrapper/              # Wrapper 文件
└── src/
    ├── main/
    │   ├── java/             # 主源代码
    │   └── resources/        # 主资源文件
    └── test/
        ├── java/             # 测试源代码
        └── resources/        # 测试资源文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Gradle 的源码目录约定与 Maven 完全一致（src/main/java、src/test/java），从 Maven 迁移过来无需调整目录结构。

# 多模块项目结构

以 interview-guide 项目为例，多模块项目结构如下：

interview-guide/
├── settings.gradle           # 根项目设置，include 子项目
├── gradle.properties         # 全局属性
├── gradle/
│   ├── libs.versions.toml    # 统一版本管理
│   └── wrapper/
├── gradlew / gradlew.bat
├── app/                      # 子项目 1
│   ├── build.gradle          # 子项目构建脚本
│   └── src/
├── shared/                   # 子项目 2（示例）
│   ├── build.gradle
│   └── src/
└── build.gradle              # 根项目构建脚本（可选，用于公共配置）

1
2
3
4
5
6
7
8
9
10
11
12
13
14

与 Maven 的父子 POM 不同，Gradle 多模块通过 settings.gradle 的 include 声明，根项目的 build.gradle 可通过 subprojects {} 块统一配置所有子项目。

# settings.gradle 详解

settings.gradle 是 Gradle 构建的入口文件，在构建脚本之前执行，用于声明项目名称、子项目和插件仓库。

以 interview-guide 项目为例：

// 1. 插件管理：声明从哪里下载 Gradle 插件
pluginManagement {
    repositories {
        maven { url = uri('https://maven.aliyun.com/repository/public/') }
        maven { url = uri('https://maven.aliyun.com/repository/gradle-plugin/') }
        maven { url = uri('https://maven.aliyun.com/repository/spring-plugin/') }
        gradlePluginPortal()
    }
}

// 2. 应用工具链解析插件（自动下载所需 JDK）
plugins {
    id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'
}

// 3. 声明根项目名称
rootProject.name = 'interview-guide'

// 4. 声明包含的子项目
include('app')

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 关键配置项

配置项	说明
`pluginManagement`	声明 Gradle 插件的下载仓库（类似 Maven 的插件仓库）
`plugins`	应用设置级插件（如工具链自动下载 JDK）
`rootProject.name`	根项目名称
`include`	声明包含的子项目，参数是项目路径

# include 的用法

// 单层子项目
include('app')

// 多个子项目
include('app', 'shared', 'common')

// 嵌套子项目（用冒号分隔）
include('app:web', 'app:core')
// 等价于 app/web/ 和 app/core/ 两个子项目

1
2
3
4
5
6
7
8
9

include 的路径用冒号 : 分隔，对应目录层级。include('app:web') 表示 app/web/ 目录下的子项目。

# gradle.properties 详解

gradle.properties 用于配置 Gradle 构建本身的属性（不是项目属性），位于项目根目录。

以 interview-guide 项目为例：

# 指定 JDK 版本路径
org.gradle.java.home=D:\\software\\java\\jdk\\jdk25
# 指定编码格式，避免控制台中文乱码
org.gradle.jvmargs=-Dfile.encoding=UTF-8

1
2
3
4

# 常用配置项

配置项	说明	示例
`org.gradle.java.home`	指定构建使用的 JDK 路径	`D:\\software\\java\\jdk\\jdk25`
`org.gradle.jvmargs`	Gradle Daemon JVM 参数	`-Dfile.encoding=UTF-8 -Xmx2048m`
`org.gradle.parallel`	是否并行构建	`true`
`org.gradle.caching`	是否启用构建缓存	`true`
`org.gradle.daemon`	是否启用 Daemon	`true`（默认）
`org.gradle.configureondemand`	按需配置（仅配置参与构建的模块）	`true`

# 自定义项目属性

在 gradle.properties 中也可以定义自定义属性，在 build.gradle 中通过 project 对象访问：

# gradle.properties
myCustomProperty=hello

1
2

// build.gradle
println project.findProperty('myCustomProperty')  // 输出 hello

1
2

gradle.properties 也可以放在 GRADLE_USER_HOME 目录下（~/.gradle/gradle.properties），作为全局配置，对所有项目生效。

# 创建新项目

# 使用 gradle init

Gradle 提供了 init 命令快速生成项目骨架：

# 交互式生成
gradle init

# 指定类型和语言
gradle init --type java-application --dsl groovy --test-framework junit

1
2
3
4
5

支持的 --type：

类型	说明
`java-application`	Java 应用程序
`java-library`	Java 库
`java-gradle-plugin`	Gradle 插件项目
`basic`	基础项目（仅生成 Gradle 文件）

# 手动创建

最小化的 Gradle 项目只需要两个文件：

settings.gradle：

rootProject.name = 'my-project'

build.gradle：

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

1
2
3
4
5
6
7

然后执行 gradle wrapper 生成 Wrapper，项目即可运行。

# 与 Maven 的对应关系

Maven	Gradle	说明
`pom.xml`	`build.gradle` / `build.gradle.kts`	项目构建脚本
`settings.xml`	`gradle.properties` + `settings.gradle`	全局/项目配置
`~/.m2/repository`	`~/.gradle/caches`	本地依赖缓存
`mvnw` / `mvnw.cmd`	`gradlew` / `gradlew.bat`	Wrapper 脚本
父子 POM	`settings.gradle` + `include`	多模块组织
`<dependencyManagement>`	`libs.versions.toml`	版本集中管理

# 学习参考

上次更新: 2026/11/4 08:44:38

← Gradle简介 Gradle构建脚本详解→