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

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 块中，定义您的插件。

迁移步骤

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

迁移过程如下：

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

迁移依赖项

在 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" }

建议在目录中依赖项块的命名方式是 kebab-case（例如 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 块目录条目的格式为 kebab-case（例如 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

}

了解更多

要了解配置版本目录的其他选项，请参阅以下资源

版本目录 TOML 文件格式文档介绍了配置目录文件的其他选项。
Now in Android 是我们使用版本目录的示例应用程序。

已知问题

Gradle 版本目录仍在积极开发中。有关尚未支持的内容的更多信息，请参阅已知问题和限制。