本文涵盖 Gradle 构建系统的核心概念、Kotlin DSL 实践、多项目构建、依赖管理、性能优化及 CI/CD 集成，适用于从入门到精通的各阶段开发者。
Gradle 是一款开源的自动化构建工具，基于 Apache Ant 和 Apache Maven 的概念，但引入了基于 Groovy 和 Kotlin 的领域特定语言（DSL）来描述构建逻辑。Gradle 被设计为：
| 维度 | Gradle | Maven |
|---|---|---|
| 配置方式 | DSL（Groovy/Kotlin） | XML（pom.xml） |
| 学习曲线 | 中等（需理解 DSL） | 平缓（约定优于配置） |
| 构建性能 | ⭐⭐⭐⭐⭐（增量构建+缓存） | ⭐⭐⭐（全量构建为主） |
| 灵活性 | ⭐⭐⭐⭐⭐（高度可编程） | ⭐⭐⭐（插件扩展） |
| IDE 支持 | IntelliJ/Android Studio 原生 | 广泛支持 |
| 社区生态 | Android 首选，现代项目趋势 | 传统企业/遗留项目 |
Hugo 的经验：在宝付跨境技术部推动从 Maven 迁移到 Gradle 后，大型微服务项目的构建时间平均减少了 40%，尤其是在开启构建缓存后，CI 流水线时间从 12 分钟降至 4 分钟。
Project（项目）
└── build.gradle.kts（构建脚本）
└── settings.gradle.kts（项目配置）
└── gradle.properties（属性配置）
└── Tasks（任务）
└── 依赖其他 Tasks
└── 输入（Inputs）→ 执行 → 输出（Outputs）
└── Dependencies（依赖）
└── 配置名称（implementation, testImplementation 等）
# macOS (Homebrew)
brew install gradle
# Linux (SDKMAN)
curl -s "https://get.sdkman.io" | bash
sdk install gradle 8.5
# 验证安装
gradle --version
Gradle Wrapper 是项目自带的脚本，无需全局安装 Gradle，确保团队使用统一版本：
# 生成 Wrapper（只需执行一次）
gradle wrapper --gradle-version 8.5
# 后续使用 Wrapper 执行构建
./gradlew build # Linux/macOS
gradlew.bat build # Windows
Wrapper 文件说明：
| 文件 | 作用 |
|---|---|
gradlew / gradlew.bat |
启动脚本 |
gradle/wrapper/gradle-wrapper.properties |
版本配置 |
gradle/wrapper/gradle-wrapper.jar |
Wrapper 逻辑 |
# ~/.bashrc 或 ~/.zshrc
export GRADLE_USER_HOME="$HOME/.gradle"
export GRADLE_OPTS="-Xmx4g -XX:MaxMetaspaceSize=512m"
# 启用守护进程（默认已启用，可微调）
export GRADLE_OPTS="$GRADLE_OPTS -Dorg.gradle.daemon=true"
// ~/.gradle/init.gradle.kts（全局配置）
allprojects {
repositories {
maven { url = uri("https://maven.aliyun.com/repository/public") }
maven { url = uri("https://maven.aliyun.com/repository/central") }
mavenCentral()
}
}
踩坑记录：早期使用阿里云镜像时遇到过
SNAPSHOT依赖不同步的问题，后来改为仅对 release 依赖使用镜像，SNAPSHOT 仍走中央仓库，避免了开发阶段的依赖混乱。
my-project/
├── build.gradle.kts # 构建脚本（核心）
├── settings.gradle.kts # 项目配置
├── gradle.properties # 属性配置
├── gradle/
│ └── libs.versions.toml # 版本目录（推荐）
├── src/
│ ├── main/
│ │ ├── kotlin/ # 主代码
│ │ └── resources/ # 主资源
│ └── test/
│ ├── kotlin/ # 测试代码
│ └── resources/ # 测试资源
└── build/ # 构建输出（自动生成）
// 根项目配置
rootProject.name = "my-project"
// 包含子项目
include("app")
include("lib:core")
include("lib:utils")
// 插件管理（集中管理插件版本）
pluginManagement {
repositories {
gradlePluginPortal()
mavenCentral()
}
}
# 项目属性
version=1.0.0-SNAPSHOT
group=com.example
# Gradle 性能优化
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configureondemand=true
org.gradle.daemon=true
# JVM 参数
org.gradle.jvmargs=-Xmx4g -XX:+HeapDumpOnOutOfMemoryError
Kotlin DSL 是 Gradle 现代项目的首选配置方式，相比 Groovy DSL 具有类型安全、IDE 自动补全、重构友好等优势。
// build.gradle.kts
plugins {
kotlin("jvm") version "1.9.22"
application
}
group = "com.example"
version = "1.0.0"
repositories {
mavenCentral()
}
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
testImplementation(kotlin("test"))
}
application {
mainClass.set("com.example.MainKt")
}
有两种配置模式：
tasks {
compileKotlin {
kotlinOptions.jvmTarget = "11"
}
compileTestKotlin {
kotlinOptions.jvmTarget = "11"
}
}
考虑到 compileKotlin 和 compileTestKotlin 都是 KotlinCompile 类型的 Task，可以合并为统一配置：
tasks.withType<KotlinCompile> {
kotlinOptions {
jvmTarget = "11"
freeCompilerArgs += "-Xjsr305=strict"
}
}
最佳实践：使用
withType<T>()批量配置同类 Task，避免重复代码，且新增同类 Task 时自动生效。
// 注册自定义任务
tasks.register<Copy>("copyConfig") {
from("src/main/config")
into("$buildDir/config")
include("*.properties")
}
// 扩展已有任务
tasks.jar {
manifest {
attributes(
"Implementation-Title" to project.name,
"Implementation-Version" to project.version
)
}
from("LICENSE") {
into("META-INF")
}
}
// 在多项目构建中访问其他项目
dependencies {
implementation(project(":lib:core"))
}
// 配置跨项目依赖
tasks.test {
dependsOn(":lib:core:test")
}
Gradle 构建由**任务（Task）**组成，每个任务是构建过程中的一个原子操作。任务具有：
tasks {
register<Zip>("packageDist") {
from("src/dist")
archiveFileName.set("dist.zip")
destinationDirectory.set(file("$buildDir/distributions"))
}
register<Copy>("deploy") {
dependsOn("packageDist") // 显式依赖
from(tasks.named<Zip>("packageDist").map { it.outputs.files })
into("/var/www/deploy")
}
}
Gradle 通过比较任务的输入和输出来决定是否需要重新执行：
tasks.register<JavaCompile>("compileCustom") {
// 定义输入
source = fileTree("src/custom/java")
classpath = configurations.compileClasspath.get()
// 定义输出
destinationDirectory.set(file("$buildDir/classes/custom"))
// 自定义输入属性（影响缓存键）
inputs.property("javaVersion", "11")
}
增量构建触发条件：
| 场景 | 行为 |
|---|---|
| 输入未变化 | 任务标记为 UP-TO-DATE，跳过执行 |
| 输出被删除 | 重新执行任务 |
| 输入属性变化 | 重新执行任务 |
// 在所有项目评估完成后执行
gradle.projectsEvaluated {
println("所有项目评估完成")
}
// 在构建完成后执行
gradle.buildFinished {
println("构建结束，结果: ${it.failure == null}")
}
// 任务执行前后钩子
tasks.withType<Test> {
doFirst {
println("测试开始: $name")
}
doLast {
println("测试结束: $name")
}
}
Gradle 使用**配置（Configuration）**来分类依赖的使用场景：
| 配置名称 | 用途 | 传递性 |
|---|---|---|
implementation |
编译和运行时必需 | 不传递 |
api |
编译和运行时必需，传递给依赖方 | 传递 |
compileOnly |
仅编译时需要（如注解处理器） | 不传递 |
runtimeOnly |
仅运行时需要 | 不传递 |
testImplementation |
测试代码依赖 | 不传递 |
testRuntimeOnly |
测试运行时依赖 | 不传递 |
dependencies {
implementation("org.springframework.boot:spring-boot-starter-web:3.2.0")
api("com.google.guava:guava:32.1.3-jre") // 传递性依赖
compileOnly("org.projectlombok:lombok:1.18.30") // 仅编译
runtimeOnly("com.h2database:h2:2.2.224") // 仅运行时
testImplementation("org.junit.jupiter:junit-jupiter:5.10.0")
}
Gradle 7.0+ 推荐的依赖版本管理方式：
# gradle/libs.versions.toml
[versions]
kotlin = "1.9.22"
springBoot = "3.2.0"
coroutines = "1.7.3"
[libraries]
kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }
kotlin-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
spring-boot-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "springBoot" }
[bundles]
kotlin-core = ["kotlin-stdlib", "kotlin-coroutines"]
[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
spring-boot = { id = "org.springframework.boot", version.ref = "springBoot" }
// build.gradle.kts 中使用
plugins {
alias(libs.plugins.kotlin.jvm)
alias(libs.plugins.spring.boot)
}
dependencies {
implementation(libs.kotlin.stdlib)
implementation(libs.bundles.kotlin.core)
implementation(libs.spring.boot.web)
}
最佳实践：版本目录将依赖版本集中管理，避免多模块项目中的版本漂移问题，同时支持 IDE 自动补全。
// 强制使用特定版本
configurations.all {
resolutionStrategy {
force("com.fasterxml.jackson.core:jackson-databind:2.15.3")
// 缓存动态版本（避免频繁检查）
cacheDynamicVersionsFor(10, TimeUnit.MINUTES)
cacheChangingModulesFor(4, TimeUnit.HOURS)
}
}
// 排除传递性依赖
dependencies {
implementation("org.springframework.boot:spring-boot-starter-web") {
exclude(group = "org.springframework.boot", module = "spring-boot-starter-logging")
}
}
# 查看完整依赖树
./gradlew dependencies
# 查看运行时依赖
./gradlew dependencies --configuration runtimeClasspath
# 查看依赖报告（HTML）
./gradlew dependencyInsight --dependency jackson-databind
root/
├── settings.gradle.kts
├── build.gradle.kts # 根项目配置（可选）
├── gradle.properties
├── app/ # 应用模块
│ └── build.gradle.kts
├── lib-core/ # 核心库
│ └── build.gradle.kts
└── lib-utils/ # 工具库
└── build.gradle.kts
rootProject.name = "my-multi-project"
include("app")
include("lib-core")
include("lib-utils")
// 自定义项目名称
project(":app").name = "web-application"
project(":lib-core").name = "core-library"
// app/build.gradle.kts
dependencies {
implementation(project(":lib-core"))
implementation(project(":lib-utils"))
}
// lib-core/build.gradle.kts
plugins {
`java-library` // 发布为库
}
// buildSrc/src/main/kotlin/kotlin-conventions.gradle.kts
plugins {
kotlin("jvm")
}
repositories {
mavenCentral()
}
kotlin {
jvmToolchain(11)
}
tasks.withType<Test> {
useJUnitPlatform()
}
// app/build.gradle.kts
plugins {
id("kotlin-conventions")
}
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core")
}
Hugo 的经验：在微服务项目中，使用 Convention Plugins 统一管理 Kotlin 版本、测试框架、代码质量检查，使得新增服务模块只需 5 行配置即可具备完整的构建能力。
| 插件 | 用途 | 示例 |
|---|---|---|
java |
Java 项目构建 | plugins { java } |
java-library |
可发布的 Java 库 | plugins { java-library } |
application |
可运行的应用 | plugins { application } |
kotlin("jvm") |
Kotlin JVM 项目 | plugins { kotlin("jvm") } |
kotlin("kapt") |
Kotlin 注解处理 | plugins { kotlin("kapt") } |
plugins {
// Spring Boot
id("org.springframework.boot") version "3.2.0"
id("io.spring.dependency-management") version "1.1.4"
// 代码质量
id("org.jlleitschuh.gradle.ktlint") version "12.0.3"
id("io.gitlab.arturbosch.detekt") version "1.23.4"
// 测试覆盖率
id("org.jetbrains.kotlinx.kover") version "0.7.5"
}
// buildSrc/src/main/kotlin/my-plugin.gradle.kts
plugins {
base
}
tasks.register("hello") {
doLast {
println("Hello from custom plugin!")
}
}
// 使用自定义插件
// app/build.gradle.kts
plugins {
id("my-plugin")
}
构建缓存是 Gradle 最强大的性能优化特性，可跨项目、跨机器复用构建输出：
// gradle.properties
org.gradle.caching=true
// 配置远程缓存（CI/CD 共享）
// ~/.gradle/gradle.properties
systemProp.gradle.cache.remote.url=https://gradle-cache.example.com/cache
systemProp.gradle.cache.remote.username=cache-user
# 命令行启用缓存
./gradlew build --build-cache
# 强制刷新缓存
./gradlew build --rerun-tasks
# gradle.properties
org.gradle.parallel=true # 并行执行独立项目
org.gradle.configureondemand=true # 按需配置项目
org.gradle.daemon=true # 守护进程（默认启用）
# 生成构建扫描报告
./gradlew build --scan
# 性能分析
./gradlew build --profile
# 查看任务执行时间
./gradlew build --console=verbose
org.gradle.caching=true)org.gradle.parallel=true)org.gradle.daemon=true)kapt.incremental.apt=true)implementation("lib:1.2.3") 而非 implementation("lib:1.2.+"))实际效果：在宝付的风控系统构建中，开启所有优化选项后，本地构建从 3 分钟降至 45 秒，CI 构建从 15 分钟降至 5 分钟。
# .github/workflows/build.yml
name: Build
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up JDK
uses: actions/setup-java@v4
with:
java-version: '17'
distribution: 'temurin'
- name: Setup Gradle
uses: gradle/actions/setup-gradle@v3
with:
gradle-home-cache-cleanup: true
- name: Build
run: ./gradlew build --no-daemon
- name: Test
run: ./gradlew test --no-daemon
- name: Publish
if: github.ref == 'refs/heads/main'
run: ./gradlew publish --no-daemon
env:
MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
# .gitlab-ci.yml
image: gradle:8.5-jdk17
variables:
GRADLE_OPTS: "-Dorg.gradle.daemon=false"
stages:
- build
- test
- deploy
build:
stage: build
script:
- gradle assemble
artifacts:
paths:
- build/libs/
test:
stage: test
script:
- gradle test
artifacts:
reports:
junit: build/test-results/test/*.xml
deploy:
stage: deploy
script:
- gradle publish
only:
- main
// build.gradle.kts
plugins {
id("com.google.cloud.tools.jib") version "3.4.0"
}
jib {
from {
image = "eclipse-temurin:17-jre-alpine"
}
to {
image = "registry.example.com/my-app"
tags = setOf(version.toString(), "latest")
}
container {
ports = listOf("8080")
environment = mapOf("SPRING_PROFILES_ACTIVE" to "production")
}
}
# 构建并推送镜像
./gradlew jib
# 清除依赖缓存
./gradlew clean --refresh-dependencies
# 查看详细日志
./gradlew build --info
./gradlew build --debug
# 检查网络代理
# ~/.gradle/gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
# gradle.properties
org.gradle.jvmargs=-Xmx8g -XX:MaxMetaspaceSize=1g -XX:+HeapDumpOnOutOfMemoryError
# 查看任务依赖图
./gradlew tasks --all
# 查看特定任务详情
./gradlew help --task build
# 堆栈跟踪
./gradlew build --stacktrace
./gradlew build --full-stacktrace
| 问题 | 原因 | 解决 |
|---|---|---|
Unresolved reference: implementation |
未应用 Java/Kotlin 插件 | plugins { java } |
Type mismatch |
类型推断失败 | 显式指定类型参数 |
Script compilation error |
语法错误 | 检查括号匹配、引号 |
project/
├── buildSrc/ # 构建逻辑复用
│ └── src/main/kotlin/
├── gradle/
│ └── libs.versions.toml # 版本目录
├── app/
├── lib-*/
├── settings.gradle.kts
├── build.gradle.kts
└── gradle.properties
| 层级 | 配置内容 | 示例 |
|---|---|---|
全局（~/.gradle/） |
镜像、代理、个人偏好 | init.gradle.kts |
项目（gradle.properties） |
版本、性能参数 | org.gradle.parallel=true |
模块（build.gradle.kts） |
依赖、任务、插件 | dependencies {} |
./gradlew dependencyCheckAnalyze)文档信息
- 版本：Gradle 8.x
- 最后更新：2026-04-27
- 维护者：Hugo Gu
- 适用范围：Java/Kotlin 后端项目、Android 项目、多模块微服务架构