1. 这个报错到底在说什么如果你在编译一个用了 Lombok 的 Java 项目时突然在堆栈里看到这么一行Caused by: java.lang.ClassNotFoundException: lombok.javac.handlers.HandleBuilderDefaultRemove第一反应大概率是懵的。ClassNotFoundException见多了但后面跟的类名是lombok.javac.handlers.HandleBuilderDefaultRemove这就有点意思了——这不是你自己写的类也不是某个第三方业务库的类而是 Lombok 自己内部的一个处理器类。先把结论摆在前面这个报错几乎百分之百是 Lombok 版本冲突或者版本不匹配导致的。具体来说是你项目里依赖的 Lombok 版本和实际参与编译的 Lombok 版本对不上或者某个依赖传递进来的 Lombok 版本太老缺少了这个类。HandleBuilderDefaultRemove这个类从名字就能猜出来它的作用处理Builder.Default注解的移除逻辑。Builder.Default是 Lombok 在 1.16.16 版本左右引入的一个特性用来给Builder生成的构建器设置默认值。如果你用的 Lombok 版本低于这个引入版本那自然就找不到这个类。所以这个报错的本质是编译期 Lombok 的注解处理器在运行时试图加载一个当前 classpath 上不存在的类。听起来绕但拆开看就清楚了。这篇文章我会从根因分析、排查思路、解决方案、版本管理、以及实际踩坑经验几个维度把这个报错彻底讲透。不管你是刚接触 Lombok 的新手还是用了好几年但一直没搞明白版本管理的老手都能从中找到可以直接抄作业的方案。2. 为什么会出现这个 ClassNotFoundException2.1 Lombok 的工作机制回顾要理解这个报错得先搞清楚 Lombok 到底是怎么工作的。很多人用了好几年 Lombok只知道加个注解就能少写代码但从来没想过它背后的原理。Lombok 的核心是一个注解处理器Annotation Processor。在 Java 编译过程中javac会扫描 classpath 上所有注册了javax.annotation.processing.Processor的处理器Lombok 就是其中之一。当编译器遇到Data、Builder、Getter这些注解时Lombok 的处理器会介入直接修改抽象语法树AST把该生成的方法塞进去。关键点来了Lombok 的处理器代码是打包在lombok.jar里的。也就是说lombok.javac.handlers.HandleBuilderDefaultRemove这个类必须存在于编译期 classpath 上的那个lombok.jar中。而HandleBuilderDefaultRemove这个类是在 Lombok 处理Builder.Default时被调用的。如果你的代码里用了Builder.Default但 classpath 上的 Lombok 版本太老没有这个类那编译器在运行到这一步时就会抛出ClassNotFoundException。2.2 版本冲突的三种典型场景根据我这些年排查这类问题的经验版本冲突基本逃不出下面三种情况第一种显式依赖版本过低。你的pom.xml或build.gradle里直接写了 Lombok 的版本但这个版本比较老比如 1.16.14 之前的版本。而你的代码里用了Builder.Default或者某个依赖库的代码里用了这个注解。编译时自然找不到对应的处理器类。第二种传递依赖引入了老版本。这种情况最隐蔽。你自己没直接声明 Lombok或者声明了一个新版本但项目里某个第三方库比如某个工具包、某个框架的 starter在它的依赖树里传递进来了一个老版本的 Lombok。Maven 或 Gradle 的依赖仲裁机制可能会选择那个老版本导致最终参与编译的 Lombok 版本低于预期。第三种IDE 与构建工具版本不一致。这个坑我踩过不止一次。命令行mvn clean compile能过但 IDE 里编译就报这个错。原因通常是 IDE 有自己的注解处理器配置或者 IDE 缓存了一个旧版本的 Lombok 插件。IDE 用的 Lombok 版本和 Maven 依赖里的版本不是同一个。2.3 为什么偏偏是 HandleBuilderDefaultRemove你可能会问Lombok 内部类那么多为什么偏偏这个类找不到因为Builder.Default这个特性比较特殊。它是在 Lombok 1.16.16 才引入的而且它的处理逻辑需要单独一个处理器类来负责。在老版本里Builder是有的但Builder.Default没有。所以当你升级了代码用了新注解但没有升级 Lombok 版本时编译器能找到HandleBuilder但找不到HandleBuilderDefaultRemove。这就好比你去一家老餐馆点菜菜单上新增了一道菜但厨房里没有对应的厨师。菜单你的代码有了厨师Lombok 处理器类没到位自然就出错了。3. 排查这个问题的完整思路3.1 第一步确认 Lombok 的实际版本排查任何依赖问题第一步永远是搞清楚实际生效的版本是什么而不是你以为的版本。Maven 项目用这个命令mvn dependency:tree -Dincludesorg.projectlombok:lombokGradle 项目用这个gradle dependencies --configuration compileClasspath | grep lombok或者更直接一点看看编译期 classpath 上到底加载的是哪个 jarmvn dependency:build-classpath -Dmdep.outputFilecp.txt然后打开cp.txt搜索lombok看看路径里的版本号是多少。注意不要只看pom.xml里写的版本。Maven 的依赖仲裁nearest-wins 策略可能会让你声明的版本被覆盖。一定要看依赖树或者实际 classpath。3.2 第二步确认代码里是否用了 Builder.Default有时候报错不是你的代码直接触发的而是某个依赖库的代码里用了Builder.Default。这种情况下你甚至不知道自己的项目里有人用了这个注解。全局搜索一下grep -r Builder.Default src/如果自己的代码里没有那就得考虑是不是依赖库的问题。可以看看报错的完整堆栈找到是哪个类在编译时触发了这个处理器。3.3 第三步检查 IDE 的注解处理器配置如果你在命令行能编译通过但 IDE 里报错那问题大概率出在 IDE 配置上。以 IntelliJ IDEA 为例检查这几个地方Settings Build, Execution, Deployment Compiler Annotation Processors确认注解处理是开启的。Settings Build, Execution, Deployment Compiler Java Compiler看看Use compiler选的是 Javac 还是 Eclipse。检查 IDEA 的 Lombok 插件版本确保它和项目依赖的 Lombok 版本兼容。Eclipse 的话检查.factorypath文件和项目的 Annotation Processing 配置。3.4 第四步查看完整的异常堆栈不要只看Caused by那一行往上翻看看是什么操作触发了这个类加载。完整的堆栈会告诉你是哪个注解处理器在调用这个类是编译哪个源文件时出的错调用链是什么样的这些信息能帮你定位到具体的触发点。4. 解决方案从根上解决版本冲突4.1 方案一统一升级 Lombok 版本推荐最直接的办法就是把 Lombok 升级到一个足够新的版本。Builder.Default从 1.16.16 开始支持但建议直接用较新的稳定版比如 1.18.x 系列。Maven 配置dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version1.18.30/version scopeprovided/scope /dependencyGradle 配置compileOnly org.projectlombok:lombok:1.18.30 annotationProcessor org.projectlombok:lombok:1.18.30注意 Gradle 里要同时声明compileOnly和annotationProcessor只写一个可能会出问题。提示升级 Lombok 版本后记得清理 IDE 缓存并重新导入项目。IDEA 里用File Invalidate Caches and RestartEclipse 里清理项目并重新构建。4.2 方案二强制指定版本覆盖传递依赖如果升级不了比如公司有版本管控或者传递依赖里有个老版本在捣乱可以用依赖管理强制指定版本。Maven 的dependencyManagementdependencyManagement dependencies dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version1.18.30/version /dependency /dependencies /dependencyManagement或者用exclusions排除传递进来的老版本dependency groupId某个依赖/groupId artifactId某个artifact/artifactId exclusions exclusion groupIdorg.projectlombok/groupId artifactIdlombok/artifactId /exclusion /exclusions /dependencyGradle 里可以用resolutionStrategyconfigurations.all { resolutionStrategy { force org.projectlombok:lombok:1.18.30 } }4.3 方案三移除 Builder.Default 或改用其他写法如果实在没法升级 Lombok那就只能改代码避开Builder.Default。原来的写法Builder public class User { Builder.Default private String name default; }改成手动在构建器里处理默认值Builder public class User { private String name; public static class UserBuilder { private String name default; } }或者干脆不用Builder.Default在构建器的build()方法里做默认值处理。注意这种方案只是权宜之计长期来看还是应该升级 Lombok。因为Builder.Default是个很实用的特性放弃它会让代码变得啰嗦。4.4 方案四检查并统一 IDE 与构建工具的版本如果命令行能过、IDE 报错那就要统一两边的版本。IDEA 里检查Settings Build, Execution, Deployment Build Tools Maven Runner看看Use project settings是否勾选。然后检查 Maven 的settings.xml里有没有配置全局的 Lombok 版本。另外IDEA 的 Lombok 插件也要更新到最新版。插件版本太老可能不认识新版本 Lombok 的某些类。Eclipse 的话检查.factorypath文件里的 Lombok jar 路径确保它指向的是正确版本。5. 版本对照与参数说明5.1 Lombok 版本与特性对照表Lombok 版本关键特性是否支持 Builder.Default1.16.14 及之前基础注解否1.16.16引入 Builder.Default是1.18.0支持 JDK 9是1.18.10支持 JDK 11是1.18.20支持 JDK 16是1.18.30支持 JDK 21是从表里可以清楚看到Builder.Default是 1.16.16 引入的。如果你的 Lombok 版本低于这个就会报ClassNotFoundException。5.2 JDK 版本与 Lombok 版本的兼容性这里有个容易被忽略的点Lombok 版本和 JDK 版本也有兼容性要求。JDK 版本最低 Lombok 版本JDK 81.16.xJDK 111.18.4JDK 171.18.22JDK 211.18.30如果你用的是 JDK 17但 Lombok 版本只有 1.18.10那即使版本高于 1.16.16也可能因为 JDK 兼容性问题导致各种奇怪的报错。所以升级 Lombok 时要同时考虑 JDK 版本。5.3 Maven 依赖仲裁规则说明Maven 的依赖仲裁用的是nearest-wins策略如果同一个依赖在依赖树的不同层级出现Maven 会选择层级最浅的那个版本。举个例子项目 ├── lombok:1.18.30 (直接依赖层级1) └── 某个库 └── lombok:1.16.14 (传递依赖层级2)这种情况下Maven 会选择 1.18.30因为它的层级更浅。但如果情况反过来项目 ├── 某个库 │ └── lombok:1.16.14 (传递依赖层级2) └── lombok:1.18.30 (直接依赖层级1)Maven 还是会选 1.18.30因为直接依赖的层级是 1比传递依赖的层级 2 更浅。真正会出问题的是这种情况项目 ├── 库A │ └── lombok:1.16.14 (层级2) └── 库B └── lombok:1.18.30 (层级2)两个都是层级 2Maven 会选择先声明的那个。如果库A先声明那就会选 1.16.14导致报错。这就是为什么有时候你明明在pom.xml里写了新版本但实际生效的还是老版本。解决办法就是用dependencyManagement强制指定或者用exclusions排除掉老版本。6. 实操过程与验证步骤6.1 完整的排查与修复流程下面是我在实际项目中处理这个问题的标准流程你可以直接照着做。第一步确认报错先看完整的异常堆栈确认是ClassNotFoundException: lombok.javac.handlers.HandleBuilderDefaultRemove。第二步查看依赖树mvn dependency:tree -Dincludesorg.projectlombok:lombok -Dverbose-Dverbose会显示被忽略的依赖能看到哪些版本被仲裁掉了。第三步确认实际版本mvn dependency:build-classpath -Dmdep.outputFilecp.txt cat cp.txt | tr : \n | grep lombok看看输出的路径里Lombok 的版本号是多少。第四步修改配置在pom.xml里添加或修改 Lombok 依赖指定一个足够新的版本。同时用dependencyManagement锁定版本。第五步清理并重新编译mvn clean compile如果还有问题加上-U强制更新依赖mvn clean compile -U第六步验证编译通过后再跑一下测试mvn test确保没有其他隐藏问题。6.2 Gradle 项目的处理方式Gradle 的依赖管理逻辑和 Maven 不太一样默认用的是highest-wins策略同一个依赖出现多个版本时选最高的那个。这听起来好像不会出问题但实际上 Gradle 的annotationProcessor配置和compileOnly配置是分开的。如果annotationProcessor里引入了一个老版本而compileOnly里是新版本编译时用的还是老版本。所以 Gradle 项目里要确保这两个配置用的是同一个版本configurations.all { resolutionStrategy { force org.projectlombok:lombok:1.18.30 } } dependencies { compileOnly org.projectlombok:lombok:1.18.30 annotationProcessor org.projectlombok:lombok:1.18.30 testCompileOnly org.projectlombok:lombok:1.18.30 testAnnotationProcessor org.projectlombok:lombok:1.18.30 }提示测试代码也要加上 Lombok 的注解处理器配置否则测试编译时可能报同样的错。6.3 IDE 缓存的清理方法改完依赖后IDE 缓存经常还在捣乱。不同 IDE 的清理方式IntelliJ IDEAFile Invalidate Caches and Restart然后Build Rebuild Project如果还不行删除.idea目录和*.iml文件重新导入项目EclipseProject Clean右键项目 Maven Update Project检查.factorypath文件确保 Lombok 路径正确VS Code清理 Java 语言服务器的缓存重新加载窗口7. 常见问题与排查技巧实录7.1 常见问题速查表问题现象可能原因解决方法命令行能编译IDE 报错IDE 缓存或插件版本问题清理 IDE 缓存更新 Lombok 插件升级 Lombok 后仍报错传递依赖里有老版本用 dependencyManagement 强制指定只有某个模块报错该模块的依赖配置不同检查该模块的 pom.xml 或 build.gradle测试编译时报错测试配置里没加 Lombok添加 testAnnotationProcessor 配置换 JDK 后报错Lombok 版本与 JDK 不兼容升级 Lombok 到兼容版本7.2 独家避坑技巧技巧一用 enforcer 插件防止版本冲突。Maven 的maven-enforcer-plugin可以在构建时检查依赖版本如果发现不符合要求的版本就直接失败避免问题流到运行时。plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-enforcer-plugin/artifactId version3.4.1/version executions execution idenforce-lombok-version/id goals goalenforce/goal /goals configuration rules requireUpperBoundDeps excludes excludeorg.projectlombok:lombok/exclude /excludes /requireUpperBoundDeps /rules /configuration /execution /executions /plugin技巧二在父 POM 里统一管理 Lombok 版本。如果是多模块项目在父 POM 的dependencyManagement里锁定 Lombok 版本子模块只需要声明依赖不需要写版本号。这样能避免各模块版本不一致。技巧三定期检查依赖树。不要等到出问题了才去看依赖树。可以在 CI 流程里加一步定期输出依赖树发现版本冲突及时处理。技巧四注意 Lombok 的 scope。Lombok 的 scope 应该是provided因为它只在编译期需要运行期不需要。如果 scope 写成了compile打包时会把 Lombok 打进 jar 里虽然不一定会报错但会增加包体积而且可能引起其他问题。7.3 一个真实的排查案例之前有个项目用的是 Spring Boot 2.xJDK 11Lombok 版本在pom.xml里写的是 1.18.10。代码里用了Builder.Default命令行编译没问题但 CI 上偶尔会报ClassNotFoundException。排查过程先看依赖树发现有个内部工具包传递进来了 Lombok 1.16.14。因为两个版本在依赖树里的层级相同Maven 按声明顺序选了 1.16.14。本地开发时IDE 用的是 1.18.10IDEA 插件版本所以没问题。CI 上用纯 Maven 构建就选了 1.16.14导致报错。解决办法在dependencyManagement里强制指定 1.18.30并在内部工具包里排除 Lombok 依赖。这个案例告诉我们本地能过不代表 CI 能过IDE 能过不代表命令行能过。排查这类问题时一定要以命令行的构建结果为准。8. 版本管理的最佳实践8.1 统一版本管理策略对于多模块项目建议在父 POM 里统一管理 Lombok 版本properties lombok.version1.18.30/lombok.version /properties dependencyManagement dependencies dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId version${lombok.version}/version scopeprovided/scope /dependency /dependencies /dependencyManagement子模块里只需要dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId /dependency这样版本号只在一个地方维护升级时改一处就行。8.2 与 JDK 版本的协同升级Lombok 版本和 JDK 版本要协同升级。升级 JDK 时先确认 Lombok 版本是否兼容。可以参考前面的兼容性表格。如果项目要从 JDK 8 升级到 JDK 17建议先把 Lombok 升级到 1.18.22 以上再升级 JDK。这样能避免升级过程中出现各种奇怪的编译错误。8.3 CI 流程中的版本检查在 CI 流程里加一步依赖检查能提前发现问题mvn dependency:tree -Dincludesorg.projectlombok:lombok如果输出的版本和预期不符就让构建失败。这样能在代码合并前就发现版本冲突而不是等到运行时才报错。9. 我个人的一些经验体会这个ClassNotFoundException看起来是个小问题但背后反映的是 Java 项目依赖管理的复杂性。我这些年处理过无数次类似的问题总结下来有几点体会。第一永远不要相信你以为的版本。pom.xml里写的版本、IDE 显示的版本、实际编译用的版本可能是三个不同的东西。排查问题时一定要用dependency:tree和build-classpath确认实际生效的版本。第二Lombok 的版本升级要谨慎但及时。Lombok 是个很特殊的库它直接操作编译器内部 API所以和 JDK 版本的耦合很紧。JDK 升级时Lombok 往往是最先出问题的依赖之一。建议在项目里保持 Lombok 版本相对较新不要落后太多。第三多模块项目的版本管理要统一。我见过太多项目各个模块的 Lombok 版本不一样导致编译时好时坏。用父 POM 统一管理能省掉很多麻烦。第四IDE 和命令行的构建结果要一致。如果两边不一致说明配置有问题。不要觉得 IDE 能过就行了CI 上用的是命令行构建最终交付的也是命令行的产物。最后分享一个小技巧如果你不确定某个 Lombok 版本是否包含某个类可以直接解压lombok.jar看看里面的lombok/javac/handlers/目录下有没有对应的 class 文件。这比查文档快多了。unzip -l lombok-1.18.30.jar | grep HandleBuilderDefault如果输出里有HandleBuilderDefaultRemove.class说明这个版本支持Builder.Default。如果没有那就得升级。这个内容后续还可以这样扩展如果你用的是 Kotlin 或 Scala 项目Lombok 的配置方式会有所不同需要单独处理。另外如果项目里用了 MapStruct 这类也依赖注解处理器的库要注意它们和 Lombok 的处理器顺序顺序不对也可能导致编译问题。