做Android开发这些年你敢说没被Duplicate class支配过我最近在模拟项目X里接入新版支付SDK时又跟老朋友碰上了第三方aar刚引进来编译直接报Duplicate class org.acme.comm.core.Util found in modules ...打开依赖树一看好家伙一个支付SDK、一个统计SDK各自都在内部塞了一份同一个网络库。这种jar冲突在Android里太经典了——两个或更多的第三方aar一起用编译期撞类、运行期NoClassDefFoundError、资源合并失败什么花活都能给你来一遍。这篇文章就专门聊一件事第三方aar引进项目之后jar/class冲突到底怎么定位、怎么解决。不管你是刚接手老项目的新人还是被一堆SDK折磨的集成工程师只要跟“依赖冲突”打过照面这章内容应该能帮你省下不少加班时间。1. 先分清你遇到的是哪种冲突1.1 aar和jar的区别决定了冲突的形态jar包本质就是一个zip容器打包的是编译好的.class文件和元数据。aar包则是“Android专用加强版jar”里面除了class之外还塞了res资源、AndroidManifest.xml、assets、JNI的so文件甚至还有一个classes.jar。所以从构建产物角度看一个aar内部本身就可能包含多个jar逻辑。但到了“类冲突”这个层面jar和aar没有本质区别。最终打包成dex时来自不同模块的两个class如果拥有相同的全限定名比如org.acme.comm.core.UtilD8/R8在合并阶段就会直接报Duplicate class。用一个生活化的类比来理解库房里两个工人各自带了一本封面、名字完全一样的笔记本但里面的笔记内容完全不同库管根本不知道该听谁的只能当场叫停。需要注意jar冲突和aar内部类冲突的根源不一样。jar冲突通常走的是Gradle传递依赖链你引入AA的POM又引了BB又引了C最后两个分支选了不同版本的同一个库。aar内部类冲突则是SDK厂商构建时直接把某个开源库的class编译进了自己的classes.jar。对外它就是一个不可分割的文件Gradle的exclude根本管不到它。这两种情况的解决路径完全不同所以第一步一定要分清楚冲突类型而不是急着改代码。1.2 四类常见的冲突现象从报错就能初判根据我的实际经验第三方aar引发的冲突基本可以归为四类各有各的报错长相。冲突类型典型报错/现场常见触发场景class重复Duplicate class X found in modules A.jar and B.jar两个aar内置同一库或传递依赖重名版本不一致编译能过运行期NoClassDefFoundError / NoSuchMethodError多个依赖对同一库要求不同版本资源冲突Resource merge failed / attribute xx already defined多个aar的res文件重名或manifest合并失败so库冲突duplicate element / couldnt find libxx.so不同aar在相同ABI下提供同名soclass重复最好认编译期直接失败报错会列出冲突类的全限定名和所在module。版本不一致最阴险编译阶段完全正常往往要跑到线上用户设备上才炸报错现场千奇百怪某个页面突然闪退、某个功能无法使用Log里只有NoSuchMethodError。资源冲突集中在R类、drawable、layout和manifest节点上多见于大型项目同时引入几个自带公共资源的SDK。so库冲突分两种情况构建期因重复so文件导致duplicates失败或者运行期加载so时报库找不到/符号找不到后者尤其难排查因为往往是某个so在当前ABI目录下缺失。看到报错先归类再往下走就不会在错误的方案上浪费时间。2. 冲突定位先做三件事比乱改代码快十倍2.1 从编译报错里提取有效信息当你看到这样一条报错Duplicate class org.acme.comm.core.Util found in modules pay-2.1.0-runtime.jar (com.xxx:pay:2.1.0) and statistics-3.0.0.jar (com.xxx:statistics:3.0.0)别慌这条报错已经把最重要的信息都给你了冲突的类名、出现在哪两个module、来自哪个坐标。把冲突类名记下来先判断它属于什么包。如果包前缀是某个第三方开源库的通用前缀比如org.acme.comm说明两个SDK都依赖了这个库如果包前缀是SDK厂商自己的域名那就是两个SDK各自实现了同样的功能类这种情况在金融类、推送类SDK里特别常见。但这里有个陷阱如果开启了R8/ProGuard混淆报错里的类名已经被重命名成a、b、c这种短名直接看会一头雾水。我的习惯是先把R8临时关掉跑一次或者在mapping文件里搜索映射关系把混淆后的类名还原成源码类名再定位。很多人卡在这步是因为盯着一个a.a.a去猜根本猜不出来。2.2 用gradle dependencies命令吃透依赖树怀疑冲突来自传递依赖时最快的方式是用Gradle自带的依赖报告命令。在项目根目录执行./gradlew :app:dependencies --configuration debugRuntimeClasspath deps.txt打开deps.txt搜索之前定位到的库名。输出是树形结构大致长这样debugRuntimeClasspath - Runtime classpath of source set debug. --- com.xxx:pay:2.1.0 | \--- org.acme:network-core:1.8.0 - 1.9.0 \--- com.xxx:statistics:3.0.0 \--- org.acme:network-core:1.8.1 - 1.9.0需要读懂几个关键符号-表示Gradle最终解析到的版本(*)表示该依赖在其它地方已经出现并统一了版本---和\---表示树的分支关系。上面这个例子里pay和statistics分别要求network-core的1.8.0和1.8.1Gradle默认按“最高版本优先”策略选了1.9.0。但注意“最高版本优先”只代表Gradle选了一个版本不代表这个版本对两边都兼容。如果1.9.0删除了1.8.x里的某个方法运行期就会毫无征兆地NoSuchMethodError。如果想看某个具体依赖是从哪条路径被引上来的用dependencyInsight更直接./gradlew :app:dependencyInsight --configuration debugRuntimeClasspath --dependency network-core它会输出所有引入该库的路径以及最终选中的版本是排查“版本被悄悄升级”问题的神器。注意配置名要跟变体对应debug包看debugRuntimeClasspathrelease包里如果用了不同混淆规则最好也查一下releaseRuntimeClasspath。2.3 物理层面确认aar/jar包里到底有什么依赖树看不到问题但编译照样报重复类这种情况十有八九是第三方aar把依赖库直接编译进了内部。这时需要把aar当zip解压看看classes.jar里到底装了什么。严谨的做法是分两步先解压aar再单独解压classes.jarunzip -o pay.aar -d pay_tmp/ mkdir classes_tmp cd classes_tmp jar xf ../pay_tmp/classes.jar ls org/acme/comm/core/如果你在多个aar里都能找到同样的包目录恭喜你遇到了“内嵌重复类”问题。这种冲突在依赖树里完全看不出来因为对Gradle来说每个aar只是一个独立文件它并不知道aar内部本来就塞了另一个库的副本。我还习惯写一个脚本把本地缓存的jar全扫描一遍快速定位某个类出现在哪些包里for j in $(find . -name *.jar); do if unzip -l $j 2/dev/null | grep -q org/acme/comm/; then echo $j fi done这个脚本在手动检查公司私有仓库里某几个aar的依赖问题时非常好用。执行完基本就能确定是A自带了一份网络库还是B内置了副本冲突面到底有多大。3. 可落地的六种解法每种都讲清楚适用范围先给结论再逐条展开。处理冲突的优先级我建议这样排先看能不能用Gradle配置解决统一版本或exclude再看要不要物理处理解压后删除/重打包最后才考虑重命名和classloader隔离这种重型手段。上来就重打包非常不划算因为SDK一更新改动全废。方案适用范围侵入度可持续性统一依赖版本传递依赖版本不一致低中exclude排除传递依赖明确不需要低中物理剔除重打包aar内嵌重复且确定无用中差字节码重命名aar内嵌重复且双方都需要高差资源/so单独处理资源或native冲突中中classloader隔离多个复杂SDK共存高好3.1 方案一统一依赖版本优先考虑如果冲突来自Gradle传递依赖只是同一个库的不同版本号最简单的做法是强制一个版本。在app模块的build.gradle里写configurations.all { resolutionStrategy { force org.acme:network-core:1.8.2 } }想精细控制某一条规则可以用eachDependencyconfigurations.all { resolutionStrategy.eachDependency { details - if (details.requested.group org.acme details.requested.name network-core) { details.useVersion 1.8.2 } } }我更推荐第二种因为它只锁定目标库不会误伤其它同名同组依赖。用force有几个注意点。第一选版本不要盲目选“最新”要选“两边SDK要求版本基础上最安全的一个”。通常厂商会在发布说明里标注兼容范围也可以看两个SDK的POM里声明的依赖区间取交集。第二强制统一版本后编译大概率能过但运行期一定要做一次真机回归重点测那些调用了网络库深层API的页面。第三这个方案对“aar内部已内嵌类”完全无效因为force管的是Gradle依赖解析管不到aar里的classes.jar。3.2 方案二exclude剔除不想要的传递依赖当某个传递依赖是多余的或者你想用自己的版本替换时用exclude最干净。典型写法implementation(com.xxx:pay:2.1.0) { exclude group: org.acme, module: json-lib }只写group也是允许的会把该组下所有模块都排除但范围太大容易误伤。我习惯尽量写完整坐标宁可多写几行也不要一把梭。全局排除写法configurations.all { exclude group: org.acme, module: json-lib }这种写法效果很猛所有模块的传递依赖里都不再包含该库。副作用也猛如果有某个SDK的代码真的依赖它且没有兜底你会瞬间收获一屏幕NoClassDefFoundError。所以全局排除只建议在团队对依赖结构非常清楚时使用排完一定要重新拉一次依赖树确认没有“连坐”。还有一个容易混淆的点exclude只对传递依赖有效对aar内部classes.jar里已编译进去的类无效。很多人遇到Duplicate class以为exclude一下就好结果发现毫无变化就是因为类在aar内部不在依赖解析范围内。3.3 方案三解压后物理删除重复类再重打包临时补丁当类确实被编译进了aar内部且你能确认这个类是冗余的比如SDK内置了一个旧版工具类你的工程里已经有新版可以把它物理删掉。基本流程如下注意要把classes.jar单独解压再处理# 1. 解压aar unzip -o pay.aar -d pay_tmp/ # 2. 单独解压classes.jar到classes_tmp mkdir classes_tmp cd classes_tmp jar xf ../pay_tmp/classes.jar # 3. 删除要清理的包 rm -rf org/acme/comm/old_util/ # 4. 重新打包classes.jar jar cf ../pay_tmp/classes_new.jar . # 5. 替换并重新打包aar cd ../pay_tmp mv classes_new.jar classes.jar zip -r ../pay_fixed.aar .我做这类操作时一定会先备份原始aar并且每次只删除确定无引用的类。判断方法很简单用反编译工具打开classes.jar搜索被删包名的引用方如果没有其它类引用它删除才安全。如果删错了运行期会报NoClassDefFoundError而且这个错误往往发生在冷门业务路径上可能很久才暴露。另一个必须提醒的点重打包之后的aar没有厂商签名本地依赖通常没问题但要发布到团队私有仓库就得自己补签名否则别人拉下来可能连资源都对不齐。另外这个方法不具备可持续性——厂商每次发新版你都要重复一次这种手工手术。它的定位是临时补丁只配在发版前夕救急不配进长期工程方案。3.4 方案四字节码层重命名包名终极手段但高风险两个SDK都内嵌了同一个库而且两边都需要用这个库的核心能力删哪一个都不行。这种时候唯一相对可行的本地解法是把其中一个SDK内部的该库类整体换个包名同时把所有引用点同步改写。简单说就是把org.acme.comm改写成org.acme.comm.svc然后jar里所有对新旧包名的引用都在字节码层面替换掉。靠手工完成这个不现实通常借助字节码处理工具或Gradle重定位插件来做。社区里很多方案都支持这种“重新定位包名”的能力搜“gradle jar relocate”能找到一堆现成实现。重命名的完整步骤大致是确认要重命名的包前缀和SDK内所有依赖方向生成一份“新旧包名对照表”。在构建流程中加入transform或自定义task在打包前对目标jar执行包名替换。处理字节码里的类引用、方法描述符、字段描述符这些工具一般会自动处理。手工检查字符串常量里的类名。这是最坑的一步如果SDK里有Class.forName(org.acme.comm.X)这种反射代码字节码重定位工具不会帮你改字符串运行期照样找不到类。重新执行完整编译对所有使用到该SDK的业务场景做回归。这个方案的高风险点在于反射、注解处理、序列化以及so库内部对Java类的引用。so文件里如果硬编码了Java类全路径重命名后native层会直接失败这种错误连崩溃堆栈都很难看懂。我个人的建议是除非你非常熟悉字节码处理且确认SDK里没有复杂反射否则不要轻易上。如果上了一定要把映射文件保存好SDK升级时逐项对照。3.5 方案五资源冲突与so库冲突的单独处理资源冲突经常被人忽略但实际遇到率不低。两个aar里都有同名drawable时构建期会报资源合并失败如果资源名不同但manifest里定义了互相冲突的属性则可能在运行时出现取错资源的现象。先说构建期的资源合并失败。遇到Resource merge failed优先看完整报错它会指出是哪个文件冲突。大部分情况下只能手动改名或者请SDK厂商修改内部资源命名。这里要说说resourcePrefixandroid { resourcePrefix pay_ }它能让当前module自己写的资源自动加上前缀主要用来防止自己新建资源时不小心重名对已编译好的第三方aar内部的资源名没有任何约束力。很多文章说加这个就能解决aar资源冲突实际上不行——aar打包完后内部资源名已经固定consumer侧的resourcePrefix管不到它。对于构建期因为重复文件比如META-INF导致的失败可以通过packaging排除packagingOptions { resources { excludes [/META-INF/xxx] } }新版AGP推荐用packaging块老版本用packagingOptions两种情况我都遇到过。再看so库冲突。如果构建期报duplicate element可以用pickFirsts让Gradle选其中一个packagingOptions { jniLibs { pickFirsts [lib/armeabi-v7a/libnative.so] } }但我不推荐把这个当作最终解法。pickFirst只解决“构建期文件重复”无法解决“两个SDK里的so文件版本不一致运行期某一边调用新符号就崩溃”的问题。最稳的方式是推动两个SDK厂商统一so版本或者确认它们的so互不干扰后只保留被更核心SDK依赖的那份。如果两个SDK共用同一个本地库但版本差异巨大基本没有完美的本地patch只能上隔离方案。3.6 方案六classloader隔离复杂场景的最终手段当冲突SDK数量多、关系复杂前面所有方案都压不住时可以考虑在架构层面做隔离。思路很简单把某个SDK及其依赖放进单独的dex/资源包运行时用一个父最后ParentLast的classloader去加载它让这个SDK和主工程里的同名类互不见面。一个简化的实现思路是写一个ClassLoader子类class IsolatedClassLoader extends ClassLoader { private final DexClassLoader inner; Override protected Class? loadClass(String name, boolean resolve) throws ClassNotFoundException { if (name.startsWith(org.acme.comm.)) { Class? c inner.loadClass(name); if (c ! null) return c; } return super.loadClass(name, resolve); } }真要在项目里落地事情会复杂很多Android默认的ClassLoader是父先ParentFirst模式你需要把加载顺序反转资源访问是全局的光隔离类不够还要隔离Resources组件生命周期、系统回调、跨模块调用都得适配。很多人把它和插件化框架混为一谈实际两者根本不是同一层级的复杂度。除非项目本身就在做插件化或者确实只有“三个SDK必须共存且互不通信”这一个解否则我不建议为了单纯的依赖冲突引入classloader隔离。它是成本最高、维护难度最大的方案应该放在最后考虑。4. 实战复盘一个支付SDK和统计SDK撞车的完整处理过程4.1 从报错到解决的逐步记录我在模拟项目X里接入的是两个厂商的SDK一个支付SDKcom.xxx:pay:2.1.0一个统计SDKcom.xxx:statistics:3.0.0编译报错是Duplicate class org.acme.comm.core.Util。第一步看依赖树发现两个SDK都没有直接暴露对network-core的传递依赖树很干净。第二步物理解压确认两个aar内部的classes.jar里都有整个org.acme.comm包。第三步检查引用发现这个网络库在两边都被实际调用支付SDK用它发请求统计SDK也用它上报数据删除任意一边的类都会导致那一边的核心流程崩。第四步决定重命名把统计SDK内部网络库的包名整体替换为org.acme.comm.svc在构建流程里用一个自定义task处理它的classes.jar处理完再合并进最终aar。第五步编译通过了但首次运行统计SDK初始化时直接崩。排查下来是有个类通过反射加载字符串里硬编码的还是旧包名。在项目代码里搜索硬编码的旧类名手动修掉或改为从新的包名加载才恢复。这个案例的教训很明显重命名方案最可怕的不是编译期而是运行期那些“藏在字符串里的类”。处理前一定要先确认该库内部有没有反射有的话重新评估成本。4.2 高频翻车点按踩坑概率排序翻车行为现场建议见冲突就exclude排除后连锁缺类NoClassDefFoundError排完立刻跑依赖树确认force到过高版本运行期NoSuchMethodError选交集版本做真机回归删除aar内嵌类后不验证冷门路径才崩溃全量回归后再发版重命名工具没处理反射初始化即崩先搜字符串常量里的类名只解决构建期so重复运行期so符号找不到推动统一so版本在混淆状态下排查类名全短名无从下手先关R8或查mapping每个翻车点背后都是真实事故。尤其是“见冲突就exclude”这个团队里出现过不止一次因为A SDk传了某个库给B用exclude后B的核心功能直接崩了。任何时候在依赖上动手脚都要重新跑依赖树和回归验证。4.3 长期工程上的预防措施依赖冲突解决一次不难难的是不再复发。我通常建议团队做四件事。第一用版本目录统一管理依赖。Gradle的版本目录version catalog或BOM可以把核心库版本集中定义新SDK引入时先对照清单避免同一库在多处声明不同版本。第二在CI上加依赖变更检查。每周或每次发版前跑一次./gradlew :app:dependencies对依赖树快照做diff新增冲突一目了然而不是等编译报错才去查。第三开启冲突即失败。可以在解析策略里加上failOnVersionConflict()让Gradle在出现版本冲突时直接构建失败逼着团队尽早解决。这个开关对维护团队纪律很有帮助代价是前期会有一些本来能忽略的冲突突然变成red build需要团队花时间清理。第四推动SDK厂商规范化。如果多个厂商都把公共库硬编进aar终端开发者只能一次次手工patch。可以把问题反馈给厂商要求把公共库改成传递依赖或者至少在发布说明里标注内部依赖版本。健康的三方依赖生态需要厂商配合而不是终端用户持续打补丁。最后再说一点个人体会。踩过几次坑之后我现在处理aar/jar冲突的顺序基本固定先跑依赖树判断冲突类型再按“统一版本→exclude→物理处理→重命名→隔离”的优先级逐级尝试绝不跳过前两步直接重打包。重命名和隔离这些手段虽然能救急但每次SDK升级都可能复发治标不治本。真正让项目长期稳定的还是统一的依赖管理规范和愿意配合的SDK生态。如果你也正在被某厂商的内嵌依赖折磨别一个人硬扛把问题写成清晰的报告反馈过去往往比在本地打十次补丁更管用。