Gradle 构建 Spring Boot 项目的关键并不是把依赖写进 build.gradle 那么简单。Spring Boot Gradle 插件会扩展 Java 插件,在 Gradle 的任务图中插入 bootJar 和 bootRun 等任务,同时通过依赖管理插件统一控制 starter 版本。如果没有理解这层扩展关系,遇到构建失败、可执行 Jar 无法启动、多模块依赖混乱这些问题时,很容易在错误方向上反复试错。下面围绕脚本结构、插件任务和构建优化展开。

一、Spring Boot Gradle 项目的脚本骨架
一个最小可用的 build.gradle 至少包含 plugins、java toolchain、repositories、dependencies 四部分。plugins 块中声明 Spring Boot Gradle 插件和依赖管理插件,前者负责生成可执行 Jar,后者让 starter 依赖不必逐个写版本号。这里需要特别注意插件声明顺序:如果依赖管理插件放在 Spring Boot 插件之前,Gradle 仍能解析,但 BOM 导入时机可能出现差异,建议保持官方顺序。
下面是一个标准脚本,它可以直接用于单模块的 Spring Boot Web 项目。group 和 version 属于项目坐标,java toolchain 用来指定编译用的 JDK 版本,repositories 中的 mavenCentral 则是依赖下载源。
plugins {
id 'org.springframework.boot' version '3.2.5'
id 'io.spring.dependency-management' version '1.1.4'
id 'java'
}
group = 'com.example'
version = '0.0.1-SNAPSHOT'
java {
toolchain {
languageVersion = JavaLanguageVersion.of(17)
}
}
repositories {
mavenCentral()
}
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
tasks.named('test') {
useJUnitPlatform()
}
如果去掉了 io.spring.dependency-management 插件,dependencies 块中的 spring-boot-starter-web 就必须显式指定版本,例如 implementation 'org.springframework.boot:spring-boot-starter-web:3.2.5'。这样做虽然可以运行,但在多模块或升级 Spring Boot 版本时,容易出现同一项目内版本不一致的问题。依赖管理插件的作用是引入 Spring Boot BOM,所有 starter 版本由 BOM 统一约束。换句话说,依赖管理插件不是可选项,而是保持构建稳定的关键一环。
二、bootJar 与 bootRun:两条不同的执行链路
bootJar 是 Spring Boot 插件最核心的任务,产物不是普通的 Jar。普通 Jar 只包含项目自身的 class 文件和资源,依赖需要外部 Classpath;bootJar 会把依赖 Jar 解压后重新组织到 BOOT-INF/lib 目录,并放入 Spring Boot 的 loader 类,使得 java -jar app.jar 可以独立启动。可执行 Jar 内部还有一个关键目录 BOOT-INF/classes,用于存放业务模块的编译结果。这个结构直接影响容器镜像分层,也是 Spring Boot 官方推荐使用分层 Jar 的原因。
在 Gradle 中执行 ./gradlew build 时,bootJar 会随 build 任务自动执行。但如果只想打普通 Jar,可以运行 ./gradlew jar;这个任务由 Java 插件提供,产物不能直接通过 java -jar 运行。日常打包应使用 ./gradlew bootJar 或 ./gradlew build。以下配置可修改产物名字并开启分层 Jar,分层顺序会影响镜像构建时缓存复用的效率。
tasks.named('bootJar') {
archiveFileName = 'app.jar'
layered {
application {
intoLayer('spring-boot-loader') {
include 'org/springframework/boot/loader/**'
}
intoLayer('application')
}
dependencies {
intoLayer('snapshot-dependencies') {
include '*:*:*SNAPSHOT'
}
intoLayer('dependencies')
}
layerOrder = ['spring-boot-loader', 'dependencies', 'snapshot-dependencies', 'application']
}
}
bootRun 则用于开发阶段直接运行应用,不需要先打包。它会在 Gradle 的 JVM 中启动 Spring Boot 应用,并支持将 resources 目录变更自动反映到运行时。如果项目使用 devtools,bootRun 会配合热重载,修改类后自动重启。与 java -jar 不同,bootRun 依赖 Gradle 的运行时类路径,因此排查问题时要注意:有些在 IDE 里能跑、打包后不能跑的情况,通常是资源文件没有被 bootJar 打包进去,而不是 bootRun 有问题。
三、多模块工程的 Gradle 配置
多模块 Spring Boot 项目通常分为 api、service、common 等子模块,根项目只维护公共配置,不生成可执行 Jar。根 build.gradle 中插件必须使用 apply false 声明,否则每个子模块都会被打成可执行 Jar,common 模块也会出现 bootJar 任务,这不是期望的结果。
plugins {
id 'org.springframework.boot' version '3.2.5' apply false
id 'io.spring.dependency-management' version '1.1.4' apply false
id 'java'
}
subprojects {
group = 'com.example'
version = '0.0.1-SNAPSHOT'
repositories {
mavenCentral()
}
}
真正启动的 service 模块再单独启用插件,并依赖其他模块。这里 common 模块不需要启用 Spring Boot 插件,只需要被 service 依赖即可。下面展示 service 模块的 build.gradle。
plugins {
id 'org.springframework.boot'
id 'io.spring.dependency-management'
}
dependencies {
implementation project(':common')
implementation 'org.springframework.boot:spring-boot-starter-web'
}
如果 common 模块只需要被依赖,不需要打成可执行 Jar,不要为它启用 Spring Boot 插件,使用 java-library 即可。常见错误是子模块全都在 plugins 里写 id 'org.springframework.boot',结果执行 ./gradlew build 时出现了多个 bootJar 任务,而且部分模块因为没有 mainClass 直接失败。对应解决方式是:在根项目中 apply false,只在启动模块启用。这样既能统一版本管理,又不会污染非应用模块的构建生命周期。
四、构建加速与常见报错处理
Gradle 的优势之一是增量构建和缓存。可以在 gradle.properties 中打开并行构建、配置缓存和按需配置。配置缓存能够跨构建复用任务图,对于大型多模块项目效果明显;并行构建则允许不同模块同时编译。
org.gradle.parallel=true org.gradle.caching=true org.gradle.configureondemand=true
org.gradle.caching=true 开启本地构建缓存,重复执行测试或打包时能跳过未变化任务。org.gradle.configurationondemand=true 在多模块项目中只配置当前执行任务需要的模块,能减少配置时间。注意配置缓存对某些动态读取系统属性的任务可能不友好,遇到结果不一致时应先关闭该项排查。另外在 CI 环境中不建议使用 ./gradlew clean build 而直接使用 ./gradlew build,因为 clean 会破坏增量缓存,使每次构建都从头执行。如果确实需要干净产物,可以在发布阶段单独执行 clean。
依赖冲突是 Spring Boot Gradle 构建中最常见的问题之一。例如同时引入 spring-boot-starter-web 和某个日志实现,可能因 commons-logging 与 slf4j 的桥接重复导致构建或运行时异常。可以在 configurations 中统一排除。
configurations.all {
exclude group: 'commons-logging', module: 'commons-logging'
}
另一个高频错误是插件版本与 Gradle 版本不兼容。Spring Boot 新版本插件通常会提高对 Gradle 最低版本的要求。如果执行 ./gradlew build 时提示找不到 org.springframework.boot 插件中的某个类,先检查 gradle-wrapper.properties 中的 distributionUrl 对应的 Gradle 版本,再对照 Spring Boot 官方文档确认插件支持的 Gradle 范围,通常升级 Gradle wrapper 即可解决。构建失败信息中出现 Could not find org.springframework.boot:spring-boot-gradle-plugin 时,多半是 repositories 中没有配置 mavenCentral 或镜像源被拦截。把仓库配置放到根构建脚本的 subprojects 中,可以让所有子模块共享同一套下载策略,减少这类问题。
Spring BootGradle构建脚本修改时间:2026-11-04 05:02:21