企业官网建设流程全解析

1. 依赖冲突的本质：为什么只知道报错还不够

1.1 从一次经典崩溃现场说起

在Android开发里，“依赖冲突”这四个字基本和“加班”绑定在一起。我见过太多项目，功能都写完了，一执行Sync直接红一片，要么是Manifest merger failed，要么是java.lang.NoSuchMethodError，运气好点的能定位到具体库，运气差的连报错都看不懂。有一次我接手一个老项目，仅因为某个图片库的传递依赖版本不一致，导致启动时ClassNotFoundException，当时全组人翻了三个小时代码，最后发现是Gradle把两个不同版本序列化进了dex，运行期才炸。

依赖冲突的本质其实很简单：Gradle会为每个依赖解析出一个版本，但当多个库引入了同一个组（groupId）和同一个工件名（artifactId）却要求不同版本时，解析过程就可能产生分歧。Gradle默认采用的是“最新版本胜出”策略，但“最新”不等于“正确”，更不等于“兼容”。很多库虽然版本号涨了，内部API却发生了破坏性变更，旧库对新版本根本不认。

这还只是版本冲突的第一层。真正麻烦的是“传递依赖冲突”——A库依赖C库的1.0，B库依赖C库的2.0，而A和B本身都没错，错就错在它们被放进了同一个工程。这时候如果没有清晰的冲突处理思路，根除路径就会变成“删一行配置试一下”“注释掉这个依赖试试”，结果往往是按下葫芦浮起瓢。

1.2 依赖冲突的三种典型场景

我把日常遇到的冲突归成三类，每类的处理思路都不一样。

第一类是版本冲突。这是最常见也是最容易理解的：同一个库的多个版本出现在依赖树里。比如项目中显式依赖了com.squareup.okhttp3:okhttp:4.9.2，某个网络库又依赖了com.squareup.okhttp3:okhttp:4.8.1，Gradle默认会选4.9.2。如果这两个版本的API差异不影响使用，其实不会出问题；一旦4.9.2删掉了某个方法，而那个网络库还在调用，运行期就会直接炸出NoSuchMethodError。

第二类是“同身份不同内容”的冲突。这里说的不是版本，而是坐标相同但来源不同。说得直白点，两个库都叫com.example:utils:1.0，但一个来自本地mavenLocal()，另一个来自远程仓库，内容完全不一样。Gradle会根据仓库顺序优先选第一个找到的，有时候本地缓存里的旧版本就会“劫持”整个解析过程。这种冲突最恶心，因为报错信息里你根本看不出来到底用的是哪个仓库的产物。

第三类是传递依赖深度嵌套。网上有调研说，平均每个Android项目里，一个直接依赖背后会带出七八个间接依赖，这些间接依赖还会互相引用。比如你引入了一个支付SDK，它带着某老版本的工具库，这个工具库又带着一个更老的Gson版本，最后你的项目里可能同时出现Gson的2.8.0、2.8.5和2.9.0三个版本。Gradle的依赖报告会显示“->”指向最终版本，但这掩盖了实际上有多少个版本被同时引入的问题。

1.3 为什么不能简单“删掉一行配置”

新手常犯的错是听说某个依赖冲突，就直接在build.gradle里把那个显式依赖删掉。这只能解决“显式依赖和传递依赖冲突”的表面问题。比如你删掉了显式的Gson依赖，想借网络库带的Gson来用，但万一网络库升级后不再传递Gson呢？你的代码里凡是用到com.google.gson.Gson的地方全部编译报错。

更隐蔽的问题是，删掉显式依赖后，Gradle解析出来的版本可能并不是你想要的版本。Gradle的默认策略是“max version wins”，也就是说它会选版本号最高的那个。如果项目里两个库分别传递了1.0和2.0，你删除了显式依赖1.0，最后剩下的可能是2.0，但这个2.0是给某个内部库用的，其API和你代码里写的完全对不上，照样是崩。

