将 build 迁移到版本目录

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

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

创建版本目录文件

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

在 libs.versions.toml 文件中，添加以下部分：

[versions]

[libraries]

[plugins]

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

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

迁移步骤

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

迁移过程如下：

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

迁移依赖项

在 libs.versions.toml 文件的 versions 和 libraries 部分，为每个依赖项添加一个条目。同步您的项目，然后将 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.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 块目录建议的格式设置 即为烤肉串（如 android-application） 代码补全帮助 生成代码

以下代码展示了如何在顶级和模块级 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 版本目录仍处于积极开发阶段。如需详细了解哪些功能尚不受支持，请参阅已知问题和限制。