推荐使用 libs.versions.toml 统一管理依赖版本，通过声明式版本目录实现集中控制、ide友好补全；其次可复用 spring boot 等官方 bom 或 io.spring.dependency-management 插件；避免使用 buildsrc 或 gradle.properties 等非类型安全方式。
Gradle 项目中统一管理第三方依赖版本，核心是把版本号从各处分散的 dependencies 块里抽出来，集中控制、一处修改、全局生效。不靠硬编码或手动改每个模块，而是用官方支持、IDE友好、多模块天然适配的机制。
用 libs.versions.toml（推荐首选）
这是 Gradle 7.0+ 官方主推的声明式版本目录方案，稳定、类型安全、自动补全支持好，适合绝大多数新老项目。
- 在项目根目录下创建
gradle/libs.versions.toml文件 - 在里面定义版本别名和依赖坐标，例如：
[versions]
springBoot = "3.3.2"
junit = "5.10.2"
retrofit = "2.9.0"
[libraries]
spring-web = { group = "org.springframework.boot", name = "spring-boot-starter-web", version.ref = "springBoot" }
junit-api = { group = "org.junit.jupiter", name = "junit-jupiter-api", version.ref = "junit" }
retrofit-core = { group = "com.squareup.retrofit2", name = "retrofit", version.ref = "retrofit" }
[bundles]
test = ["junit-api", "junit-engine"]
- 在
settings.gradle.kts或settings.gradle中启用特性（Gradle 8.0+ 可省略）：
enableFeaturePreview("VERSION_CATALOGS")
- 在任意模块的
build.gradle.kts中直接引用：
dependencies {
implementation(libs.spring.web)
testImplementation(libs.bundles.test)
}
修改版本只需改 toml 里的 [versions]，所有模块自动同步，IDE 支持代码补全和跳转。
用 Spring Boot BOM 或其他官方 BOM
如果你用的是 Spring Boot、Spring Cloud、Micrometer 等生态，直接复用它们提供的 BOM（物料清单），比自己维护更省心、更兼容。
- 在
dependencies块中引入平台（platform）：
dependencies {
implementation platform("org.springframework.boot:spring-boot-dependencies:3.3.2")
implementation "org.springframework.boot:spring-boot-starter-web"
implementation "org.springframework.boot:spring-boot-starter-data-jpa"
}
BOM 内部已声明各组件的匹配版本，Gradle 会自动对齐，避免手动指定每个库的版本，也天然解决传递依赖冲突。
用 io.spring.dependency-management 插件（兼容旧项目）
适用于 Gradle 6.x 或需要与 Maven pom.xml 风格保持一致的老项目，尤其适合已有 Spring 生态但暂未升级到新版 Gradle 的场景。
- 在根项目的
build.gradle中应用插件并声明依赖管理：
plugins {
id "io.spring.dependency-management" version "1.1.2""
dependencyManagement {
imports {
mavenBom "org.springframework.boot:spring-boot-dependencies:3.3.2"
}
dependencies {
dependency "com.google.guava:guava:33.2.0-jre"
dependency "org.apache.commons:commons-lang3:3.14.0"
}
}
- 子模块中只写坐标，不写版本：
dependencies {
implementation "org.springframework.boot:spring-boot-starter-web"
implementation "com.google.guava:guava"
}
插件会按优先级：BOM > 显式 dependencyManagement > 模块内声明，自动注入版本。
避免用 buildSrc 或 ext 常量（不推荐）
虽然 buildSrc 或 ext 可以定义字符串常量，但缺乏类型检查、IDE 不识别、无法约束依赖组合、升级时易漏改，属于过渡方案而非优雅解法。Gradle 官方已明确建议迁移到 Version Catalog。
- 不要在
gradle.properties里写spring.version=3.3.2再用${spring.version}拼接 - 不要在
buildSrc/src/main/groovy/Constants.groovy里维护一堆静态字段 - 这些方式无法享受依赖解析校验、BOM 兼容性检查、IDE 补全等现代能力
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
