1. 先把这个错误读明白，别急着加依赖

java.lang.NoClassDefFoundError: io/netty/channel/EventLoopGroup这个报错，我在过去几年的项目里遇到过不下十次，每次的场景都不一样：有的是依赖被 exclude 掉了，有的是两个版本的 Netty 打架，有的是打包插件把类漏了，还有一次是应用服务器自带的 Netty 和业务包里的是两个世界。所以看到这行日志的第一反应不应该是"哦，缺 Netty，加个 netty-all 就行"，而是先问自己：它到底是"根本没有这个类"，还是"有但加载失败了"？

先把结论摆在这儿：EventLoopGroup是 Netty 事件驱动模型的总入口，位于io.netty.channel包，属于netty-transport这个模块。任何依赖 Netty 做网络通信的组件——响应式 Web 服务、RPC 框架客户端、消息队列客户端、缓存客户端、搜索引擎客户端——启动时几乎都会碰到它。所以这个错误的本质不是"Netty 有问题"，而是你当前的运行时类路径，和某个组件预期的类路径对不上。

这篇文章适合三类人看：第一类是被这行堆栈卡住、想快速定位的初中级开发；第二类是负责打包和部署、需要理解构建产物为什么会丢类的工程同学；第三类是正在做依赖治理、想从根上避免这类问题反复出现的技术负责人。全文按"读懂错误 → 找原因 → 上手排查 → 分场景解决 → 速查表"的顺序展开，每一步都给出可以直接复制的命令和配置。

1.1 NoClassDefFoundError 和 ClassNotFoundException 根本不是一回事

很多人把这两个混着用，其实它们在 JVM 里走的是两条完全不同的路径，排查方向也完全不同。

ClassNotFoundException是显式加载时抛的。你写Class.forName("io.netty.channel.EventLoopGroup")或者用ClassLoader.loadClass(...)，类路径里翻遍了没找到，就抛这个。它通常意味着"依赖确实没进到运行时"。

NoClassDefFoundError则是隐式加载时抛的。编译器在编译你的代码时是能找到这个类的，字节码里留下了符号引用，等到运行时第一次真正要用它了（new 实例、调静态方法、甚至只是解析常量池），JVM 去加载，结果拿不到，才抛这个 Error。它有两个子情况：

• 类文件压根不存在：和 ClassNotFoundException 的根因一样，只是触发路径不同。
• 类文件存在，但链接或初始化失败：比如静态初始化块抛了异常、依赖的上游类缺失、<clinit>执行出错。这种在日志里往往会看到Caused by: java.lang.ExceptionInInitializerError或者Caused by: java.lang.NoClassDefFoundError: Could not initialize class io.netty.util.internal.PlatformDependent。

注意：如果你的堆栈里出现的是Could not initialize class，那就不要再往依赖方向上找了，问题在初始化阶段，通常是环境或 JDK 版本不兼容，方向完全不一样。

区分这两种情况最土也最有效的办法，是看堆栈里NoClassDefFoundError后面跟的类名到底是不是EventLoopGroup本身。如果是io/netty/channel/EventLoopGroup（带斜杠，说明是内部表示），那是类缺失；如果是某个io.netty.util.internal.xxx或者io/netty/channel/xxx$1之类的伴生类，那多半是初始化链路上出了问题。

1.2 为什么偏偏是 EventLoopGroup 第一个倒下

Netty 的设计是一个典型的"入口类极早被触碰"的结构。EventLoopGroup是Bootstrap.group(...)的参数类型，任何客户端或服务端在构建启动器的时候都会第一时间引用它。而EventLoopGroup的具体实现NioEventLoopGroup、EpollEventLoopGroup又会反向依赖netty-transport、netty-common、netty-buffer、netty-resolver这一整条链。

这就导致一个很典型的表象：你其实缺的是netty-common或者netty-transport，但报错却指向EventLoopGroup。因为 JVM 的类加载是按需触发的，EventLoopGroup恰好是第一个被触碰到的类，它倒了，后面的一串自然没机会浮出水面。

更麻烦的是，EventLoopGroup在 Netty 4.0 和 4.1 里的全限定名是完全一样的，包名、类名都没变。所以当你看到这个错误时，有一种可能是：类路径里其实有io.netty.channel.EventLoopGroup，只是它来自 4.0 的 jar，而你用的框架（比如某个新版本的响应式客户端）是按 4.1 的 API 编译的，方法签名对不上，最终以NoSuchMethodError或者NoClassDefFoundError的形式爆出来。这个坑我在一个老项目升级时踩过，花了整整一个下午。

