Gradle 中如何在构建时动态获取并强制使用特定传递依赖的版本

详解如何在 build.gradle 中不显式声明、而通过排除策略与解析机制，精准捕获并锁定某依赖项所引入的特定传递依赖版本

今天我们来探讨一个在 Gradle 依赖管理中颇具技巧性的场景：如何在不直接声明的情况下，精准锁定某个传递依赖的特定版本。比如，你明确需要 `group:module:2.0.0` 这个版本，但它是由上游依赖 `my-dependency-1` 间接引入的，而另一个依赖 `my-dependency-2` 却带来了冲突的 `3.0.0` 版本。我们的目标，就是通过构建时的动态约束，让 `2.0.0` 胜出。

在 Gradle 的世界里，“传递依赖”是把双刃剑。它自动帮你拉取依赖链上的所有子依赖，省时省力；可一旦多个上游依赖引入了同一坐标（group:module）的不同版本，麻烦就来了。Gradle 默认会采用一套“最近优先 + 最高版本胜出”的仲裁策略，但这套策略未必符合你的实际业务意图。你心里清楚，必须沿用 `my-dependency-1` 所携带的 `2.0.0`，而不是 `my-dependency-2` 带来的 `3.0.0`。

这时候，直接使用 `force true` 或者 `version { strictly '2.0.0' }` 这类静态硬编码方法就行不通了。为什么？因为它们无法感知到构建过程中，依赖图实际解析出的动态版本。正确的思路，是结合排除（exclude）策略、依赖图解析和构建时动态约束，来实现精准控制。

✅ 推荐方案：排除干扰项 + 利用依赖解析结果隐式锁定

首先得明确一点：Gradle 并没有提供一个直接的 DSL 方法，让你在 `build.gradle` 脚本的配置阶段就能“读取”到传递依赖的最终版本号。像 `configurations.compileClasspath.resolvedConfiguration` 这类对象，在配置阶段是尚未就绪的。不过别担心，我们完全可以通过另一条可靠的路径达成目标。

1. 显式排除冲突的传递依赖

dependencies {
    implementation "my-dependency-1:module:1.0.0" // 自动带入 group:module:2.0.0
    implementation("my-dependency-2:module:1.0.0") {
        exclude group: "group", module: "module" // 阻断其引入的 3.0.0
    }
}

✅ 这个操作的效果非常直接：`my-dependency-1` 所传递的 `group:module:2.0.0` 将成为该坐标的唯一来源；而 `my-dependency-2` 引入该坐标的路径被彻底切断，版本竞争自然也就消失了。

⚠️ 这里有个关键细节：`exclude` 必须写在带括号的闭包形式里（也就是 `implementation(...)` 这种写法），否则语法是无效的。同时，`group` 和 `module` 的名称必须严格匹配，注意大小写。

2. 进阶：通过 resolutionStrategy 强制统一版本（可选增强）

如果你希望约束更加健壮，比如防止未来其他依赖意外引入 `group:module` 的其他版本，可以在 `configurations` 中添加解析策略：

configurations.all {
    resolutionStrategy {
        force "group:module:2.0.0" // 全局强制指定版本
        // 或更安全的写法：仅对特定配置生效
        // force "group:module:2.0.0", configuration: "implementation"
    }
}

⚠️ 需要注意的是，`force` 会覆盖所有来源的版本，适用于你已明确知道 `2.0.0` 是稳定版本的场景。但如果 `2.0.0` 本身是动态生成的（比如 `SNAPSHOT` 版本），那么更稳妥的做法还是以 `exclude` 为主，并在 CI 阶段进行依赖校验。

3. 验证：命令行查看实际解析结果

方案实施后，如何验证是否成功？执行下面的命令，可以清晰地看到最终的依赖解析结果：

./gradlew app:dependencies --configuration releaseRuntimeClasspath | grep "group:module"

在输出中，你应该只能看到 `group:module:2.0.0`，而找不到任何指向 `3.0.0` 的路径。这就表明排除操作成功了。

? 关键注意事项

• 不要在 dependencies 块中尝试调用 resolvedConfiguration：这是一个常见的误区。该对象在配置阶段尚未就绪，强行调用会导致 `NullPointerException` 或返回空集合。
• exclude 是声明式、轻量级且可预测的：与 `force` 相比，`exclude` 不会改变依赖图的整体语义，它只是精准地移除了指定的冲突路径，更符合“最小干预”的工程原则。
• 版本号需与实际发布一致：动手之前，最好去 Ma ven Repository 或 Google’s Ma ven Repo 确认一下，`group:module:2.0.0` 这个版本确实存在且可用。
• JCenter 已弃用：确保你的 `repositories` 配置中已经移除了 `jcenter()`，改用 `ma venCentral()` 或 `google()`（Android Studio 2021.3+ 版本已默认如此配置）。

✅ 总结

说到底，要“程序化获取并锁定某个传递依赖版本”，核心思路不是去“读取”它，而是去“引导”和“约束”整个依赖解析过程。通过 `exclude` 精准切断干扰源，让目标依赖成为该坐标的唯一供给者，是目前最简洁、最可靠、也最符合 Gradle 设计哲学的实践方式。它无需引入任何额外插件，不侵入构建生命周期，并且完全兼容 Android Gradle Plugin 8.0+ 及 Gradle 8.x，堪称企业级项目进行依赖治理的推荐范式。