Java 应用在引入多个第三方 SDK 时，经常会碰到同一个依赖库的不同版本被传递进来，比如 A 组件需要 Guava 30，B 组件需要 Guava 18。Maven 或 Gradle 的默认仲裁通常只会保留一个版本，运行期一旦调用到另一个版本独有的方法，就会抛出 NoSuchMethodError。要彻底解决这类问题，除了升级或改依赖，还可以借助 ClassLoader 的隔离能力，让不同版本的类同时存在，各用各的。
双亲委派机制为什么会放大版本冲突
Java 类加载器大致分为 Bootstrap ClassLoader、Platform ClassLoader 和 Application ClassLoader 三层。默认情况下，应用类加载器加载一个类之前，会先把请求委派给父加载器，只有父加载器找不到该类时，子加载器才尝试自己加载。这个双亲委派模型的作用是保证核心类库不会被随意替换，同时避免同一个类被重复加载。但它也带来一个明显限制：在同一个类加载器命名空间中，两个全限定名完全相同的类只能存在一个。
当两个第三方 SDK 分别依赖不同版本的同一个库时，Maven 只会保留其中一个版本。如果保留的是旧版本，而新版本 SDK 调用了一个只有新版本才有的方法，运行期就会因为加载了旧类而抛出 NoSuchMethodError。更隐蔽的是，这种错误不一定在启动阶段出现，可能只在某条业务分支触发，排查起来非常费劲。问题根源不是 Maven 没有选对版本，而是类加载器没有为不同版本提供隔离空间。
自定义 ClassLoader 实现子优先加载
要让同一个类的不同版本同时存在于 JVM 中，最直接的办法就是在类加载环节做隔离。可以创建多个自定义 ClassLoader，每个加载器指向一个包含特定版本 jar 包的目录。通过重写 loadClass 方法，让指定的包名先由子加载器自己查找，找不到再委派给父加载器。这样，A 组件使用指向 Guava 30 目录的加载器，B 组件使用指向 Guava 18 目录的加载器，双方互不干扰。
public class VersionedClassLoader extends URLClassLoader {
private final Set<String> childFirstPackages;
public VersionedClassLoader(URL[] urls, ClassLoader parent, Set<String> childFirstPackages) {
super(urls, parent);
this.childFirstPackages = childFirstPackages;
}
@Override
protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundException {
synchronized (getClassLoadingLock(name)) {
Class<?> loaded = findLoadedClass(name);
if (loaded == null) {
boolean childFirst = childFirstPackages.stream().anyMatch(name::startsWith);
if (childFirst) {
try {
loaded = findClass(name);
} catch (ClassNotFoundException ignored) {
// 子加载器找不到再交给父加载器
}
}
if (loaded == null) {
loaded = super.loadClass(name, resolve);
}
}
if (resolve) {
resolveClass(loaded);
}
return loaded;
}
}
}
这段代码只对指定的包前缀启用子优先策略，其他类仍然走双亲委派，避免破坏 Java 核心类库的稳定性。使用方需要把不同版本依赖分别解压到独立目录，然后通过 URLClassLoader 的 URL 数组指定这些目录。除了类加载，资源文件也建议同步重写 getResource，否则可能出现类版本隔离了，配置文件却读错版本的情况。
自定义 ClassLoader 的隔离效果虽然直接，但也会带来一些额外成本。不同加载器加载出来的同一个全限定名类，在 JVM 看来是不同类型，互相赋值或强转时会抛出 ClassCastException。因此在设计隔离边界时，需要明确哪些类必须共享，哪些类需要隔离。通常做法是把接口和公共模型类放在父加载器可见的位置，把不同版本的实现类放进子加载器目录。
线程上下文类加载器与 SPI 场景
有些依赖版本冲突不是直接 new 对象产生的，而是通过 SPI 机制加载实现类时发生。JDBC 驱动、SLF4J 日志绑定、Servlet 容器扩展等场景都依赖 ServiceLoader 或类似机制。SPI 框架的接口类通常由 Bootstrap 或 Platform 加载器加载，但具体实现类位于应用类路径下，按照双亲委派模型，上层加载器无法向下看到子加载器的类。Java 为此提供了线程上下文类加载器，框架通过 Thread.currentThread().getContextClassLoader() 获取合适的加载器去加载实现类。
ClassLoader original = Thread.currentThread().getContextClassLoader();
try {
Thread.currentThread().setContextClassLoader(versionedLoader);
ServiceLoader<Driver> drivers = ServiceLoader.load(Driver.class);
for (Driver driver : drivers) {
System.out.println(driver.getClass().getName());
}
} finally {
Thread.currentThread().setContextClassLoader(original);
}
如果依赖冲突恰好发生在 SPI 实现上，可以临时切换线程上下文类加载器，让 ServiceLoader 从指定版本的目录中加载实现类。调用结束后必须在 finally 块中恢复原来的加载器，否则线程被线程池复用后可能串到其他业务上下文，造成更隐蔽的类加载问题。
不过线程上下文类加载器并不是万能钥匙。它只在框架读取上下文加载器时才生效，如果某些 SDK 在内部直接使用自身的 ClassLoader 或硬编码了 Class.forName，这种切换就不会起作用。因此在实际排查中，需要先确认冲突类到底是由哪个加载器、通过什么方式加载的，再决定是否采用上下文切换方案。
模块级隔离与包名重定位的工程选择
工程中更大规模的隔离可以参考 Tomcat 的 WebappClassLoader。每个 Web 应用拥有独立的类加载器，不同应用可以加载不同版本的 Spring 或日志框架。OSGi 则把隔离粒度进一步细化到 bundle，每个 bundle 有自己的类加载器，只通过显式导出的包进行交互。这些方案的核心都是让不同模块拥有独立的类加载器命名空间。
如果不想维护复杂的自定义 ClassLoader，也可以从构建阶段入手，使用 Maven Shade 或 Gradle Shadow 对冲突依赖做包名重定位。例如把 com.google.common 改成 shaded.com.google.common，这样即使两个版本同时出现在类路径上，也不会再发生同名类冲突。下面是一个 Shade 插件配置片段。
<configuration>
<relocations>
<relocation>
<pattern>com.google.common</pattern>
<shadedPattern>shaded.com.google.common</shadedPattern>
</relocation>
</relocations>
</configuration>
包名重定位的优点是简单直接，不需要在运行时介入类加载过程，也不容易产生 ClassCastException。缺点是会增加构建复杂度，所有反射、资源路径、序列化字符串都要同步修改，否则可能找不到类或资源。如果冲突只涉及少量类，或者不希望引入类加载器层次，这种方案非常合适。
反过来，如果系统本身就是插件化架构，或者需要动态加载不同版本的模块，自定义 ClassLoader 或 OSGi 方案更合适。自定义 ClassLoader 还能做到按需加载和卸载，但要注意及时关闭 URLClassLoader、清理静态引用，否则元空间中的类元数据不会被回收，长期运行会出现内存泄漏。
综合来看，ClassLoader 解决依赖版本冲突的本质是在 JVM 中构造多个命名空间，让相同全限定名的类各归各位。选择哪种策略，取决于冲突范围、模块生命周期和团队维护能力。无论采用哪种方案，都需要在测试阶段覆盖不同版本分支的实际调用，并增加类加载器相关日志，方便未来定位问题。
类加载器依赖版本冲突自定义ClassLoader修改时间：2026-10-02 14:44:24