IncompatibleClassChangeError 表示运行时类结构与预期不一致，本质是二进制兼容性被破坏；常见于接口变抽象类、方法签名变更未重编译、字段删除仍访问等，需检查 JDK 版本一致性、依赖冲突、字节码及全量重建。
看懂 IncompatibleClassChangeError 的真实含义
这个错误不是编译失败，而是 JVM 在运行时发现某个类的结构和它“以为的”不一致。常见于：类从接口变成了抽象类、方法签名变了但调用方没重编译、字段被删了却还在读取——本质是**二进制兼容性被破坏**，不是语法或逻辑错。
它和 NoClassDefFoundError 或 ClassNotFoundException 容易混淆：IncompatibleClassChangeError 说明类加载成功了，但结构对不上；后两者是根本找不到类。
检查 javac 和 java 版本是否真正一致
很多人只看 java -version，却忘了 javac 可能来自另一个 JDK（比如系统 PATH 里混了多个 JDK，或者 IDE 指定了不同 JDK 编译，但命令行用的是另一个运行）。
- 执行
which javac和which java，确认路径是否指向同一 JDK 根目录 - 在 IDE（如 IntelliJ）里检查：
File → Project Structure → Project → Project SDK和Project language level是否匹配构建脚本中指定的版本 - Maven 用户注意：
maven-compiler-plugin的<source></source>和<target></target>必须 ≤ 运行时 JDK 版本；若设为17，但用 JDK 11 运行，就会触发此错误（尤其涉及sealed类、record字段访问等）
排查依赖 jar 包里的类冲突
最隐蔽的来源：两个依赖引入了同一类的不同版本，且其中一个做了不兼容修改（比如 A 依赖打包了 com.example.Utils v1.2，B 依赖打包了同名类 v1.3，但 v1.3 把一个 public static 方法改成了 default 方法）。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
立即学习“Java免费学习笔记（深入）”；
- 用
javap -v查看出问题的类字节码：比如报错说class com.example.Service implements interface com.example.Task失败，就执行javap -v com.example.Service，观察interfaces:列表是否真包含该 interface - Maven 工程跑
mvn dependency:tree -Dverbose，搜关键词，看是否有重复 artifactId + 不同 version - 运行时加
-XX:+TraceClassLoading，观察类是从哪个 jar 加载的（注意日志量大，建议配合grep过滤）
增量编译 / IDE 自动构建导致的“假干净”
IDE 常默认只编译改动文件，如果改了接口定义（比如给 interface Dao 新增 default 方法），但实现类没重编译，运行时就会因实现类字节码里没有对应桥接方法而抛 IncompatibleClassChangeError。
- 遇到此类问题，先强制全量重建：IntelliJ 用
Build → Rebuild Project；Eclipse 用Project → Clean...；Maven 用mvn clean compile - 禁用 IDE 的“build on save”或“compile on fly”，改用明确的构建流程，避免隐式状态残留
- CI 流水线里务必保证
clean步骤存在，不能只靠增量编译
真正麻烦的往往不是版本号写错了，而是某次重构改了父类/接口的可见性、移除了字段、把 static final 常量改成非 final——这些变更不会报编译错误，却会在运行时让旧字节码崩溃。得盯着字节码层面看，而不是只信 IDE 的绿色对勾。