所以，处理依赖冲突的第一步永远是“搞清楚现状”，而不是“动手改配置”。你连冲突发生在哪个依赖、哪些路径引入了它、哪个版本最终生效都不知道，就谈解决方案，那和闭着眼睛修车没什么区别。

2. 分析冲突的第一步：拿到准确情报

2.1 用 dependencies 任务输出依赖树

我会先跑一遍依赖报告。在Android Studio的Terminal里执行：

./gradlew :app:dependencies --configuration debugRuntimeClasspath

这里的debugRuntimeClasspath是Android插件提供的配置项，基本能反映App运行时实际会用到哪些依赖。如果你还想查静态编译期的冲突，可以换成debugCompileClasspath。刷出来结果一般很长，我习惯加一个> /tmp/deps.txt把输出写到文件里，再慢慢看。

依赖树上的每一行都代表一个依赖节点，缩进表示层级关系。关键要注意这几种标记：

• ->：表示Gradle把某个冲突版本“提升”到了后面那个版本。例如com.google.code.gson:gson:2.8.5 -> 2.9.0，意思是实际最终使用2.9.0。
• (*)：表示这部分依赖在其他地方已经被展开过了，为节省篇幅省略展开。
• FAILED：表示解析失败，很多时候是因为冲突或网络原因。

我一般会先搜索有没有同一个库出现多次的情况，比如搜索gson，看它出现在哪些路径下。如果同一个库出现多次但最终版本不一致，那就要继续往下看是谁引出来的。

2.2 用 dependencyInsight 精准锁定某个库的来源

依赖树信息量太大时，可以用dependencyInsight把某个具体库的来源捋得一清二楚。命令如下：

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

这条命令会把okhttp相关的所有依赖路径都列出来，包含“直接依赖”和“传递依赖”，还会标注出“是哪个依赖请求了它”。比如：

com.squareup.okhttp3:okhttp:4.9.2 variant "releaseRuntimeElements" ... com.squareup.okhttp3:okhttp:4.9.2 Selection reasons: - By conflict resolution : between versions 4.8.1 and 4.9.2 org.example:network-sdk:1.2.0 com.squareup.okhttp3:okhttp:4.8.1

这样你就能清楚地看到，4.9.2是从哪里选出来的，谁又在要求4.8.1。这比在几百行的依赖树里人肉查找高效太多。

2.3 怎么正确读Gradle依赖树上的“->”和“(*)”

很多开发者看到v1 -> v2就以为Gradle做了“替换”，事实上它是“版本升级选择”，不是物理替换。被替换的低版本依然可能存在于最终依赖图中，只是运行时classpath上只保留了一个版本。但如果是通过多模块分别编译，某些模块内引用的可能还是旧版本APK里的字节码，最终还是会被打进同一个DEX里。所以有时依赖树上显示“统一了”，但运行期依然出现方法找不到，原因就在这里。

(*)符号同样容易误读。它不代表“没问题”，只代表“该依赖在其他地方已经被列出过”。如果你搜索某个库时发现它带有(*)，必须顺藤摸瓜找到第一次出现的位置，才能确认最终生效的版本。

经验之谈：分析依赖时，宁可多花10分钟把完整依赖树打开，也绝对不要只看AS提示的“Conflict”弹窗。那个弹窗里给出的“Open Gradle Script”和“Upgrade Dependency”很多时候只是表面处理，解决不了根因。

3. 解决冲突的四个层级与实操姿势

3.1 全局排除：一劳永逸但小心误伤

最“粗暴”的方式是在allprojects里配置全局排除：

allprojects { configurations.all { exclude group: 'com.google.code.gson', module: 'gson' } }

它的意思是：所有配置、所有依赖都别带Gson进来。如果你项目里其他地方显式引入了Gson，那没问题；如果没有任何地方显式引入Gson，而某些第三方库运行需要它，那就会直接NoClassDefFoundError。

