将 build 迁移到版本目录

借助 Gradle 版本目录,您能够以可扩容的方式添加和维护依赖项和插件。使用 Gradle 版本目录,您可以在拥有多个模块时更轻松地管理依赖项和插件。您不必对各个 build 文件中的依赖项名称和版本进行硬编码,也不必在每次需要升级依赖项时都更新每个条目,而是可以创建一个包含依赖项的中央版本目录,各种模块可在 Android Studio 协助下以类型安全的方式引用该目录。

本页介绍了有关将 Android 应用迁移到版本目录的基本信息。如需了解详情,请参阅添加 build 依赖项和 Gradle 文档。

创建版本目录文件

首先创建一个版本目录文件。在根项目的 gradle 文件夹中,创建一个名为 libs.versions.toml 的文件。Gradle 默认会在 libs.versions.toml 文件中查找目录,因此我们建议使用此默认名称。

libs.versions.toml 文件中,添加以下部分:

[versions]

[libraries]

[plugins]

这些部分的使用方式如下:

  • versions 代码块中,定义用于保存依赖项和插件版本的变量。您可以在后续代码块(librariesplugins 代码块)中使用这些变量。
  • libraries 代码块中,定义依赖项。
  • plugins 代码块中,定义插件。

迁移步骤

我们建议您按照所列顺序执行这些步骤。build 可以同时使用 build 脚本和目录中的依赖项和插件,因此请花些时间单独迁移依赖项和插件。

迁移过程如下:

  1. 将新条目添加到目录。
  2. 同步您的 Android 项目。
  3. 将以前的字符串声明替换为目录类型安全访问器。

迁移依赖项

libs.versions.toml 文件的 versionslibraries 部分,为每个依赖项添加一个条目。同步您的项目,然后将 build 文件中的声明替换为相应的目录名称。

以下代码段展示了移除依赖项之前的 build.gradle.kts 文件:

Kotlin

dependencies {
    implementation("androidx.core:core-ktx:1.9.0")

}

Groovy

dependencies {
    implementation 'androidx.core:core-ktx:1.9.0'

}

以下代码段展示了如何在版本目录文件中定义依赖项:

[versions]
ktx = "1.9.0"

[libraries]
androidx-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }

在为目录中的依赖项块命名时建议采用 kebab case(例如 androidx-ktx),以便在 build 文件中获得更好的代码补全帮助

在需要此依赖项的每个模块的 build.gradle.kts 文件中,按照您在 TOML 文件中定义的名称定义依赖项。

Kotlin

dependencies {
   implementation(libs.androidx.ktx)

}

Groovy

dependencies {
   implementation libs.androidx.ktx

}

迁移插件

libs.versions.toml 文件的版本和插件部分,为每个插件添加一个条目。同步您的项目,然后将 build 文件中 plugins{} 代码块内的声明替换为相应的目录名称。

以下代码段展示了移除插件之前的 build.gradle.kts 文件:

Kotlin

// Top-level `build.gradle.kts` file
plugins {
   id("com.android.application") version "7.4.1" apply false

}

// Module-level `build.gradle.kts` file
plugins {
   id("com.android.application")

}

Groovy

// Top-level `build.gradle` file
plugins {
   id 'com.android.application' version '7.4.1' apply false

}

// Module-level `build.gradle` file
plugins {
   id 'com.android.application'

}

以下代码段展示了如何在版本目录文件中定义插件:

[versions]
androidGradlePlugin = "7.4.1"

[plugins]
android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }

与依赖项一样,对于 plugins 代码块目录条目,建议使用 kebab case(例如 android-application)格式,以便在 build 文件中获得更好的代码补全帮助

以下代码展示了如何在顶级和模块级 build.gradle.kts 文件中定义 com.android.application 插件。对于来自版本目录文件的插件,请使用 alias;对于并非来自版本目录文件的插件(例如惯例插件),请使用 id

Kotlin

// Top-level build.gradle.kts
plugins {
   alias(libs.plugins.android.application) apply false

}

// module build.gradle.kts
plugins {
   alias(libs.plugins.android.application)

}

Groovy

// Top-level build.gradle
plugins {
   alias libs.plugins.android.application apply false

}

// module build.gradle
plugins {
   alias libs.plugins.android.application

}

了解详情

如需了解用于配置版本目录的其他选项,请参阅以下资源:

已知问题

Gradle 版本目录仍处于积极开发阶段。如需详细了解哪些功能尚不受支持,请参阅已知问题和限制