Gradle怎么通过bundle一次引入多个依赖-java教程-PHP中文网

libs.bundles 是 Gradle 8.0+ 中用于声明逻辑关联、版本需对齐的依赖组合的机制，非物理打包；在 libs.versions.toml 的 [bundles] 下用字符串数组引用已定义的 libraries 别名，如 okhttp = ["okhttp", "okhttp-logging", "okhttp-mock"]。

gradle怎么通过bundle一次引入多个依赖

什么是 libs.bundles？

Gradle 8.0+（含 7.6+）支持在 libs.versions.toml 中定义 bundles，它不是“打包多个 JAR”，而是声明一组**逻辑上总是一起用、版本需对齐的依赖项组合**。比如 libs.bundles.okhttp 可以同时包含 okhttp、logging-interceptor 和 mockwebserver，避免漏加或版本错配。

怎么在 toml 文件里定义 bundle

在项目根目录 gradle/libs.versions.toml 中写：

[bundles]
okhttp = ["okhttp", "okhttp-logging", "okhttp-mock"]
retrofit2 = ["retrofit", "converter-gson", "adapter-rxjava3"]

注意：bundle 的 value 是字符串数组，每个元素对应你在 [libraries] 下定义的依赖别名（不是 Maven 坐标）。

你得先确保这些别名已正确定义，例如：

[libraries]
okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version = "4.12.0" }
okhttp-logging = { group = "com.squareup.okhttp3", name = "logging-interceptor", version.ref = "okhttp" }
okhttp-mock = { group = "com.squareup.okhttp3", name = "mockwebserver", version.ref = "okhttp" }
retrofit = { group = "com.squareup.retrofit2", name = "retrofit", version = "2.9.0" }
converter-gson = { group = "com.squareup.retrofit2", name = "converter-gson", version.ref = "retrofit" }
adapter-rxjava3 = { group = "com.squareup.retrofit2", name = "adapter-rxjava3", version.ref = "retrofit" }

version.ref 复用同一版本号，是 bundle 能保持一致的关键
别名命名不能含点（.），否则 Gradle 解析失败；推荐用短横线（-）分隔
bundle 名称本身不带版本，它只是“引用集合”

怎么在 build.gradle(.kts) 中使用 bundle

在模块的 build.gradle.kts（或 build.gradle）中直接写：

Gradle 9.8.0

下载

dependencies {
    implementation(libs.bundles.okhttp)
    implementation(libs.bundles.retrofit2)
}

Gradle 会自动展开成对应的所有依赖项，并正确处理传递依赖和版本冲突。

常见错误现象：

Cannot access 'libs.bundles.xxx': it is public/*package*/ in module → 检查是否在 settings.gradle 启用了预览特性：enableFeaturePreview("VERSION_CATALOGS")
IDE 不提示 bundle 补全 → 确保用的是 Kotlin DSL（.kts），且 Gradle 版本 ≥ 8.0；Groovy DSL 目前不支持自动补全 bundle
编译报错 “Could not resolve …” → bundle 中某个依赖别名拼写错误，或对应 [libraries] 条目缺失