本文详解在多模块 Gradle 项目中，当库（如 library A）声明了特定版本的传递依赖（如 library B-v2），但宿主项目已引入冲突版本（library B-v1）时，如何通过 strictly 约束或 force 策略确保该库始终绑定其自有依赖版本。
本文详解在多模块 gradle 项目中，当库（如 library a）声明了特定版本的传递依赖（如 library b-v2），但宿主项目已引入冲突版本（library b-v1）时，如何通过 `strictly` 约束或 `force` 策略确保该库始终绑定其自有依赖版本。
在 Gradle 的依赖解析机制中，默认采用“最高版本胜出”（Highest Version Wins）策略：只要任意路径（直接声明、传递依赖或平台约束）请求了某个依赖的某个版本，Gradle 就会从所有候选版本中选择语义化版本号最高的一个作为最终解析结果。这意味着，即使 library-A 在其 build.gradle 中通过 api("group:name:library-B:v2") 明确指定了 v2，一旦主项目也声明了 implementation("group:name:library-B:v1")（或通过其他库间接引入 v1），而 v2 library-A 的字节码实际运行在 v1 的 API 上，极易引发 NoSuchMethodError 或行为不一致等运行时问题。
要打破这一默认行为，关键在于显式声明版本偏好并提升其解析优先级。Gradle 提供两种主流、安全且推荐的方式：
✅ 方式一：使用 strictly 版本约束（推荐，精准可控）
适用于你希望精确锁定 library-B 的某一个版本（如 v2）供整个项目统一使用的场景。它通过富版本声明（Rich Versions）实现，具有高可读性和模块化优势：
// build.gradle.kts（主项目）
dependencies {
implementation("com.example:library-A:1.0.0") // 依赖 library-B:v2
implementation("com.example:library-C:2.1.0") // 可能依赖 library-B:v1
// 强制所有对 library-B 的解析必须严格匹配 v2
implementation("com.example:library-B") {
version {
strictly("2.0.0") // ← 关键：v2 被设为不可妥协的唯一合法版本
}
}
}✅ 优势：
- 作用范围明确（仅影响
library-B），不影响其他依赖； - 与 Gradle 的依赖图验证兼容，构建失败时会清晰报错（如存在无法满足的
strictly约束）； - 支持
prefer、reject等组合策略，灵活性强。
✅ 方式二：使用 resolutionStrategy.force()（全局强制）
适用于需快速统一多个依赖版本，或处理复杂传递依赖链的场景。它在配置层面“覆盖”所有匹配模块的版本选择：
// build.gradle.kts（主项目）
configurations.all {
resolutionStrategy {
force("com.example:library-B:2.0.0") // ← 强制所有 configuration 使用 v2
// 可叠加多条 force，例如：
// force("org.slf4j:slf4j-api:2.0.9")
// force("com.google.guava:guava:32.1.3-jre")
}
}⚠️ 注意事项：
-
force是全局生效的，可能意外覆盖其他库的兼容性预期，请谨慎评估； - 它不参与版本冲突检测逻辑，若强制版本与某些库的
requires元数据冲突（如 Java 版本不兼容），可能在运行时暴露问题； - 建议配合
--scan或./gradlew dependencies --configuration runtimeClasspath验证实际解析结果。
❌ 不推荐的方案说明
-
修改
library-A的依赖声明为implementation而非api：虽可切断传递，但会破坏library-A的公共 API 合约（若其 API 类引用了library-B类型），导致主项目编译失败； -
自定义 ClassLoader 隔离：技术上可行，但严重违背模块化设计原则，增加维护成本与调试难度，且无法解决静态链接（如
static final字段）、JNI 或反射等场景； -
Java Module System（JPMS）隔离：需全面迁移至模块化，并要求所有依赖提供
module-info.class，当前生态支持度有限，不适合作为通用解法。
总结
| 场景 | 推荐方案 | 关键代码 |
|---|---|---|
| 精准控制单个依赖版本，强调可维护性与可读性 |
strictly 约束 |
implementation("g:a") { version { strictly("x.y.z") } } |
| 快速统一多个依赖版本，或处理遗留复杂依赖树 | resolutionStrategy.force() |
configurations.all { resolutionStrategy { force("g:a:x.y.z") } } |
最终，应以 最小作用域、最大确定性 为原则选择方案。绝大多数情况下，strictly 是更现代、更健壮的选择。务必在变更后执行 ./gradlew build --refresh-dependencies 并检查 dependencies 报告，确认 library-B 的解析版本已稳定为预期值（如 2.0.0），再投入测试与发布流程。
