2. 依赖冲突：如何定位和解决 Transitive Dependency 冲突

依赖冲突，说白了就是你的项目里，同一个库出现了不同的版本。Gradle 不是傻子，它通常会自动选择最高版本，但事情没这么简单。特别是当你引入了第三方 SDK 或者公司内部的基础库，它们内部又依赖了其他东西——这就是所谓的传递依赖（transitive dependency）。

我在项目中遇到过好几次，比如升级了一个网络库，结果运行时直接崩了，日志提示某个类的方法找不到。排查了一圈，发现是另一个库内部依赖了老版本的 OkHttp。这就是典型的传递依赖冲突。

2.1 先搞清楚：依赖冲突到底长什么样？

先看一个典型的错误信息：

Program type already present: com.squareup.okhttp3.OkHttpClient$Builder

或者更常见的：

Conflict with dependency 'com.squareup.okhttp3:okhttp' in project ':app'.
Resolved versions for app (4.9.3) and test app (4.9.2) differ.

这些都是 Gradle 在编译期或者构建时就报出来的。但最讨厌的是那种——编译通过了，打包也没问题，一跑就崩。嗯，这往往是因为两个版本的方法签名不一致，运行时找不到对应的方法。

2.2 定位冲突：我用过最有效的三板斧

2.2.1 第一板斧：跑 Gradle 命令看依赖树

这是我个人习惯的第一反应。直接在 Android Studio 的 Terminal 里敲：

./gradlew :app:dependencies --configuration releaseRuntimeClasspath

如果只关心某个特定的 dependency，可以用：

./gradlew :app:dependencyInsight --dependency okhttp --configuration releaseRuntimeClasspath

这个命令会告诉你，到底是谁把 OkHttp 拉进来的，以及 Gradle 最终选定了哪个版本。

命令	作用
dependencies	打印完整的依赖树，能看到传递依赖的层级
dependencyInsight	针对某一个库，告诉你冲突的根源

2.2.2 第二板斧：Android Studio 自带依赖分析

如果你是 Mac 用户，在菜单栏选 View → Tool Windows → Gradle，找到你的 app module，展开 help → dependencies。这个界面能清楚地展开所有依赖树。我个人习惯在这里看第三方库内部到底又引了哪些东西。

2.2.3 第三板斧：Build 分析器

构建完成后，点右边的 Build → Analyze APK。这个可以检查最终的 APK 里是不是真的重复打了同一个库的两个版本。我在项目中遇到过 com.google.guava 同时打了 27.0 和 30.0 两个版本，APK 体积白白多了好几兆。

2.3 怎么解决？我总结的 5 种实用策略

定位到谁在对谁打架之后，就要决定怎么劝架了。你想想看，其实就四种核心思路：屏蔽、替换、统一、强制。

策略 1：exclude 排除法

这个最常用。比如你依赖了某个 SDK，它内部引入了老版本的 support 库，你的项目里已经用了 AndroidX。这时候直接：

implementation('com.example:some-sdk:1.0.0') {
    exclude group: 'com.android.support'
}

也可以更精准地排除特定的 module：

implementation('com.example:some-sdk:1.0.0') {
    exclude group: 'com.android.support', module: 'support-compat'
}

策略 2：transitive = false 整体禁用

如果你觉得某个 SDK 的传递依赖全是垃圾（虽然不建议这样粗暴），可以直接禁掉：

implementation('com.example:some-sdk:1.0.0') {
    transitive = false
}

然后手动一条条补你需要的依赖。这个方式在重构老项目时偶尔会用，但日常开发我不推荐。

策略 3：全局 Force 强制版本

有些时候，你觉得某个库就该用这个版本，不管谁引入什么版本。可以在 build.gradle 里全局 force：

configurations.all {
    resolutionStrategy {
        force 'com.squareup.okhttp3:okhttp:4.10.0'
    }
}

策略 4：统一版本管理（BOM / 版本目录）

这个现在很流行，特别是对于全家桶系列的库，比如 OkHttp、Retrofit、Okio：

// 用 BOM 统一版本
implementation(platform("com.squareup.okhttp3:okhttp-bom:4.10.0"))
implementation("com.squareup.okhttp3:okhttp")
implementation("com.squareup.okhttp3:logging-interceptor")

或者用 AGP 7.0+ 的版本目录（libs.versions.toml）统一管理。这个方式能从根本上减少冲突，我建议每个团队都搞起来。

策略 5：使用 strict version（严格版本）

如果你希望任一依赖引入的版本必须和你声明的一致，可以声明为 strict：

implementation('com.squareup.okhttp3:okhttp') {
    version {
        strictly '4.10.0'
    }
}

这样如果其他库试图传递一个不同版本，Gradle 会直接构建失败并告诉你是谁的锅。这招在 CI 流水线上特别有用。

2.4 一个真实的排查案例

我之前接手过一个老项目，打 Release 包一直正常，但打开某页面就抛 NoClassDefFoundError。后来用 dependencyInsight 查到：

• 项目依赖的 com.example:core:2.0.0 传递依赖了 com.squareup.okhttp3:okhttp:3.12.0
• 另一个 com.example:feature:1.5.0 传递依赖了 com.squareup.okhttp3:okhttp:4.9.3
• Gradle 选择了 4.9.3，编译没问题
• 但 core:2.0.0 内部用了 3.12 才有的一个内部类，在 4.9.3 里被移除了

解决方案很简单：在 core:2.0.0 的依赖里 exclude 掉它自带的 OkHttp，然后让它用全局的统一版本。

2.5 依赖冲突处理流程

下面这张图是我自己总结的，从发现问题到解决问题的完整路径。你照着走一遍，基本能搞定 90% 的冲突。

2.6 预防大于治疗：几个好习惯

1. 每次加依赖前跑一次 dependencies：看清楚这个库会带哪些东西进来。
2. 用版本目录统一管理：AGP 7.0+ 的 libs.versions.toml 是真香，能减少手写版本号的低级错误。
3. 定期升级传递依赖：不要等到冲突了才想着升，特别是像 OkHttp、Google 系的基础库。
4. CI 流水线里加依赖检查：我经历过一次因为某个开发随意接了个第三方 SDK，导致整体项目里多出了三个版本的 Gson……从那以后我就把依赖检查写进 CI 了。