LinkageError 是 JVM 类加载冲突导致的链接失败，本质是同一类名被不同 ClassLoader 加载为不兼容版本；典型表现包括 NoClassDefFoundError 等子类错误，根因多为依赖重复（如 servlet-api 同时由容器和应用引入）或自定义 ClassLoader 隔离不当。
LinkageError 不是代码写错了，是类加载“认不出自己人”
LinkageError 的本质不是语法或逻辑错误，而是 JVM 在链接阶段发现：同一个类名（比如 javax.servlet.http.HttpServletRequest），被两个不同的 ClassLoader 加载成了“两个不兼容的版本”。它们字节码结构对不上，JVM 拒绝把它们混用——哪怕编译时完全没问题。
典型现象：NoClassDefFoundError、NoSuchMethodError、IncompatibleClassChangeError 都是它的子类。你看到这些错误，别急着改方法签名或补 classpath，先查“谁加载了谁”。
- 常见场景：Web 应用打成 WAR 包部署到 Tomcat，但项目里又显式引入了
servlet-api.jar（scope=compile）；或 Spring Boot 打包时把tomcat-embed-jasper和容器自带的 JSP API 一起带上 - 关键信号：错误堆栈里出现
loader constraint violation或duplicate class definition - 验证方法：加 JVM 参数
-verbose:class，启动时看同一类是否被多个 loader 加载过；或者用jcmd $PID VM.native_memory summary辅助定位类加载器隔离问题
排查重复类：从 mvn dependency:tree 到 jar -tf
90% 的 LinkageError 源于依赖冲突——两个不同版本的 jar 包里都含 org.apache.commons.lang3.StringUtils 这种通用类，而你的代码在 A 版本里编译，在 B 版本里运行。
- 先执行
mvn dependency:tree -Dincludes=commons-lang3，确认是否有多条路径引入了commons-lang3，尤其注意compilevsprovidedscope - 再检查 WAR/BOOT-INF/lib 下实际打包进来的 jar：
jar -tf your-app.war | grep StringUtils.class，看它到底来自哪个 jar - 如果用 IDE（如 IntelliJ），右键模块 → “Show Dependencies”，勾选 “Include non-classpath dependencies”，能直观看到冲突节点
- 注意 Maven 的
exclusion只影响传递依赖，不影响直接声明的依赖；若你自己写了<dependency><groupId>org.springframework</groupId><artifactId>spring-web</artifactId></dependency>，就得手动降级或排除其内部拉进来的老版jakarta.annotation
Web 容器里最常踩的坑：provided 写成 compile
Tomcat、Jetty 等容器已提供 servlet-api、jsp-api、el-api，你本地再打进 WAR，等于让 JVM 同时见到两套同名接口——一个由 BootstrapClassLoader 加载（容器自带），一个由 WebAppClassLoader 加载（你打包的），一调用就报 LinkageError: loader constraint violation。
- 必须确保这些依赖的 scope 是
provided：<scope>provided</scope>，否则 Maven 默认按compile处理，会打进WEB-INF/lib - Spring Boot 用户注意：
spring-boot-starter-tomcat默认是provided，但如果你手动加了tomcat-catalina或tomcat-jasper，且没设 scope，就容易触发冲突 - IDE 调试时也得小心：IntelliJ 的 “Use module compile output” 选项如果开启，可能绕过 Maven scope 控制，导致测试时正常、打包后失败
自定义 ClassLoader 场景下怎么避免“同名不同命”
当你写插件系统、热部署框架或 OSGi 类机制时，主动用 URLClassLoader 加载外部 jar，就极容易触发 LinkageError——比如插件 A 和插件 B 都依赖 logback-core-1.4.11.jar，但你用了两个独立的 ClassLoader 去加载，它们各自加载的 ch.qos.logback.core.Appender 在 JVM 看来就是两个不兼容的类。
- 解决核心：让共享类（如 SLF4J 接口、JSON 工具类）统一由父加载器提供，子加载器只加载业务逻辑类；即设置好
parent参数，不要传null - 验证方式：在插件代码里打印
MyClass.class.getClassLoader()和SharedUtil.class.getClassLoader()，确保后者是前者的祖先 - 禁止操作：不要在子加载器里通过反射调用父加载器加载的类的方法，且该方法参数类型是子加载器自己加载的同名类（比如父加载器的
List接收子加载器的ArrayList实例） - 替代方案：优先用服务接口（SPI）解耦，而不是直接传递具体类实例；例如定义
LogService接口，由宿主提供实现，插件只调用接口方法
LinkageError 最难调试的地方在于：它不告诉你哪两个类冲突，只说“链接失败”。真正要定位，得靠 -verbose:class 日志 + 对比类加载器输出 + 人工梳理依赖树——工具帮不了全部，经验才是关键。
