如何在 Gradle 版本目录 Version Catalog 中排除依赖项

作者：袖梨 2026-07-12

Gradle 的版本目录（libs.versions.toml）本身不支持直接声明 exclude 规则；排除依赖必须在实际引用依赖的模块（如 build.gradle）中通过 implementation 或 testImplementation 等配置项显式指定。

gradle 的版本目录（`libs.versions.toml`）本身不支持直接声明 `exclude` 规则；排除依赖必须在实际引用依赖的模块（如 `build.gradle`）中通过 `implementation` 或 `testimplementation` 等配置项显式指定。

在使用 Gradle 版本目录（Version Catalog）时，一个常见误区是试图在 libs.versions.toml 文件中为依赖项（如 snakeyaml）直接配置 exclude 语句。例如：

[libraries]snakeyaml = { module = "org.yaml:snakeyaml", version = "2.0" }

⚠️ 这种写法无法规避 snakeyaml-2.0-android.jar 的错误解析——因为 Gradle 版本目录的设计初衷是统一管理坐标与版本，而非控制依赖图的解析行为。它本质上是一个“只读清单”，不承载配置逻辑（如 exclude group: 'com.android'、force、transitive = false 等）。

✅ 正确做法是在实际应用该依赖的 build.gradle（或 build.gradle.kts）中，于依赖声明处添加排除规则：

Groovy DSL 示例（build.gradle）：

dependencies {    implementation(libs.snakeyaml) {        exclude group: 'com.android', module: 'android' // 排除疑似冲突的 android.jar 变体        // 或更精准地排除特定 classifier（如果存在）        // exclude group: 'org.yaml', module: 'snakeyaml', classifier: 'android'    }    testImplementation(libs.snakeyaml) {        exclude group: 'com.android', module: 'android'    }}

Kotlin DSL 示例（build.gradle.kts）：

dependencies {    implementation(libs.snakeyaml) {        exclude(group = "com.android", module = "android")    }    testImplementation(libs.snakeyaml) {        exclude(group = "com.android", module = "android")    }}

? 为什么会出现 snakeyaml-2.0-android.jar 错误？
Maven 仓库中某些 snakeyaml 发布版本（尤其是较新版本）可能附带了多 JAR 构建产物（如 classifier = "android"），而 Gradle 在解析传递依赖时若未明确约束，可能尝试拉取不存在的变体（如 *-android.jar）。此时排除该 classifier 或对应 group/module 即可绕过此问题。

? 进阶建议：结合 Platform 使用
若需对一组相关依赖（如 YAML 生态、Spring Boot Starter）统一管理版本 + 共享排除策略，推荐搭配 platform 或 enforcedPlatform：

// 在 dependencyManagement 块中定义平台dependencies {    implementation(platform("org.yaml:snakeyaml:2.0"))    implementation("org.yaml:snakeyaml") // 自动继承版本，且可单独 exclude}

? 总结