2. 五类诱因，覆盖九成以上的现场

我把这些年遇到的案例归了归类，基本都落在这五个筐里。你可以对照着自己项目的特征先做一轮粗筛，能省掉很多盲目试错。

2.1 依赖压根没进来：exclude、provided、optional 三兄弟

最常见的一种。表现形式是mvn dependency:tree里根本搜不到io.netty相关的条目，或者只搜到一个残缺的模块。

三种典型操作会导致这个结果：

• 全局 exclude。有些团队为了"瘦身"，在父 POM 里对着某个 starter 一顿exclusions，把netty-common、netty-transport一起排掉了，结果主业务没事，某个边缘功能启动就炸。
• scope 是 provided。provided的含义是"编译要用，运行时由容器提供"。本地 IDE 跑单测时因为带了编译类路径，一切正常；打到服务器上，容器里要是没这个包，就是标准的 NoClassDefFoundError。
• optional 是 true。Maven 的optional只影响传递依赖，不买这个账的下游项目拿不到它。如果你的项目依赖了中间件 A，A 把 Netty 标成 optional，那你自己的项目就必须显式声明 Netty，否则一定缺。

这三类有个共同特征：本地跑得通，换环境就崩。所以只要你的报错是"开发环境正常、测试/生产环境异常"，优先查这一条。

2.2 版本打架：4.0 和 4.1 在同一个类路径里共存

Netty 的版本兼容性是个老话题。4.0 和 4.1 的包名完全一致，类名基本一致，但内部实现和部分 API 签名有差异。当两个版本的 jar 同时出现在WEB-INF/lib或者 fat jar 里时，JVM 按类路径顺序取第一个匹配的，另一个就成了幽灵。

这种情况下报错会很飘：有时是NoSuchMethodError，有时是NoClassDefFoundError，有时是LinkageError，取决于哪个版本的类先被加载、以及调用方的期望是什么。

还有一种更隐蔽的版本冲突：netty-all和分模块依赖（netty-transport、netty-handler等）混用。netty-all在 4.1.x 的某些版本里是一个只含 META-INF 的聚合包，靠netty-bom里的分模块拼起来；而在更早的版本里它是真的把 class 打进去的。如果你一边引netty-all一边引netty-transport:4.1.xx，就可能出现类重复但版本不同的情况。

判断方法很简单：mvn dependency:tree -Dincludes=io.netty看到两个及以上不同版本号，基本就实锤了。

2.3 类加载器隔离：容器、插件、热部署的三重门

这一类最难查，因为依赖树看起来完美无缺，dependency:tree干净得挑不出毛病，但运行就是不行。

典型的场景有这么几个：

• 应用服务器自带 Netty。某些 Java EE 容器或者中间件的 lib 目录里躺着一个老版本 Netty，父类加载器优先加载了它，而你的应用包里的新版本被"遮蔽"了。父加载器加载的EventLoopGroup与子加载器里框架期望的版本不匹配。
• 插件化架构。主程序和插件各有一套类加载器，插件里引用的EventLoopGroup来自主程序的加载器，但插件自己的依赖树里又有另一份，两个世界互不相认。
• 热部署。开发阶段改代码触发热重载，旧的类加载器没被回收，新的又建了一个，静态变量和类身份出现分裂。
• OSGi。Bundle 之间的 import/export 配置没写全，io.netty.channel这个包没被正确导出，运行时就是找不到。

判断这一类问题，光看依赖树没用，必须在运行时打印类的实际来源（下一章给代码）。

2.4 打包环节：fat jar 的索引、重复条目与签名

本地 IDE 里一切正常，mvn package之后跑就崩——这个特征几乎百分百指向打包。

常见的几个坑：

