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

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 块目录条目中使用连字符命名法（例如 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 版本目录仍处于积极开发中。有关尚不支持内容的更多信息，请参阅已知问题和限制。