Docker容器运行WebFlux时出现Netty本地库加载异常

这问题我之前帮好几个开发者排查过，本质是Netty的epoll本地库在Docker镜像环境中缺失或者加载不兼容导致的。先抓你贴的核心报错看：

Caused by: java.io.FileNotFoundException: META-INF/native/libnetty_transport_native_epoll.so
Suppressed: java.lang.UnsatisfiedLinkError: no netty_transport_native_epoll in java.library.path

下面给你几个按优先级排序的解决方案，一步步来：

1. 更换带Glibc的JDK基础镜像（最快解决） #

大概率你用了轻量的Alpine镜像——Alpine默认用Musl C库，而Netty的epoll原生库基本都是针对Glibc编译的，兼容性拉胯。直接换成官方的Glibc-based JDK镜像就行：
比如在Dockerfile里替换基础镜像：

# 推荐用这个，或者eclipse-temurin系列的JRE镜像
FROM openjdk:11-jre-slim

这个方案不需要改任何代码或依赖，换完重新构建镜像基本就能启动成功。

2. 基于Alpine镜像补全依赖（适合必须用Alpine的场景） #

如果一定要保留Alpine的轻量特性，需要两步操作：

第一步：在Dockerfile中安装Glibc兼容层 #

FROM openjdk:11-jre-alpine
# 安装libc6-compat来兼容Glibc环境
RUN apk add --no-cache libc6-compat

第二步：确保打包时包含对应架构的Netty原生依赖 #

在你的Maven/Gradle依赖中明确指定对应CPU架构的classifier：
Maven示例：

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-transport-native-epoll</artifactId>
    <version>你的Netty版本号</version>
    <!-- x86_64架构用这个，如果是ARM64（比如M系列Mac）换成linux-aarch_64 -->
    <classifier>linux-x86_64</classifier>
    <scope>runtime</scope>
</dependency>

Gradle示例：

runtimeOnly 'io.netty:netty-transport-native-epoll:你的版本号:linux-x86_64'

3. 禁用Epoll模型（兜底方案） #

如果上面两种都搞不定，或者你对Epoll的性能优势没需求，可以强制Netty使用NIO模型：

方式一：添加JVM启动参数 #

在Docker启动命令或Dockerfile的ENTRYPOINT/CMD里加参数：

java -Dio.netty.transport.type=NIO -jar auth-service.jar

方式二：代码中设置系统属性 #

在应用启动类的最开头加上：

public static void main(String[] args) {
    System.setProperty("io.netty.transport.type", "NIO");
    // 后面的启动代码
    SpringApplication.run(AuthServiceApplication.class, args);
}

额外排查点 #

• 检查Docker镜像的CPU架构是否和本地一致：比如你本地是ARM64（M1/M2 Mac），但构建的镜像默认是x86_64，这时候需要对应ARM64的Netty库（classifier用linux-aarch_64）。

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