Spring Boot WebFlux运行出现NoClassDefFoundError异常的排查咨询

1. 类加载失败的常见原因 #

• 依赖版本冲突：虽然你解压jar确认类存在，但如果依赖树中存在多个版本的netty-transport包，类加载器优先加载低版本包时就会找不到该类（该类是netty 4.1.x之后新增的）。你可以执行./gradlew dependencies | grep netty-transport检查是否存在版本不一致的情况。
• Spring Boot快照版不稳定：你使用的是2.6.0-SNAPSHOT测试版本，本身存在依赖管理缺陷的概率很高，可能导致LaunchedURLClassLoader的类搜索路径异常。
• 临时目录解压失败：Spring Boot的LaunchedURLClassLoader会将BOOT-INF/lib下的jar包解压到java.io.tmpdir指定的目录，如果你配置的tmp目录权限不足、磁盘满、或者Docker挂载的tmp目录有IO异常，会导致netty的jar解压失败，即使原包里有类也无法加载。
• JDK版本不匹配：编译用JDK15、运行用JDK16的跨大版本部署，也可能触发JDK类加载机制的兼容问题。

2. 异常捕获与优雅关闭方案 #

你配置的Thread.setDefaultUncaughtExceptionHandler不生效，是因为Netty的SingleThreadEventExecutor内部自带异常捕获逻辑，会把异常吞掉打warn日志，不会抛到线程层级的未捕获异常处理器。可以按以下方式处理：

• 自定义Netty线程工厂：在配置Reactor Netty服务器时，给EventLoopGroup指定自定义的ThreadFactory，给每个IO线程单独设置UncaughtExceptionHandler。
• 增加Netty全局异常处理器：往Netty的ChannelPipeline中添加一个全局的ChannelInboundHandlerAdapter，重写exceptionCaught方法捕获IO链路的异常。
• 优雅关闭触发：捕获到NoClassDefFoundError异常后，直接调用Spring ApplicationContext的close()方法，触发SpringBoot的优雅关闭流程：先停止端口监听、处理完已接收的请求、再销毁Bean关闭容器。

3. 后续排查方向 #

• 替换Spring Boot版本：将2.6.0-SNAPSHOT替换为同系列正式稳定版（如2.6.15），排除快照版本身的bug影响。
• 统一JDK版本：编译和运行环境都使用相同大版本的JDK，避免跨版本兼容问题。
• 开启类加载日志：启动命令中增加-XX:+TraceClassLoading -XX:+TraceClassLoadingPreorder参数，输出完整的类加载日志，确认加载ChannelInputShutdownReadComplete时的搜索路径和失败原因。
• 排查临时目录状态：监控Docker容器内tmp目录的权限、磁盘空间、inode使用率，确认没有IO异常。
• 复现验证：本地使用相同的配置启动服务，模拟高并发请求场景，尝试稳定复现问题后再定位根因。

内容的提问来源于stack exchange，提问作者Donggi Kim