我见过有人为了压掉Gson冲突，全局排除Gson，结果支付SDK在回调里new Gson，直接崩溃。这个方案只适合那些“你一定会在自己的代码里显式声明该依赖”的库。所以使用全局排除前，要仔细确认两点：项目里是否有一份可控的显式依赖；第三方库是否真的不需要你排除的那个版本里的特殊类。

3.2 按依赖排除：精确定位冲突点

比全局排除更稳妥的是在具体依赖上排除：

implementation('com.example:library-a:1.0.0') { exclude group: 'com.google.code.gson', module: 'gson' }

这样只是让library-a不传递Gson，其他库不受影响。如果你知道library-a里其实用不到Gson，或者你希望它使用你自己定义的版本，这个方案是最合适的。

还有一种情况，你要排除的不是某个库，而是某个“依赖组”，例如：

implementation('com.example:library-a:1.0.0') { exclude group: 'androidx.appcompat' }

不过这要非常谨慎，因为排除掉AndroidX相关组件，可能导致资源合并失败或运行时View冲突。

3.3 强制统一版本：从版本策略到 resolutionStrategy

大多数场景下，我们的目标不是“排除”，而是“让大家都用同一个版本”。Gradle官方提供的方案是resolutionStrategy。可以在模块级别这样写：

configurations.all { resolutionStrategy { force 'com.google.code.gson:gson:2.9.0' force 'com.squareup.okhttp3:okhttp:4.9.2' } }

force的作用是：无论哪个依赖要求什么版本，最终一律使用我指定的版本。它比dependencies里直接指定版本更“霸道”一点，因为它会影响所有传递依赖的解析。

不过force有个坑：它只能保证Gradle“选中”的版本一致，不能保证第三方库在混淆、编译期引用的符号仍然存在。如果强制到一个API大改的版本，某些库的方法引用就会在编译期或运行期炸掉。所以强制版本时一定要关注“API兼容性”而不是只看版本号大小。

如果项目里用的是Gradle 7以上的Kotlin DSL，可以写成：

configurations.all { resolutionStrategy { force("com.google.code.gson:gson:2.9.0") } }

3.4 让Gradle自动帮我挑版本：strictly 与 preferred

从Gradle 6开始，模块元数据（Gradle Module Metadata）中出现了“strictly”和“preferred”的概念。简单理解：

• preferred：期望的版本，但允许被更高版本替换。
• strictly：严格限制的版本，不可覆盖。

在构建脚本里可以声明：

implementation('com.google.code.gson:gson') { version { strictly('2.9.0') prefer('2.9.0') } }

不过实战中更常见的做法是使用platform()。如果一个项目有统一版本管理的BOM，就可以让Gradle自动对齐。

还有一个容易混淆的命令是dependencyConstraints，它主要用于约束库的候选版本范围，比如：

dependencies { constraints { implementation('com.google.code.gson:gson:2.9.0') } }

这种“约束”只在与依赖解析冲突时才会起作用。如果某个库直接传递了3.0且Gradle判断3.0更高，那么它可能不会执行你的约束。所以当我们需要“硬性统一版本”时，resolutionStrategy或者strictly才是可靠的选择。

4. 特殊场景与组合技巧

4.1 多个第三方库同时依赖不同版本的同一个库

我经常遇到的场景是：网络库SDK带了OkHttp 3.12，而另一个推送SDK带了OkHttp 4.8。两个版本之间的API有大量变化，但两个SDK都必须要用。这时候不能简单强上4.8，因为网络库SDK是基于3.12写的，内部可能用了HttpUrl相关的旧方法；强行统一版本后，它在某些分支上就会崩溃。

这种场景下通常有两条可走的路。第一条是在打包层面把它们分开，比如通过implementation改成compileOnly，把其中一个SDK的OkHttp依赖排除掉，然后自己统一提供一个中间适配层。这条路适合SDK引用的OkHttp版本差异极大、且你无法替换SDK内部实现的情况。

