Gradle 参考文档 #

1. Gradle 简介 #

Gradle是一款功能强大的开源构建自动化工具，它结合了Ant的灵活性和Maven的约定优于配置思想，支持多种语言和平台。

主要特点：

  • 基于Groovy/Kotlin的DSL构建脚本
  • 强大的依赖管理系统
  • 高度可扩展的插件架构
  • 增量构建支持
  • 多项目构建支持
  • 与主流IDE无缝集成

2. 安装与配置 #

2.1 系统要求 #

  • Java JDK 8 或更高版本
  • 操作系统：Windows、macOS、Linux

2.2 安装方法 #

macOS (使用Homebrew) #

bash 
brew install gradle

Windows (使用Chocolatey) #

powershell 
choco install gradle

手动安装 #

  1. 从Gradle官网下载最新版本的二进制包
  2. 解压到合适的目录
  3. 配置环境变量 GRADLE_HOME 指向解压目录
  4. 将 $GRADLE_HOME/bin 添加到系统PATH

2.3 验证安装 #

bash 
gradle --version

3. 核心概念 #

3.1 项目 (Project) #

Gradle构建的基本单位，对应一个软件模块或组件。每个项目包含一个或多个任务。

3.2 任务 (Task) #

Gradle执行的基本工作单元，例如编译代码、运行测试、打包等。

3.3 构建脚本 #

定义项目和任务的脚本文件，默认名称为：

  • build.gradle (Groovy DSL)
  • build.gradle.kts (Kotlin DSL)

3.4 设置文件 #

定义多项目构建的文件，默认名称为：

  • settings.gradle (Groovy DSL)
  • settings.gradle.kts (Kotlin DSL)

4. 常用命令 #

4.1 基础命令 #

bash 
# 查看Gradle版本
gradle --version

# 查看项目中的任务
gradle tasks

# 查看任务详情
gradle help --task <task-name>

# 执行任务
gradle <task-name>

# 并行执行任务
gradle <task-name> --parallel

# 离线模式执行
gradle <task-name> --offline

4.2 构建命令 #

bash 
# 编译项目
gradle compileJava

# 运行测试
gradle test

# 生成JAR包
gradle jar

# 生成WAR包
gradle war

# 清理构建产物
gradle clean

# 执行完整构建（clean + build）
gradle clean build

# 跳过测试执行构建
gradle build -x test

4.3 依赖管理命令 #

bash 
# 查看依赖树
gradle dependencies

# 查看特定配置的依赖树
gradle dependencies --configuration <configuration-name>

# 检查依赖冲突
gradle dependencyInsight --dependency <dependency-name>

# 下载所有依赖
gradle dependencies --refresh-dependencies

5. 依赖管理 #

5.1 仓库配置 #

groovy 
repositories {
    // Maven中央仓库
    mavenCentral()
    
    // Google仓库
    google()
    
    // 本地Maven仓库
    mavenLocal()
    
    // 自定义Maven仓库
    maven {
        url "https://repo.example.com/maven2"
    }
    
    // Ivy仓库
    ivy {
        url "https://repo.example.com/ivy"
    }
}

5.2 依赖声明 #

groovy 
dependencies {
    // 编译时依赖
    implementation 'com.google.guava:guava:31.1-jre'
    
    // 运行时依赖
    runtimeOnly 'com.h2database:h2:2.1.214'
    
    // 测试依赖
    testImplementation 'junit:junit:4.13.2'
    
    // 编译时注解处理
    annotationProcessor 'org.projectlombok:lombok:1.18.24'
    
    // 导入BOM
    implementation platform('org.springframework.boot:spring-boot-dependencies:2.7.5')
}

5.3 依赖范围 #

  • implementation: 编译和运行时依赖，不暴露给下游项目
  • api: 编译和运行时依赖，暴露给下游项目
  • compileOnly: 仅编译时依赖，运行时不需要
  • runtimeOnly: 仅运行时依赖，编译时不需要
  • testImplementation: 仅测试编译和运行时依赖
  • testCompileOnly: 仅测试编译时依赖
  • testRuntimeOnly: 仅测试运行时依赖

6. 多项目构建 #

6.1 创建多项目结构 #

text 
root-project/
├── settings.gradle
├── build.gradle
├── module-1/
│   └── build.gradle
└── module-2/
    └── build.gradle

6.2 配置settings.gradle #

groovy 
rootProject.name = 'root-project'
include 'module-1', 'module-2'

6.3 配置根项目build.gradle #

groovy 
// 所有子项目的通用配置
subprojects {
    apply plugin: 'java'
    
    repositories {
        mavenCentral()
    }
    
    dependencies {
        testImplementation 'junit:junit:4.13.2'
    }
}

