Gradle如何升级到libs.versions.toml

官方参考文档 docs.gradle.org/current/use…

在文章最后有重点教你怎么引用私有库的插件,这个很多人不知道

一：谈谈语法

在 Android 项目中，libs.versions.toml 文件是 Gradle Version Catalogs 的核心，它提供了一种集中管理项目依赖版本的方式。它主要包含以下四个部分，每部分都有其特定的写法形式：

---

1. [versions] 区块

这个区块用于定义项目中使用的各种库和插件的版本号。它的写法非常直接，通常是键值对的形式，键是版本的别名，值是具体的版本字符串。

写法形式：

[versions]
# 直接指定版本号
kotlin = "1.9.0"
agp = "8.5.0"
androidxComposeBom = "2024.04.01"

# 也可以是其他类型的数据，例如整数
minSdk = 24
targetSdk = 34

---

2. [libraries] 区块

这个区块用于定义项目中的依赖库。你可以通过不同的方式指定库的 GAV (Group, Artifact, Version) 坐标。

写法形式：

a. 引用 [versions] 中的版本 (推荐)

这是最常见且推荐的方式，通过 version.ref 属性引用 [versions] 区块中定义的版本。

[libraries]
# 使用 version.ref 引用版本
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
androidx-appcompat = { module = "androidx.appcompat:appcompat", version.ref = "appcompat" }

• group: 依赖的组 ID。
• name: 依赖的 artifact ID。
• version.ref: 引用 [versions] 中定义的版本别名。
• module: 结合 group 和 name 的简写形式，例如 "group:name"。

注意：上面两种写法都可以

b. 直接指定版本号

你也可以直接在 [libraries] 区块中指定每个库的版本，但这种方式不推荐，因为它失去了集中管理版本的优势。

[libraries]
# 直接指定版本号（不推荐）
junit = { group = "junit", name = "junit", version = "4.13.2" }

c. 声明富版本 (Rich Version)

对于更复杂的版本需求，例如指定严格版本、首选版本或拒绝某些版本，可以使用富版本声明。

[versions]
myLib = { require = "1.2.0", prefer = "1.2.1", reject = ["1.3.0"] }

[libraries]
my-lib = { group = "com.example", name = "my-lib", version.ref = "myLib" }

• require: 必须使用的版本。
• prefer: 首选的版本。
• strictly: 严格使用的版本，不允许其他版本。
• reject: 拒绝使用的版本列表。
• rejectAll: 拒绝所有版本（通常用于测试）。

---

3. [bundles] 区块

这个区块用于将多个相关的库打包成一个“捆绑包”，方便在 build.gradle 文件中一次性引入。

写法形式：

[libraries]
# ... 其他库声明
junit = { group = "junit", name = "junit", version.ref = "junit" }
androidx-test-ext-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }
androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }

[bundles]
# 定义一个测试捆绑包
android-testing = ["junit", "androidx-test-ext-junit", "androidx-espresso-core"]

在 build.gradle 中可以通过 implementation(libs.bundles.androidTesting) 引入。

---

4. [plugins] 区块

这个区块用于定义项目中使用的 Gradle 插件。

写法形式：

[plugins]
# 引用 [versions] 中的版本
androidApplication = { id = "com.android.application", version.ref = "agp" }
kotlinAndroid = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

# 也可以直接指定版本（不推荐）
detekt = { id = "io.gitlab.arturbosch.detekt", version = "1.23.0" }

• id: 插件的 ID。
• version.ref: 引用 [versions] 中定义的版本别名。
• version: 直接指定插件版本。

---

总结一下：

libs.versions.toml 的写法形式主要围绕着这四个核心区块展开，并且强烈推荐使用 [versions] 区块来集中管理版本，然后通过 version.ref 在 [libraries] 和 [plugins] 中引用，这样可以大大提高依赖管理的清晰度和可维护性。

二、谈谈升级步骤

首先，确保你的 Gradle 版本支持 Version Catalogs。Version Catalogs 是从 Gradle 7.0 版本开始引入的，并在 7.4 版本中成为稳定功能

大体上就是setting.gradle已经已经变成了配置包与插件服务器地址的地方，项目里的build.gradle变成了配置插件声明的地方

1.创建 libs.versions.toml 文件

在你的项目根目录下的 gradle 文件夹中创建一个名为 libs.versions.toml 的文件。如果 gradle 文件夹不存在，你需要先创建它。

你的项目结构看起来会像这样：

your-project/
├── gradle/
│   └── libs.versions.toml  <-- 创建这个文件
└── build.gradle
└── settings.gradle
└── ...

2. 启用 Version Catalogs

在你的项目根目录下的 settings.gradle (或 settings.gradle.kts) 文件中，添加以下代码来启用 Version Catalogs：所有的插件和包的引用地址都要写在这里了

// settings.gradle
enableFeaturePreview("VERSION_CATALOGS") // 如果你使用的是 Gradle 7.0-7.3 版本，需要这行
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
    versionCatalogs {
        create("libs") { // "libs" 是你的 catalog 名称，对应 libs.versions.toml
            from(files("gradle/libs.versions.toml"))
        }
    }
}

注意： 从 Gradle 7.4 版本开始，enableFeaturePreview("VERSION_CATALOGS") 这一行就不再需要了，因为 Version Catalogs 已成为稳定功能。如果你使用的是 7.4 或更高版本，可以移除它。

3.在 build.gradle 文件中使用 Version Catalogs

现在，你可以在你的 build.gradle (或 build.gradle.kts) 文件中替换旧的依赖声明和插件声明。

更新 build.gradle (模块级别，例如 app/build.gradle):

// app/build.gradle

// 移除 ext {} 中的版本定义

dependencies {
    // 使用 libs.your-library-alias
    implementation(libs.kotlin.stdlib) // 注意这里会根据你的 TOML 文件中的 alias 自动生成
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.appcompat)

    // 如果你有 bundles
    // implementation(libs.bundles.androidTesting)
}

更新 build.gradle (项目级别):

// build.gradle (project level)
plugins {
    // 使用 libs.plugins.yourPluginAlias
    alias(libs.plugins.androidApplication) apply false
    alias(libs.plugins.kotlinAndroid) apply false
}

注意：

• libs 是你在 settings.gradle 中 create("libs") 定义的 catalog 名称。
• libs.kotlin.stdlib 中的 kotlin.stdlib 是根据 libs.versions.toml 中[libraries] 下的 kotlin-stdlib 自动生成的。Gradle 会将 . 替换为 -，所以如果你在 TOML 中写的是 some-library，在 Gradle 中就是 libs.some.library。

三、如何配置私有库的插件！！

1、在toml里先定义插件

插件名字：com.xiaojinzi.component.plugin

2、在setting.gradle里进行配置，如图：

完成，按照这个设置就可以