第二条是升级或动态替换SDK。先看这个SDK有没有新版本，很多库在升级后会兼容新版本OkHttp。如果没有，就只能做“包级隔离”，利用implementation的“模块私有性”，在子模块里单独依赖特定版本，让不同模块各自持有自己的OkHttp。这里一定要确认是否开启了isTransitive，以及混淆规则是否覆盖到对应包。

4.2 ClassNotFoundException 和 NoSuchMethodError 的区别

这两类运行期错误是依赖冲突最典型的“果”，但它们的修复思路完全不同。

NoClassDefFoundError、ClassNotFoundException，通常表示某个类在编译期存在，运行时却找不到。原因一般是依赖被排除后没有别的地方补充。比如你排除掉了某个库的Gson依赖，但没加自己的Gson依赖，一走到序列化那行就炸。这种问题我建议先查崩溃堆栈上第一个“找不到”的类属于哪个库，然后用dependencyInsight确认那个库是不是真的没有被传递进当前构建产物。

NoSuchMethodError则更麻烦，它表示“类找到了，但里面没有那个方法”。这种基本都是依赖版本不一致，编译期用的是新版本库A，运行期却加载了库B里的旧版本类，或者被其他库打包的“影子类”覆盖。常见于同一个类被不同库以不同版本分别打入DEX，classloader按加载顺序取到了旧的那份。这种问题单纯看Gradle依赖树还未必能发现，需要检查最终APK里的classes.dex或使用jdeps查看实际打包进去的类。

我自己排查这类问题的一个小技巧是：在崩溃前打印相关API的版本信息。比如OkHttp的OkHttpClient.VERSION、Gson的Gson.class.getPackage().getImplementationVersion()，运行日志里直接输出，看看到底加载了哪个版本。虽然不优雅，但定位问题非常快。

4.3 用 BOM 统一版本，降低冲突概率

如果你项目里要管十几个库的版本，一个个force实在太累。我更推荐用BOM（Bill of Materials）模式。做法是在自己的仓库里发布一个“版本清单”模块，里面只声明constraints，不包含实际代码。然后在业务模块中引入它：

implementation platform(project(':versions'))

versions模块的build.gradle类似这样：

dependencies { constraints { implementation 'com.google.code.gson:gson:2.9.0' implementation 'com.squareup.okhttp3:okhttp:4.9.2' implementation 'com.github.bumptech.glide:glide:4.14.2' } }

这样做的好处是：所有模块都用同一个版本，而且依赖规则集中在“一个文件”里维护。新增模块只需引用同一个platform，改动版本也只需改一处。对于多模块大型项目，非常推荐这种模式。

如果是用Android Studio的插件版本目录（version catalog），也可以直接在libs.versions.toml里定义版本，但注意version catalog定义的是“可选版本”，不是“强制约束”。它并不会阻止其他模块通过implementation直接引入不同版本。所以如果你的项目已经出现了冲突，只有platform和resolutionStrategy才能真正干预最终解析结果。

4.4 模块化改造：从根上减少爆炸半径

依赖冲突的另一个长期解法是模块化。说句实话，很多冲突都是因为一个超大的app模块把所有依赖都堆在一起，构建时所有传递依赖全都塞进同一个classpath。如果你按功能拆成独立的模块，每个模块内部依赖自己的库版本，那么多模块之间只会暴露“对外接口”，不会把内部的OkHttp、Gson全部传递出来。

拆模块是个大工程，但我们可以先做“最小的模块边界化”。比如新建一个core-network模块，里面统一管理OkHttp、Retrofit、Gson等网络相关库，对外只提供封装好的Api接口。所有业务模块只依赖core-network，而不直接依赖OkHttp、Gson。这时候就算另一个模块想用Gson 3.x，也要通过core-network的统一出口，你不用去管它内部怎么解析，因为Gson的传递依赖在这个模块里就被控制住了。

不过要提醒的是：模块化之后，implementation和api的区别变得尤为重要。如果没有特殊原因，优先用implementation，这样依赖不会传递到模块外部。要暴露给外部使用的类型，才用api声明。很多项目出现跨模块冲突，就是因为滥用api导致依赖被传出去了一大圈。

