Gradle 是 Java 生态里 Maven 的继任者，用 Groovy/Kotlin DSL 写构建脚本，比 Maven 的 XML 灵活得多。Spring Boot 新项目默认就是 Gradle。本文整理实际开发中常用的配置和命令。

相关文档：Gradle 官方文档 (opens new window) | Spring Boot Gradle Plugin (opens new window)

安装与初始化

安装

# macOS
brew install gradle

# Ubuntu / Debian
sdk install gradle

# 手动下载（推荐用 Wrapper，不一定需要全局安装）
# 下载地址: https://gradle.org/releases/

大多数情况不需要全局安装 Gradle——项目自带的 gradlew（Wrapper）会自动下载指定版本。

创建项目

# 交互式创建
gradle init

# 指定类型
gradle init --type java-application
gradle init --type java-library
gradle init --type basic

---

build.gradle 配置

Groovy DSL（传统，最常见）

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.0'
    id 'io.spring.dependency-management' version '1.1.4'
}

group = 'com.example'
version = '1.0.0'

java {
    sourceCompatibility = '17'
    targetCompatibility = '17'
}

repositories {
    mavenCentral()
}

dependencies {
    // Spring Boot
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

    // Lombok
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'

    // 测试
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

Kotlin DSL（build.gradle.kts，新项目推荐）

plugins {
    java
    id("org.springframework.boot") version "3.2.0"
    id("io.spring.dependency-management") version "1.1.4"
}

group = "com.example"
version = "1.0.0"

java {
    sourceCompatibility = JavaVersion.VERSION_17
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    compileOnly("org.projectlombok:lombok")
    annotationProcessor("org.projectlombok:lombok")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

tasks.withType<Test> {
    useJUnitPlatform()
}

Groovy vs Kotlin DSL 怎么选：新项目选 Kotlin DSL，类型安全、IDE 补全好。老项目保持 Groovy 别折腾。

---

依赖管理

依赖类型

配置	作用	对应 Maven
implementation	编译和运行时都需要，不暴露给依赖方	compile
api	编译和运行时都需要，暴露给依赖方	compile（传递）
compileOnly	仅编译时需要，运行时不打包	provided
runtimeOnly	仅运行时需要	runtime
testImplementation	仅测试编译和运行时需要	test
annotationProcessor	注解处理器（Lombok、MapStruct 等）	-

排除传递依赖

implementation('org.springframework.boot:spring-boot-starter-web') {
    exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
}

// 全局排除
configurations {
    all {
        exclude group: 'org.springframework.boot', module: 'spring-boot-starter-logging'
    }
}

依赖版本统一管理

// 方式一：ext 变量
ext {
    swaggerVersion = '2.2.20'
    mapstructVersion = '1.5.5.Final'
}

dependencies {
    implementation "io.swagger.core.v3:swagger-annotations:${swaggerVersion}"
}

// 方式二：用 Spring Boot BOM（推荐）
dependencies {
    implementation platform('org.springframework.boot:spring-boot-dependencies:3.2.0')
    implementation 'org.springframework.boot:spring-boot-starter-web'  // 版本由 BOM 管理
}

---

常用命令

# 构建项目（编译 + 测试 + 打包）
./gradlew build

# 跳过测试构建（赶时间用）
./gradlew build -x test

# 清理构建产物
./gradlew clean

# 运行测试
./gradlew test

# 运行单个测试类
./gradlew test --tests "com.example.UserServiceTest"

# 运行 Spring Boot 应用
./gradlew bootRun

# 打包（生成 jar/war）
./gradlew bootJar    # 可执行 jar
./gradlew bootWar    # war 包

# 查看依赖树（排查冲突必备）
./gradlew dependencies

# 查看某个配置的依赖
./gradlew dependencies --configuration runtimeClasspath

# 刷新依赖（强制重新下载）
./gradlew build --refresh-dependencies

# 查看所有可用任务
./gradlew tasks

# 查看项目信息
./gradlew projects

---

多模块项目

项目结构

my-project/
├── settings.gradle
├── build.gradle           # 根项目配置（公共）
├── buildSrc/              # 公共构建逻辑（可选）
├── app/                   ├── build.gradle
│                          └── src/
├── common/                ├── build.gradle
│                          └── src/
└── api/                   ├── build.gradle
                           └── src/

settings.gradle

rootProject.name = 'my-project'
include 'app', 'common', 'api'

根 build.gradle（公共配置）

// 所有子模块共享的配置
subprojects {
    apply plugin: 'java'

    group = 'com.example'
    version = '1.0.0'

    java {
        sourceCompatibility = JavaVersion.VERSION_17
    }

    repositories {
        mavenCentral()
    }

    // 公共依赖
    dependencies {
        compileOnly 'org.projectlombok:lombok'
        annotationProcessor 'org.projectlombok:lombok'
        testImplementation 'org.junit.jupiter:junit-jupiter'
    }

    test {
        useJUnitPlatform()
    }
}

子模块依赖

// api/build.gradle
dependencies {
    implementation project(':common')    // 依赖其他子模块
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

---

自定义任务

// 自定义任务
tasks.register('copyConfig', Copy) {
    from 'src/main/resources'
    into 'build/output'
    include '*.yml'
}

// 构建前自动执行
tasks.named('build') {
    dependsOn 'copyConfig'
}

// 命令行传参
tasks.register('printInfo') {
    doLast {
        println "项目: ${project.name}"
        println "版本: ${project.version}"
        println "环境: ${project.findProperty('env') ?: 'dev'}"
    }
}

// 执行: ./gradlew printInfo -Penv=prod

---

镜像加速

国内下载依赖慢，换成阿里云镜像。

单项目配置

repositories {
    maven { url 'https://maven.aliyun.com/repository/public' }
    maven { url 'https://maven.aliyun.com/repository/spring' }
    mavenCentral()
}

全局配置（所有项目生效）

在 ~/.gradle/init.gradle 中配置：

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/spring' }
        mavenCentral()
    }

    // 也可以配置全局镜像
    buildscript {
        repositories {
            maven { url 'https://maven.aliyun.com/repository/public' }
            maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        }
    }
}

---

Gradle Wrapper

Wrapper 是项目自带的 Gradle 启动脚本，保证团队成员用同一个 Gradle 版本。永远用 ./gradlew 而不是全局 gradle。

# 生成或更新 Wrapper（指定版本）
gradle wrapper --gradle-version 8.5

# 生成的文件：
# ├── gradlew              # Linux/macOS 启动脚本
# ├── gradlew.bat          # Windows 启动脚本
# └── gradle/
#     └── wrapper/
#         ├── gradle-wrapper.jar
#         └── gradle-wrapper.properties  # 版本配置

# gradle/wrapper/gradle-wrapper.properties
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip

国内下载慢，改成腾讯镜像：

distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.5-bin.zip

---

常用技巧

JVM 参数调优

# gradle.properties（项目根目录或 ~/.gradle/）
org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m

# 开启并行构建（多模块项目有效）
org.gradle.parallel=true

# 开启构建缓存
org.gradle.caching=true

# 开启守护进程（默认已开启）
org.gradle.daemon=true

# 配置按需加载（多模块项目）
org.gradle.configureondemand=true

全局 Gradle 版本

# ~/.gradle/gradle.properties（全局）
org.gradle.jvmargs=-Xmx2048m
org.gradle.parallel=true
org.gradle.caching=true

查看 Gradle 用户主目录

# 默认在 ~/.gradle/
# 缓存、全局配置、Wrapper 下载的 Gradle 都在这里
ls ~/.gradle/

---

Gradle vs Maven 速查

操作	Gradle	Maven
构建	./gradlew build	mvn package
跳过测试	./gradlew build -x test	mvn package -DskipTests
运行测试	./gradlew test	mvn test
清理	./gradlew clean	mvn clean
依赖树	./gradlew dependencies	mvn dependency:tree
运行应用	./gradlew bootRun	mvn spring-boot:run
打包	./gradlew bootJar	mvn package