Android Gradle中如何隔离SDK自身依赖避免版本冲突

Gradle默认的依赖解析机制是构建阶段统一做版本仲裁，全项目同坐标依赖最终只会保留一个版本（默认取最高版本，也可被宿主配置覆盖），且所有类最终会被合并到宿主APK的dex中，由同一个PathClassLoader加载，这就是你当前遇到SDK调用宿主侧低版本Koin的根本原因——普通的implementation声明仅能限制编译期依赖传递，完全做不到运行时隔离。

要实现「SDK固定使用自身声明的依赖版本、宿主无感知、依赖无冲突」，有两类成熟方案，按落地成本从低到高排列：

方案一：字节码重定位（最推荐，90%以上商业SDK采用的方案） #

核心逻辑是在SDK打包阶段，将需要隔离的内部依赖直接打入SDK自身的AAR包中，同时批量修改所有依赖类的包名、以及SDK代码中对这些类的引用路径，从字节码层面让SDK内部依赖的类和宿主侧的同坐标类完全不重名，从根源上避免冲突。

操作步骤 #

• 引入支持类重定位的AAR打包插件，常规Android库可选适配AGP的fat-aar类插件，纯Java/Kotlin库可直接用shadow插件。
• 将需要隔离的依赖（比如你案例中的Koin）从implementation配置改为插件提供的embed配置，标记为需要打入SDK内部AAR的依赖，不要用api声明，避免编译期暴露给宿主。
• 配置重定位规则，将内部依赖的根包名统一替换为带SDK唯一标识的私有包名，示例配置：

  // SDK模块build.gradle 插件声明
  plugins {
      id 'com.android.library'
      id 'kotlin-android'
      id 'io.github.kezong.fat-aar' version '1.3.8'
  }
  
  dependencies {
      // 用embed替代implementation，将Koin打入SDK内部AAR
      embed "io.insert-koin:koin-android:3.2.0"
      // 其他不需要隔离的依赖仍用implementation/api即可
  }
  
  // 重定位规则配置
  shadowJar {
      // 将原org.koin包下的所有类，统一迁移到sdk私有包路径下
      relocate 'org.koin', 'com.your.sdkname.shaded.org.koin'
      // 其他需要隔离的依赖按相同格式追加规则即可
  }
  

方案效果 #

• 编译期：宿主无法访问SDK内部重命名后的Koin类，完全感知不到该依赖存在
• 运行时：SDK代码中所有Koin调用指向的是私有包路径下的3.2.0版本类，宿主自身的Koin 2.0.1仍在原org.koin路径下，二者互不干扰，不存在版本仲裁问题

方案二：独立类加载器隔离（适合大型SDK，隔离最彻底） #

如果SDK体量较大、隔离要求极高，可以打破Android默认的类加载双亲委派机制：

• SDK初始化时创建独立的DexClassLoader，将SDK自身的dex、所有内部依赖的dex放在该类加载器的查找路径首位
• 改写类加载逻辑：加载类时优先查找SDK自身dex中的类，找不到时再委托给宿主的类加载器
• SDK内部所有业务逻辑、依赖调用都在该独立类加载器中执行

注意事项 #

该方案需要适配跨类加载器调用逻辑，比如Context传递、四大组件注册、系统服务调用等场景都需要做特殊桥接，接入和维护成本较高，普通业务SDK不推荐优先使用。

常见无效方案避坑 #

• 不要依赖implementation关键字做运行时隔离：implementation仅能控制编译期依赖是否传递，APK打包阶段仍会合并所有依赖做版本仲裁，运行时类共享，完全没有隔离效果
• 不要在SDK侧配置resolutionStrategy.force强制依赖版本：该配置仅对当前模块作为主工程构建时生效，SDK被宿主接入时，宿主侧的依赖解析规则优先级更高，SDK中配置的强制规则会被直接覆盖
• 不要直接用fat-aar不做重定位：如果只是把依赖打进AAR不改包名，遇到宿主侧有同包名同类的情况，仍会出现类重复、版本覆盖的问题
• 重定位时记得同步处理依赖自带的res资源，给所有内部资源加SDK专属前缀，避免和宿主资源重名被覆盖

内容的提问来源于stack exchange，提问作者Vladimir Fisher