OSX系统Java配置Netty依赖后KQueue不可用如何排查

现有配置与现象 #

项目中配置的Gradle依赖如下：

implementation("io.netty:netty-transport-native-epoll:$nettyVersion")
implementation("io.netty:netty-transport-native-kqueue:$nettyVersion")
implementation("io.netty:netty-transport-native-epoll:$nettyVersion:linux-aarch_64")
implementation("io.netty:netty-transport-native-epoll:$nettyVersion:linux-x86_64")
implementation("io.netty:netty-transport-native-kqueue:$nettyVersion:osx-x86_64")

Gradle日志显示依赖已正确拉取缓存（<source>为内部私有依赖库存储路径）：

Cached resource <source>/releases/io/netty/netty-transport-native-kqueue/4.1.78.Final/netty-transport-native-kqueue-4.1.78.Final-osx-x86_64.jar is up-to-date (lastModified: Fri Jun 24 17:45:28 PDT 2022).

构建时操作系统与CPU架构检测结果正常：

------------------------------------------------------------------------
Detecting the operating system and CPU architecture
------------------------------------------------------------------------
os.detected.name=osx
os.detected.arch=x86_64
os.detected.version=12.4
os.detected.version.major=12
os.detected.version.minor=4
os.detected.classifier=osx-x86_64

最简复现代码：

KQueue.isAvailable()

该方法返回值为false。
执行以下代码获取详细错误：

KQueue.unavailabilityCause().printStackTrace();

移除无关栈轨迹后核心报错如下：

java.lang.UnsatisfiedLinkError: could not load a native library: netty_transport_native_kqueue_x86_64
        at io.netty.util.internal.NativeLibraryLoader.load(NativeLibraryLoader.java:239)
        at io.netty.channel.kqueue.Native.loadNativeLibrary(Native.java:155)
        ...
        Suppressed: java.lang.UnsatisfiedLinkError: no netty_transport_native_kqueue_x86_64 in java.library.path: /Users/kdilsiz/Library/Java/Extensions:/Library/Java/Extensions:/Network/Library/Java/Extensions:/System/Library/Java/Extensions:/usr/lib/java:.
        ...

已完成前置排查：通过gradle -info --refresh-dependencies确认KQueue相关依赖拉取、缓存流程正常，公开渠道可查的旧版本Netty debug日志级别依赖加载问题与当前场景不匹配。

问题根因与修复方案 #

现有依赖声明不存在语法错误，加载失败由以下三类高频问题导致，按排查优先级从高到低处理即可：

• 运行时类路径缺失native jar
  手动指定classifier声明依赖时，部分IDE和构建工具不会将带classifier的jar加入应用运行时类路径，即使Gradle已经把依赖缓存到本地，运行时Netty无法从jar包内提取动态库，只能遍历java.library.path查找本地库，最终抛出找不到库的错误。
  验证方式：启动应用时添加JVM参数-verbose:class，查看io.netty.channel.kqueue.Native类加载时，类路径下是否存在netty-transport-native-kqueue-4.1.78.Final-osx-x86_64.jar。
  修复方式：不要手动枚举各系统架构的classifier依赖，引入Gradle osdetector插件，自动匹配当前系统架构拉取对应native依赖，避免类路径识别异常。
• MacOS安全机制拦截native库加载
  MacOS 12+版本会对网络下载的二进制文件自动添加com.apple.quarantine隔离标记，当Netty把jar包内的libnetty_transport_native_kqueue_x86_64.dylib解压到临时目录准备加载时，系统安全策略会直接拦截加载请求，该错误会被Netty的NativeLibraryLoader捕获，包装为“找不到库”的异常，和当前报错特征完全匹配。
  验证方式：进入Java临时目录（默认路径为$TMPDIR下的netty开头的临时文件夹），对解压出的dylib文件执行xattr 文件名，查看输出是否包含com.apple.quarantine属性。
  修复方式：执行以下命令移除Gradle缓存下所有Netty包的隔离标记，重启应用即可：

  sudo xattr -r -d com.apple.quarantine ~/.gradle/caches/modules-2/files-2.1/io.netty/
  

• 临时目录无执行权限
  部分企业管控的Mac设备会将/tmp目录挂载为noexec权限，Netty将native库解压到该目录后没有执行权限，无法完成加载。
  修复方式：启动应用时添加JVM参数，指定一个有执行权限的目录作为Netty native库工作目录：

  -Dio.netty.native.workdir=/path/to/your/executable/dir
  

内容的提问来源于stack exchange，提问作者Kemal Tezer Dilsiz