TOML依赖管理

在 Android 项目开发中，统一管理插件版本和第三方库依赖十分重要，Gradle 提供的 Version Catalog (TOML) 方便我们通过libs.versions.toml文件集中管理所有依赖和插件的版本。

TOML 文件在项目根目录的 gradle/libs.versions.toml 里，如果文件视图中选择 Android 的话也很容易在 Gradle Scripts 里找到。

古老硬编码写法

喂，这样明明很方便的好吧

在早期的 Gradle 配置中，我们通常在 build.gradle.kts 文件中直接声明插件和依赖库。不过现在新版的 Android Studio 刚创建项目后应该也看不见它的身影了。在一些教程里为了方便，依赖引用声明常常直接导入。

——历史的博物馆——

根项目的 build.gradle.kts

1
2
3
4
plugins { 
    id("com.android.application") version "9.2.1" apply false  
    id("org.jetbrains.kotlin.plugin.compose") version "2.2.10" apply false 
}

模块内应用与依赖库引用 build.gradle.kts

1
2
3
4
5
6
7
plugins {  
   id("com.android.application") 
   id("org.jetbrains.kotlin.plugin.compose")  
}
dependencies{
    implementation("androidx.activity:activity-compose:1.13.0")
}

使用TOML统一管理

TOML 文件最常用的三个表是[versions] 、[libraries] 、 [plugins] 。

分别用来定义版本号、声明具体的第三方库、管理 Gradle 插件。

插件管理

对于插件，我们可以直接在 [plugins] 中定义插件：

1
2
[plugins]
android = "com.android.application:9.2.1"

然后我们就可以 build.gradle.kts 中通过使用 alias 引用 TOML 中的插件啦。

1
alias(libs.plugins.android.application) apply false

当然，为了分离版本信息，方便集中统一版本，我们可以使用内联表的方式，包裹键值对，用 version.ref 引用 version 表里的版本变量。

1
2
3
4
[versions]
agp = "9.2.1"
[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }

这样之后，版本号被集中管理起来，就便于统一升级了。

依赖管理

依赖同理，如下：

1
2
3
4
5
6
7
8
[versions]
activityCompose = "1.13.0"
[libraries]
androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
dependencies {
        implementation(libs.androidx.activity.compose)
        //在模块中引用时，Gradle会自动将TOML中的连字符（-）转换为Kotlin中的点（.）
}

为了进一步简化依赖引用，我们还可以在 toml 文件里定义一个数组用来装依赖变量名，将多个相关的依赖组合在一起。

1
2
3
[bundles]
androidx = ["androidx-core-ktx","androidx-lifecycle-runtime-ktx"]
#你在[libraries]里定义的变量

然后在代码里就能一次性引入：

1
implementation(libs.bundles.androidx)

使用BOM进行版本对齐

BOM 即 Bill Of Materials 对于像 Jetpack Compose 这样的大型库集合， Google 提供了 BOM 来统一管理版本。它提供一个清单版本，以实现库的版本的自动对齐。你只需引入 BOM ，就不用手动指定每个库的版本。 在 libs.versions.toml 中定义 BOM ：

1
2
3
4
[versions]
composeBom = "2026.02.01"
[libraries]
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }

在build.gradle.kts中应用 BOM

1
implementation(platform(libs.androidx.compose.bom))

当然，如果需要在debug或androidTest中也使用 BOM ，可以把 BOM 单独抽出来存个变量

1
2
3
4
val composeBom = platform(libs.androidx.compose.bom)
implementation(composeBom)
androidTestImplementation(composeBom)
debugImplementation(composeBom)

哦对了，不要忘了 Sync now ( ∩_∩ )