将您的构建迁移到版本目录

Gradle 版本目录让您能够以可扩展的方式添加和维护依赖项和插件。当您拥有多个模块时，使用 Gradle 版本目录可以更轻松地管理依赖项和插件。您可以创建一个集中的依赖项版本目录，各种模块可以在 Android Studio 的帮助下以类型安全的方式引用它，而无需在各个构建文件中硬编码依赖项名称和版本并在需要升级依赖项时更新每个条目。

本页面提供了将 Android 应用迁移到版本目录的基本信息。要了解更多信息，请参阅添加构建依赖项和 Gradle 文档。

创建版本目录文件

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

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

[versions]

[libraries]

[plugins]

这些部分的用法如下

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

迁移步骤

我们建议您按照所列顺序执行这些步骤。构建可以同时从构建脚本和目录中消耗依赖项和插件，因此请花时间逐个迁移您的依赖项和插件。

迁移过程如下

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

迁移依赖项

在 libs.versions.toml 文件的 versions 和 libraries 部分为每个依赖项添加一个条目。同步您的项目，然后将其在构建文件中的声明替换为它们的目录名称。

此代码片段显示了移除依赖项之前的 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" }

在目录中，依赖项块的推荐命名方式是烤串命名法（例如 androidx-ktx），以便在您的构建文件中获得更好的代码补全辅助。

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

Kotlin

dependencies {
   implementation(libs.androidx.ktx)

}

Groovy

dependencies {
   implementation libs.androidx.ktx

}

迁移插件

在 libs.versions.toml 文件的 versions 和 plugins 部分为每个插件添加一个条目。同步您的项目，然后将其在构建文件中的 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 版本目录仍在积极开发中。有关尚未支持功能的更多信息，请参阅已知问题和限制。