5. 常见问题速查与避坑笔记

5.1 排除后仍然冲突怎么办

先别急着加更多排除。依赖冲突没变化，通常是“排除的坐标和实际冲突的坐标不一样”。比如说，有的库发布时，supports库路径是androidx.appcompat:appcompat，但实际引入的是androidx.appcompat:appcompat-resources。如果只排除了前者，后者依然会传递进来。

还有一种是“同一个库被不同名称打包”。比如某SDK内部把OkHttp改写后重新打包成一个内部库，它在Maven仓库里的名字是com.example.thirdparty:okhttp-shaded:4.0.0，这时候你去排除com.squareup.okhttp3:okhttp是没用的，因为SDK根本不走这个坐标。遇到这种“shaded”或“relocated”的库，只能通过反编译或阅读官方文档确认真正需要排除的坐标。

我的经验是：在排除无效时，先跑一次dependencyInsight，看是否存在“依赖被排除后，依赖树中依然出现相同group:artifact但不同版本”的情况。有时候是构建缓存的问题，先执行./gradlew clean再试。别一上来就怀疑排除写法。

5.2 强制版本后编译通过但运行崩溃

这个问题我踩过不少坑。强制版本只能保证Gradle解析时选择某一个版本，却不能保证其他依赖在编译时引用的API依然存在。比如某库编译时引用了OkHttp 3.x内部某个包名下的类，你把版本强制成4.x后，编译时由于该库本身是AAR，里面对应的字节码已经被编译好了，类文件和方法引用不会因为强制版本而改变。可运行时，Gson和OkHttp被替换成了4.x，DEX里没有了3.x的那个私有类，旧库一执行就NoClassDefFoundError。

解决方式有几种：

• 要么升级这个旧库到支持新版本的版本；
• 要么别强制OkHttp版本，改为只对某一个模块强制；
• 要么给旧库单独提供“兼容包”。

在multidex还好用的时代，有人会故意把两个版本都打进去，靠classloader顺序来解决问题，但这在Android 10以后基本不靠谱，因为会碰上dex2oat优化后加载顺序不一致的问题。我强烈不建议走这种小路。

5.3 两个容易忽略的细节：版本号规约与仓库顺序

版本号规约看起来和冲突无关，其实影响很大。使用动态版本号1.+、latest.release的后果是每次构建拉取都可能变依赖版本，冲突原因永远无法复现。我接手过的项目里，凡是用+版本的，几乎都有诡异的依赖问题。一定要显式固定版本号，至少每个lib的版本要有个明确的tag。

仓库顺序同样关键。多个仓库存在同一个库但版本不同时，Gradle默认按声明顺序先去第一个仓库找。如果第一个仓库里有一个旧的、被损坏的或本地魔改的包，Gradle不会去第二个仓库比对版本更高，而是直接采用找到的版本。所以私有仓库应该放在靠前的位置还是靠后，要慎重考虑。一般建议：公共仓库（mavenCentral、google()）在前，私有仓库在后；如果私有仓库有覆盖公共仓库的定制需求，才故意放前面。很多“本地构建没问题，CI上天天ParseException”的问题，其实就是私有仓库顺序不一致导致的。

整理依赖相关配置的时候，我会顺手把repositoriesMode设置成PREFER_SETTINGS，统一在settings.gradle里管理仓库，避免各个模块写各自不同的仓库顺序。

最后再分享一个我很受用的习惯：每次升级第三方库，我都在提交信息里附上该库的版本变化和关联的传递依赖变化，比如“升级xx 2.0 -> 3.1，另附带okhttp 4.x升级，运行期已验证”。这不是什么花哨技巧，但时间长了，项目里每个版本的变动都有迹可循，真正再遇到冲突时，能快速回溯到是哪个模块的哪次升级引起的。依赖冲突从来不是靠“运气”解决的，而是靠对依赖树的清晰理解和一套稳定的操作流程。