linkageerror是jvm链接阶段因同一类被不同classloader加载为不兼容版本而拒绝混用的错误，本质是类加载隔离失效；典型线索为loader constraint violation或duplicate class definition，根源多为依赖重复或provided/compile scope误用。
LinkageError 不是代码写错了，而是 JVM 在链接阶段“认不出自己人”——同一个类名（比如 javax.servlet.http.HttpServletRequest）被两个不同 ClassLoader 加载成结构不兼容的版本，字节码对不上，JVM 拒绝混用。编译时完全正常，运行时却崩，问题就藏在类加载隔离与依赖叠加里。
看堆栈里的关键线索
别急着改代码，先盯紧错误日志中的两句话：
- loader constraint violation：明确提示类加载器约束冲突，说明同一类被多个 loader 加载且互不承认
- duplicate class definition：直接指出某个类被重复定义，大概率是 WAR 包里塞了本该由容器提供的 API
如果报的是 NoClassDefFoundError 或 IncompatibleClassChangeError，也别只查 classpath，它们常是 LinkageError 的子表现，根源仍在加载冲突。
定位谁加载了谁
加 JVM 参数启动应用，让 JVM 自己说话：
- -verbose:class：启动时打印每个类由哪个 ClassLoader 加载，重点关注出错类是否反复出现、loader 名不同
- jcmd $PID VM.native_memory summary：辅助观察类加载器内存分布，异常增长可能暗示隔离失效
- 在 Tomcat 环境下，检查 WEB-INF/lib 是否误打入
servlet-api.jar或jsp-api.jar；Spring Boot 嵌入式容器要警惕tomcat-embed-jasper和外部容器 JSP API 的版本打架
挖依赖树，揪出隐藏副本
90% 的 LinkageError 来自 Maven 依赖叠加。执行命令层层下钻：
-
mvn dependency:tree -Dincludes=org.apache.commons.lang3：确认
commons-lang3是否从多个路径引入，特别注意compile和providedscope 混用 - jar -tf your-app.war | grep StringUtils.class：验证最终打包产物里，这个类到底落在哪个 jar 中
- IDEA 中右键模块 → “Show Dependencies”，勾选 Include non-classpath dependencies，可视化看到冲突节点和传递链
注意：<exclusion></exclusion> 只能砍掉传递依赖，不能屏蔽你自己直接声明的依赖。比如你写了 spring-web，它带进来的老版 jakarta.annotation 就得手动排除或升级。
容器环境下的加载优先级陷阱
Tomcat 默认用 WebAppClassLoader，遵循双亲委派但允许打破——它优先加载 WEB-INF/classes 和 WEB-INF/lib，再委托给父加载器。问题常出在这里：
- 应用里
lib/放了slf4j-api-1.7.36.jar，而 Tomcat 自带slf4j-api-2.0.7.jar，两者不兼容 → 启动时可能不报错，但运行中调用新方法就抛 NoSuchMethodError - 多个 WAR 部署在同一 Tomcat，各自 lib 里都有
netty-buffer不同版本 → 类加载器隔离本应生效，但若用了共享线程池或静态工具类，就可能跨应用污染 - 解决思路不是删掉一个，而是统一收敛：把容器级依赖设为
provided，确保只由容器提供；应用内只保留业务强依赖，版本由根 pom 统一锁定