6.4 项目间依赖 #

groovy 
// module-2/build.gradle
dependencies {
    implementation project(':module-1')
}

6.5 执行多项目任务 #

bash 
# 执行所有项目的测试
gradle test

# 执行特定项目的任务
gradle :module-1:build

# 执行根项目和特定子项目的任务
gradle build :module-1:test

7. 插件系统 #

7.1 应用插件 #

groovy 
// 应用核心插件（Short Name）
apply plugin: 'java'
apply plugin: 'war'
apply plugin: 'application'

// 应用第三方插件（完整坐标）
plugins {
    id 'org.springframework.boot' version '2.7.5'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
}

7.2 常用核心插件 #

  • java: Java项目支持
  • war: Web应用支持
  • application: 可执行应用支持
  • groovy: Groovy项目支持
  • kotlin: Kotlin项目支持
  • scala: Scala项目支持
  • ear: EAR包支持

8. 任务管理 #

8.1 定义任务 #

groovy 
// 简单任务
task hello {
    doLast {
        println 'Hello Gradle!'
    }
}

// 使用闭包简化
task hello << {
    println 'Hello Gradle!'
}

// 任务依赖
task helloWorld(dependsOn: hello) {
    doLast {
        println 'Hello World!'
    }
}

// 配置任务属性
task copyFiles(type: Copy) {
    from 'src/main/resources'
    into 'build/resources'
    include '**/*.properties'
}

8.2 任务类型 #

  • Copy: 文件复制
  • Delete: 文件删除
  • JavaCompile: Java编译
  • Test: 测试执行
  • Jar: JAR包生成
  • War: WAR包生成
  • Exec: 执行外部命令

9. 高级特性 #

9.1 构建生命周期 #

  1. 初始化阶段: 加载settings.gradle，确定项目结构
  2. 配置阶段: 加载所有build.gradle文件，配置项目和任务
  3. 执行阶段: 执行指定的任务及其依赖

9.2 增量构建 #

Gradle会跟踪任务的输入和输出，只有当输入发生变化时才会重新执行任务，提高构建效率。

groovy 
task processFiles(type: Copy) {
    inputs.files fileTree('src')
    outputs.dir 'build/processed'
    
    from 'src'
    into 'build/processed'
    filter { line -> line.replace('old', 'new') }
}

9.3 自定义构建逻辑 #

groovy 
// 自定义扩展属性
extensions.create('myConfig', MyConfig)

class MyConfig {
    String appName = 'MyApp'
    String version = '1.0.0'
}

// 使用自定义属性
task printConfig {
    doLast {
        println "App Name: ${myConfig.appName}"
        println "Version: ${myConfig.version}"
    }
}

10. IDE集成 #

10.1 IntelliJ IDEA #

bash 
# 生成IDEA项目文件
gradle idea

# 打开IDEA，导入项目即可

10.2 Eclipse #

bash 
# 生成Eclipse项目文件
gradle eclipse

# 打开Eclipse，导入项目即可

10.3 VS Code #

使用Gradle for Java扩展，直接导入Gradle项目。

11. 最佳实践 #

11.1 构建脚本组织 #

  • 保持build.gradle简洁，将复杂逻辑提取到单独文件
  • 使用Kotlin DSL提高类型安全性
  • 利用插件简化配置

11.2 依赖管理 #

  • 始终指定依赖版本
  • 使用BOM管理版本一致性
  • 定期更新依赖
  • 避免不必要的依赖

11.3 性能优化 #

  • 启用并行构建
  • 利用增量构建
  • 合理配置缓存
  • 避免在配置阶段执行耗时操作

11.4 持续集成 #

  • 在CI环境中使用--no-build-cache确保构建一致性
  • 使用gradle build --scan生成构建扫描报告
  • 配置构建超时和资源限制

12. 常见问题与解决方案 #

12.1 依赖冲突 #

问题: 不同依赖版本之间的冲突 解决方案: 使用dependencyInsight查看冲突，使用force强制指定版本

groovy 
dependencies {
    implementation('com.google.guava:guava:31.1-jre') {
        force = true
    }
}

12.2 构建缓慢 #

问题: 构建过程耗时过长 解决方案:

  • 启用并行构建
  • 优化测试执行
  • 利用构建缓存
  • 避免不必要的任务执行

12.3 内存不足 #

问题: Gradle构建过程中内存不足 解决方案: 在gradle.properties中配置JVM参数

properties 
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=512m

13. 资源链接 #

最后更新：2026-02-05