Gradle 7.4+ 中统一管理依赖版本的首选方案是使用 libs.versions.toml：在根项目 gradle/ 目录下创建该文件，定义 [versions]、[libraries] 和可选 [bundles] 三部分；在 settings.gradle.kts 中启用 VERSION_CATALOGS；子模块通过 libs.xxx 引用，修改版本只需更新 toml 中的 [versions] 块。
在 Gradle 7.4+ 中，Version Catalogs（版本目录）是官方推荐的依赖版本集中管理机制，它通过 libs.versions.toml 文件声明所有依赖坐标和版本，让模块间共享统一版本、避免硬编码、提升可维护性。关键在于正确配置 TOML 文件 + 在 build.gradle 中按约定引用。
1. 创建并配置 gradle/libs.versions.toml
在项目根目录的 gradle/ 文件夹下新建 libs.versions.toml，内容结构清晰分三块：
-
[versions]：定义版本别名（如
junit = "5.10.0"） -
[libraries]：定义依赖别名，用
{version = "junit"}引用已声明的版本 -
[bundles]（可选）：组合多个 library 别名，方便一键引入（如
test包含 junit + mockito）
示例：
[versions]
kotlin = "1.9.20"
junit = "5.10.0"
retrofit = "2.9.0"
[libraries]
kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }
junit-junit5 = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" }
retrofit-core = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
[bundles]
test = ["junit-junit5"]
2. 在 settings.gradle(.kts) 中启用 Version Catalogs
必须显式声明启用，否则 Gradle 不识别 libs 命名空间：
立即学习“Java免费学习笔记（深入）”；
- 如果是 Groovy：
enableFeaturePreview("VERSION_CATALOGS") - 如果是 Kotlin：
enableFeaturePreview("VERSION_CATALOGS")（写在settings.gradle.kts顶部）
Gradle 8.0+ 默认启用，但显式声明更稳妥。
3. 在模块的 build.gradle 中使用 libs
无需额外插件，直接通过 libs 访问声明的依赖：
- Groovy 写法：
implementation libs.kotlin.stdlib（层级用点号分隔） - Kotlin DSL 写法：
implementation(libs.kotlin.stdlib) - 引用 bundle：
testImplementation libs.bundles.test - 单独取版本号：
libs.versions.junit.get()（Kotlin DSL）或libs.versions.junit（Groovy）
4. 高级技巧与注意事项
- 支持多 catalog：可定义多个 TOML 文件（如
libs2.versions.toml），并在settings.gradle中用dependencyResolutionManagement { versionCatalogs { create("libs2") { from(files("gradle/libs2.versions.toml")) } } } - 版本覆盖：在子项目中可通过
libs.versions.junit.version.set("5.11.0")动态覆盖（Kotlin DSL） - IDE 支持：IntelliJ 2022.3+ 原生支持自动补全
libs.xxx，悬停查看坐标和版本 - 不支持动态版本（如
1.2.+）：TOML 要求明确版本字符串，动态解析需改用platform或 BOM
