使用 libs.versions.toml
这是 Gradle 在大约 8.x 版本左右开始支持的依赖管理方案（起始时间记不太清了，也可能更早），至少在 8.x 版本左右（或者说最近据我个人的观察）开始变得常见、稳定、流行了起来。
首先，你可以前往 官方文档 来了解 Version Catalog 详细的使用方式，而这篇小文章就以上手应用的方式简单为你介绍一下。
配置文件
首先，在你 Gradle 项目的根目录，在 gradle 目录中创建一个 toml 文件 libs.versions.toml:
根目录
|
\- gradle
| \- libs.versions.toml <==== 在这里
|
\- src
\- build.gradle.kts
\- settings.gradle.kts
\- 其他什么别的东西
文件内容大概是这样样子的：
[versions]
kotlin = "2.0.0"
kotlinx-coroutines = "1.8.1"
log4j = "2.23.1"
ksp = "2.0.0-1.0.22"
[libraries]
# jetbrains-annotation
jetbrains-annotations = "org.jetbrains:annotations:24.1.0"
# kotlinx-coroutines
kotlinx-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }
kotlinx-coroutines-reactor = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-reactor", version.ref = "kotlinx-coroutines" }
kotlinx-coroutines-debug = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-debug", version.ref = "kotlinx-coroutines" }
kotlinx-coroutines-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "kotlinx-coroutines" }
# log4j
log4j-api = { group = "org.apache.logging.log4j:log4j-api", version.ref = "log4j" }
log4j-core = { group = "org.apache.logging.log4j:log4j-core", version.ref = "log4j" }
log4j-slf4j2 = { module = "org.apache.logging.log4j:log4j-slf4j2-impl", version.ref = "log4j" }
[bundles]
log4j2 = ["log4j-api", "log4j-core", "log4j-slf4j2"]
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
可以看到配置文件中分了那么几段，它们分别代表着不同的作用。
[versions]
其实这几个分段看名字也能大概猜到它们的意思。
[versions] 即为定义某个东西的版本的，比如：
[versions]
kotlin = "2.0.0"
则代表定义了一个叫 kotlin 的东西的版本为 2.0.0。
版本可以在后续的其他几个分类中引用使用，或者在配置文件里使用 libs.versions.xxx.get() 直接获取。
具体使用先按下不表，我们稍后再谈。
[libraries]
[libraries] 便是定义依赖的地方了。它有很多写法，比如直接使用字符串表示完整的依赖：
[libraries]
jetbrains-annotations = "org.jetbrains:annotations:24.1.0"
或者使用 group、name、version 完整的定义依赖坐标中的每一个部分：
[libraries]
kotlinx-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }
kotlinx-coroutines-reactor = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-reactor", version.ref = "kotlinx-coroutines" }
又或者使用 module 和 version 将坐标与版本的信息分离开来：
[libraries]
log4j-api = { group = "org.apache.logging.log4j:log4j-api", version.ref = "log4j" }
log4j-core = { group = "org.apache.logging.log4j:log4j-core", version.ref = "log4j" }
log4j-slf4j2 = { module = "org.apache.logging.log4j:log4j-slf4j2-impl", version.ref = "log4j" }
细心的你也许发现了，如果使用 version.ref 而不是 version，那便是对上面 [versions] 中定义的版本进行了一个引用。
当然，version 或 version.ref 也是可以省略的，这可以用于在配合使用其他 bom 或者别的什么来管理版本的时候使用，比如在配合 Spring Boot 时。
[bundles]
如果你在每一个地方都需要重复引用相同的多个 [libraries] 中的内容，那么不妨将它们打包在一起，一次引用它们全部。[bundles] 便可用于将 [libraries] 中定义的一个或多个依赖包在一起。
[bundles]
log4j2 = ["log4j-api", "log4j-core", "log4j-slf4j2"]
[plugins]
[plugins] 也可以使用 version 或 version.ref，并使用 id 来表示插件的ID信息。
它主要使用在配置 plugins {} 的时候。
[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
使用
配置完成后，刷新/初始化你的Gradle，他会自动将上面的信息编译，并可以让你在配置脚本中直接通过 libs 访问到它们。
versions
虽然 versions 通常是用来给其他部分做引用的，但是你依旧可以直接使用它们。
比如在 build.gradle.kts 中输出 kotlin 的版本信息的日志：
// 其他省略...
logger.info("Kotlin version = {}", libs.versions.kotlin.get())
可以看到，我们通过 libs.versions 访问到了其中的 kotlin，并使用 get() 得到了它的字符串值。
libraries
接下来就是比较常见的 libraries 了。在 build.gradle.kts 中的 dependencies 中引入依赖的时候，不再使用字符串，而是直接用类型安全的 libs 所提供的属性即可。
// 其他省略...
dependencies {
compileOnly(libs.jetbrains.annotations)
implementation(libs.kotlinx.coroutines.core)
testImplementation(libs.kotlinx.coroutines.test)
}
细心的你可能又发现了，明明你定义的是 jetbrains-annotations，怎么到这儿， - 就变成 . 了？
是的，从 libs.versions.toml 编译过来后就会将分段的命名使用 . 作为衔接。
你可以在 这里 看到官方对这种规则的详细描述。
bundles
一个“包体”的使用方式其实跟 libraries 差不多，只不过多了一层 bundles。
// 其他省略...
dependencies {
// ...
implementation(libs.bundles.log4j2)
}
1
2
3
4
5
6
plugins
plugins 只能在 plugins {} 中使用，并需要通过 alias 来引用它们。
plugins {
// ...
alias(libs.plugins.ksp)
}
在 buildSrc 中使用
不过，gradle/libs.versions.toml 默认情况下并不能在 buildSrc 目录中的代码中使用，不过好在想要能够使用也很简单。
在 buildSrc 目录下创建一个 settings.gradle.kts 文件，大概结构如下：
根目录
|
\- buildSrc
| \- src
| \- build.gradle.kts
| \- settings.gradle.kts <==== 在这里
\- gradle
| \- libs.versions.toml
|
\- src
\- build.gradle.kts
\- settings.gradle.kts
\- 其他什么别的东西
然后在其中加上：
dependencyResolutionManagement {
versionCatalogs {
create("libs") {
from(files("../gradle/libs.versions.toml"))
}
}
}