• maven-shade-plugin没配ServicesResourceTransformer。Netty 和一些框架依赖META-INF/services下的 SPI 文件，多个 jar 的同名文件在 shade 合并时默认是"后来的覆盖先来的"，直接导致某些 Provider 找不到。虽然这个通常不表现为EventLoopGroup缺失，但会连带引发一系列初始化失败。
• 签名文件冲突。第三方 jar 被重新打包后，META-INF/*.SF、META-INF/*.RSA还留着，但内容已经对不上了，JVM 校验时抛SecurityException，有时会被包装成类加载失败。用 shade 时应该显式过滤掉这些文件。
• 重复类条目。两个 jar 里有同名 class，打包工具合并策略不同，可能保留了空壳或者损坏的字节码。
• spring-boot-maven-plugin的includes/excludes。有些人为了减小包体积配置了排除规则，正则写得宽了一点，把netty-*也顺带排掉了。

我遇到过一次特别离谱的：某同学在打包脚本里写了个rm -rf target/classes/io，本意是清理旧产物，结果把编译生成的包目录也删了。这种低级错误说出来丢人，但确实发生过。

2.5 JDK 版本与 Netty 版本的隐性不兼容

这个坑最近两年变多了。Netty 4.1 的早期版本在 JDK 17 上跑，会因为反射访问sun.misc.Unsafe或者内部 API 触发模块系统限制，PlatformDependent的静态初始化失败，最终以NoClassDefFoundError: Could not initialize class io.netty.util.internal.PlatformDependent的形式呈现。

这种情况下你加再多依赖都没用，因为类是在的，只是初始化挂了。解决办法是升级 Netty 到较新的 4.1.x 版本，或者在启动参数里加--add-opens系列开关（不推荐作为长期方案）。

还有一个变种：JDK 21 的虚拟线程和某些老版本 Netty 的FastThreadLocal有交互问题，虽然不直接报这个错，但会以其他形式影响启动。

3. 排查链路：从堆栈一步步走到根因

排查这类问题，我有一套固定的动作序列，按顺序走基本十分钟内能定位。

3.1 先读堆栈的第二行和所有 Caused by

很多人只看第一行NoClassDefFoundError: io/netty/channel/EventLoopGroup就开始搜，其实信息量最大的是后面几行。

要重点看三处：

1. 抛出位置。第一个业务栈帧是哪个类？是Bootstrap、NioEventLoopGroup，还是某个框架的ClientFactory？这决定了是谁在要这个类。
2. Caused by链。如果第一层是EventLoopGroup，往下翻通常会看到NoClassDefFoundError: io/netty/util/concurrent/EventExecutorGroup或者Could not initialize class。往下深挖一层，真正的缺失类才会露出来。
3. ClassLoader信息。有些框架会打印failed to load class ... from ClassLoader [xxx]，这个xxx是定位类加载器问题的关键。

提示：如果日志被日志框架截断或者刷屏了，用grep -A 30 "NoClassDefFoundError" app.log把完整堆栈捞出来，别只看控制台那几行。

3.2 依赖树过滤，五秒钟看出有没有

Maven 项目：

mvn dependency:tree -Dincludes=io.netty:* -Dverbose

-Dverbose会把被省略的冲突节点也打出来，能看到(version omitted for conflict with 4.1.100.Final)这类标注。

Gradle 项目：

./gradlew dependencies --configuration runtimeClasspath | grep -A 5 netty

或者更精准：

./gradlew dependencyInsight --dependency netty-transport --configuration runtimeClasspath

看的结果要关注三件事：

• io.netty:netty-transport在不在。不在就是 2.1 的情况。
• 版本号是不是同一个。不一致就是 2.2 的情况。
• 有没有(omitted)或者->符号。Gradle 的->表示版本被强制解析了，要确认解析结果是不是你想要的。

我自己习惯再加一句：

mvn dependency:tree -Dincludes=io.netty:* -DoutputFile=netty-tree.txt

输出到文件里慢慢看，比在终端翻页舒服。

3.3 直接翻构建产物，眼见为实

依赖树再干净，也不代表打出来的包里真的有这个 class。我习惯直接掀开盖子看：

# 看 jar 里有没有这个类 unzip -l your-app.jar | grep "io/netty/channel/EventLoopGroup" # Spring Boot fat jar 要往里再翻一层 unzip -l your-app.jar | grep "BOOT-INF/lib/netty"

如果是 Spring Boot 的 fat jar，BOOT-INF/lib/下面应该能看到netty-transport-4.1.xx.Final.jar、netty-common-4.1.xx.Final.jar等一串。如果只有一个netty-common，那问题就清楚了。

解压出来再确认一次类是否真的在里面：

unzip -p your-app.jar BOOT-INF/lib/netty-transport-4.1.100.Final.jar > /tmp/nt.jar jar tf /tmp/nt.jar | grep EventLoopGroup

正常应该输出：

io/netty/channel/EventLoopGroup.class

看到.class结尾，说明类在。如果 jar 里的条目是.class但你解压出来是 0 字节，那是打包损坏，得重新打。

3.4 运行时反查：类到底从哪来的

依赖树和 jar 包都没问题，那就要在运行现场取证了。有两个手段，一个轻量一个重量。

轻量方案，在报错之前插一段诊断代码：

public class NettyProbe { public static void main(String[] args) throws Exception { String target = "io.netty.channel.EventLoopGroup"; ClassLoader cl = Thread.currentThread().getContextClassLoader(); System.out.println("TCCL = " + cl); // 用 resource 方式查，不会触发类初始化 java.net.URL url = cl.getResource(target.replace('.', '/') + ".class"); System.out.println("resource = " + url); // 再确认一次能否加载 try { Class<?> c = Class.forName(target, false, cl); System.out.println("loaded from = " + c.getProtectionDomain() .getCodeSource().getLocation()); System.out.println("classloader = " + c.getClassLoader()); } catch (Throwable t) { t.printStackTrace(); } } }

注意Class.forName的第二个参数传false，只加载不初始化，避免因为静态块炸掉而干扰判断。

重量方案是用诊断工具在线捞。Arthas 这类的sc命令非常直观：

sc -d io.netty.channel.EventLoopGroup

会打印出类的加载器、代码来源 jar、是否被加载等一堆信息。如果同一个类被两个加载器各加载了一份，sc会列出多条，这个信息价值极高。

JVM 自带的手段也可以，启动时加-verbose:class，然后在输出里 grep：

java -verbose:class -jar app.jar 2>&1 | grep EventLoopGroup

会看到类似[Loaded io.netty.channel.EventLoopGroup from file:/app/lib/netty-transport-4.1.100.Final.jar]的记录，来源一目了然。

4. 分场景解决：能抄的配置我都写出来

定位到原因之后，解决方案其实不多，但每个都要用对地方。

4.1 场景一：依赖缺失，显式补齐并锁版本

如果是 2.1 那种情况，最直接的办法就是显式声明。这里有个关键选择：用netty-all还是用分模块？

我的建议是优先分模块。理由很实在：netty-all会把 codec、handler、transport-native 之类全拉进来，体积大不说，还容易和框架自己引的分模块版本打架。你只需要用到什么就引什么。

一个典型的响应式 HTTP 客户端场景，最小集是这样的：

<properties> <netty.version>4.1.100.Final</netty.version> </properties> <dependencies> <dependency> <groupId>io.netty</groupId> <artifactId>netty-transport</artifactId> <version>${netty.version}</version> </dependency> <dependency> <groupId>io.netty</groupId> <artifactId>netty-common</artifactId> <version>${netty.version}</version> </dependency> <dependency> <groupId>io.netty</groupId> <artifactId>netty-buffer</artifactId> <version>${netty.version}</version> </dependency> <dependency> <groupId>io.netty</groupId> <artifactId>netty-handler</artifactId> <version>${netty.version}</version> </dependency> </dependencies>

四个模块的依赖关系是：netty-transport依赖netty-buffer和netty-resolver；netty-buffer依赖netty-common；netty-handler依赖netty-transport和netty-codec。所以实际上只显式引netty-handler一个，其他的会被传递带进来。但我在实际项目里还是习惯把netty-transport和netty-common也写上，因为这两个最容易被上游的 exclude 顺手排掉，写死了更稳。

如果你确实想图省事，netty-all也能用，但一定要配合下面的 BOM 方案，别让版本漂移。

4.2 场景二：版本漂移，用 BOM 一锤定音

解决版本冲突，Maven 里最干净的做法是dependencyManagement引入 BOM。Netty 官方提供netty-bom，Spring Boot 2.3 之后也内置了对它的管理。

<dependencyManagement> <dependencies> <dependency> <groupId>io.netty</groupId> <artifactId>netty-bom</artifactId> <version>4.1.100.Final</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

加了这段之后，下面所有io.netty:*的依赖都不需要写<version>，统一按 BOM 走。这个做法的好处是：即使某个传递依赖里写着 4.0.x，也会被强制解析到 4.1.100。

但要注意，BOM 只解决"版本统一"，不解决"两个大版本 API 不兼容"。如果某个老组件确实是按 4.0 编译的，硬拉 4.1 可能会出NoSuchMethodError。这种情况下的正确做法是升级那个组件，或者用下一节的 shade 隔离。

Gradle 那边对应的写法是：

dependencies { implementation platform('io.netty:netty-bom:4.1.100.Final') implementation 'io.netty:netty-handler' }

再加上一条强制规则兜底：

configurations.all { resolutionStrategy { force 'io.netty:netty-transport:4.1.100.Final' force 'io.netty:netty-common:4.1.100.Final' } }

force是核武器，能解决一切版本漂移，但也可能掩盖真正的兼容性问题，慎用，用了要在注释里写清楚为什么。

4.3 场景三：确实需要共存，用 shade 重定位隔离

如果你的应用里真的有两个组件，一个必须 4.0 一个必须 4.1，那唯一干净的办法是把其中一个的 Netty 重定位到私有包名。

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <version>3.5.1</version> <executions> <execution> <phase>package</phase> <goals><goal>shade</goal></goals> <configuration> <relocations> <relocation> <pattern>io.netty</pattern> <shadedPattern>com.myapp.shaded.io.netty</shadedPattern> </relocation> </relocations> <transformers> <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/> <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> <mainClass>com.myapp.Main</mainClass> </transformer> </transformers> <filters> <filter> <artifact>*:*</artifact> <excludes> <exclude>META-INF/*.SF</exclude> <exclude>META-INF/*.DSA</exclude> <exclude>META-INF/*.RSA</exclude> </excludes> </filter> </filters> </configuration> </execution> </executions> </plugin>

这里有三个细节必须注意：

• ServicesResourceTransformer不能省。Netty 的部分功能靠 SPI 加载，shade 合并时如果不做 service 文件合并，运行时会静默丢功能。
• 签名文件必须排除。上面filters那段就是干这个的，不排除会在启动时抛SecurityException。
• 重定位只对被打进 jar 的依赖生效。如果你的 Netty 来自provided，shade 管不着，那条路得走容器层面的类加载器隔离。

重定位之后，jar 体积会变大，但两个版本能和平共处，这是唯一可靠的共存方案。

4.4 场景四：容器与插件环境，处理类加载器优先级

如果确认是 2.3 那种父加载器遮蔽的问题，解决思路是让应用自己的类加载器优先，或者把冲突的包彻底隔离。

具体做法取决于容器，这里只能给通用思路：

• 确认父加载器里到底有没有。在启动脚本里加-verbose:class，看EventLoopGroup是从容器的 lib 加载的还是从应用的 lib 加载的。
• 配置类加载委托顺序。很多容器支持"子优先"（child-first）配置，让WEB-INF/lib优先于容器 lib。这个配置项名字各容器不同，需要查对应容器的部署描述符。
• 实在不行就升级或移除冲突包。如果容器自带的是 Netty 4.0，而你的应用必须用 4.1，最稳的做法是把应用打成独立进程部署，不依赖容器的类加载体系。

插件化架构的话，思路类似：确保插件的类加载器能正确委托到主程序，同时插件自己的依赖里不要重复打包 Netty。这个在pom.xml里用provided声明就行。

4.5 场景五：打包产物有问题，重新配置构建

如果确认是 2.4 那种打包问题，动作就很明确了：

• Spring Boot 项目检查spring-boot-maven-plugin的排除配置，确认没有误伤netty-*。
• 确认repackage生效。有些人在pom.xml里把spring-boot-maven-plugin的repackagegoal 去掉了，打出来的是普通 jar，java -jar一跑就缺依赖。
• 多模块项目检查模块间的依赖声明。子模块引用了父模块的类但没声明依赖，IDE 里能跑是因为整个 reactor 在一起，单独打包就缺。
• Docker 镜像检查多阶段构建。COPY --from=builder /app/target/*.jar这种写法如果匹配到多个 jar，会 COPY 失败或者 COPY 错，要写清楚文件名。

打包问题的验证手段很简单：把构建产物单独拷到一个干净目录，用java -jar跑一遍。IDE 能跑不代表产物能跑，这一步不能省。

5. 哪些技术栈最爱踩这个坑

了解了通用解法，再说几个高频场景。知道自己在哪个场景里，排查速度能快一倍。

5.1 响应式 Web 服务端

基于事件循环的 Web 框架，启动时第一件事就是创建EventLoopGroup。如果用了某个 starter 又把它依赖的 Netty 排掉了，启动直接挂。

这个场景的特征是：报错发生在main线程，堆栈很短，就两三行。因为是在SpringApplication.run的早期阶段失败的。

排查重点就一条：检查那个 starter 的传递依赖里有没有netty-handler或者netty-transport。有的话，看是不是被上面某个exclusion干掉了。

还有一种情况是混用两种 Web 容器。项目里同时引了 Tomcat 和响应式容器，Spring Boot 会按优先级选一个，但如果选中的那个缺 Netty，或者选中的是 Tomcat 而某个组件又硬要 Netty，就会出现这种矛盾。

5.2 RPC 与消息中间件客户端

这类客户端几乎百分百依赖 Netty。它们的特点是：启动时不一定报错，第一次真正发起调用才炸。

因为很多框架做了懒初始化，EventLoopGroup在第一次建立连接时才创建。所以你在本地启动一切正常，压测或者联调时突然报这个错。

这类场景下要特别注意provided的作用域。有些中间件客户端为了减小体积，把 Netty 标成provided，期待用户自己提供。这时候报错就是提醒你：该显式声明了。

5.3 缓存与搜索客户端

缓存客户端和搜索引擎的 Java 客户端，内部都用 Netty 做连接池。它们的版本通常和 Netty 绑得比较死，比如某个客户端版本只能配 4.1.x 的特定区间。

这类场景的典型特征是：依赖树里有 Netty，但版本被另一个组件拉低了。比如你引了三个客户端，各自的传递依赖分别指向 4.1.50、4.1.63、4.1.100，Maven 按"最短路径优先"选了 4.1.50，而最新的那个客户端需要 4.1.63 以上的 API。

解决办法就是 4.2 节的 BOM，把所有版本统一到较高那个。但如果低版本客户端在新 Netty 上有兼容问题，就得考虑升级客户端。

5.4 单元测试与本地启动

这个场景容易被忽略：只有跑单测时才报错。

原因是测试类路径和运行类路径不一样。testscope 的依赖、maven-surefire-plugin的额外配置、IDE 的"包含 test 依赖"开关，任何一个没对齐都可能造成差异。

我的习惯是在pom.xml里给测试也显式声明一次核心依赖，虽然看起来冗余，但能避免很多莫名其妙的差异：

<dependency> <groupId>io.netty</groupId> <artifactId>netty-transport</artifactId> <version>${netty.version}</version> <scope>test</scope> </dependency>

6. 速查表与踩坑心得

6.1 一页纸速查表

6.2 几个我踩过、文档里不会写的坑

第一个坑：只加netty-all反而更乱。早年我图省事，遇到这个问题就往pom.xml里塞一个netty-all，结果和框架自带的netty-transport版本不一致，变成了NoSuchMethodError。后来才明白，netty-all不是万金油，它是聚合包，版本必须和其他分模块一致，否则只是把问题从"缺类"变成"方法签名不匹配"。

第二个坑：dependencyManagement里写了版本不等于引入了依赖。这个我见过不止一次。有人在dependencyManagement里声明了netty-transport的版本，以为就完事了，实际上dependencyManagement只做版本仲裁，不引入依赖。类还是缺，必须同时在<dependencies>里声明。

第三个坑：升级 Netty 版本要连带看netty-tcnative和netty-transport-native-epoll。这几个包的版本必须和主版本严格对齐，错一个版本号就可能在 native 传输层炸掉。如果你的服务用的是原生 epoll 传输，升级时这几个要一起改。

第四个坑：exclusion是按 groupId + artifactId 匹配的，不认版本。你在父 POM 里对netty-transport写了个 exclude，不管哪个版本进来都会被排掉。有些团队在父 POM 里写了 exclusion 之后忘了，过了半年新同学排查这个问题能排查一天。

第五个坑：日志里只看到一个NoClassDefFoundError，别以为只有一个问题。类加载失败是有连锁反应的，第一个缺失的类往往不是根因。我一般的做法是把日志里所有NoClassDefFoundError和ClassNotFoundException都 grep 出来，找那个"最底层"的类名，通常从它入手最快。

第六个坑：-Dverbose输出的omitted要看清楚是"哪个版本胜出"。Maven 的冲突解决是"最短路径优先"，但输出里的省略标记有时候不太好读。我习惯配合dependency:tree -Dincludes=io.netty:*一起看，只看 Netty 这棵子树，视野干净很多。

最后分享一个我自己的习惯：每次引入新的中间件客户端或者框架，我都会在引入后立刻跑一次mvn dependency:tree -Dincludes=io.netty:*，把输出贴到需求文档的备注里。看起来多此一举，但在后面几个月里，只要出现和 Netty 相关的怪问题，翻出这份记录，十秒钟就能判断是"新引入的组件拉低了版本"还是"原本就有两个版本在打架"。这个习惯帮我节省的时间，远超当初多花的那几分钟。