如何在Windows上调试APISIX Java Runner过滤器及解决运行报错

问题原因 #

APISIX Java Plugin Runner 0.4.0版本依赖的netty-transport-native-epoll/kqueue是Linux/macOS专属的IO模型，Windows系统不支持这两种机制，直接运行会触发该报错。

可行解决方法 #

1. 用WSL2（Windows子系统Linux）运行 #

• 安装WSL2并选择Ubuntu等Linux发行版
• 在WSL2环境内部署APISIX 3.3.0和Java Plugin Runner 0.4.0，复用Linux下的调试流程
• 本地IDE（如IntelliJ IDEA）可通过远程调试连接WSL2中的Java进程：
  • 在Java Runner启动命令中添加JVM参数：-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:5005
  • 在IDE中配置远程调试，目标地址填WSL2的IP（通过ip addr查询）和端口5005

2. 修改Java Runner依赖配置（仅本地调试用，不推荐生产） #

• 打开Java Runner的pom.xml，移除netty-transport-native-epoll和netty-transport-native-kqueue相关依赖
• 添加Windows兼容的netty依赖：

  <dependency>
      <groupId>io.netty</groupId>
      <artifactId>netty-transport-native-epoll</artifactId>
      <version>${netty.version}</version>
      <classifier>windows-x86_64</classifier>
  </dependency>
  

• 重新编译项目后尝试启动，此方法可能存在兼容性问题

3. 用Docker容器运行 #

• 基于官方APISIX和Java Runner镜像构建容器环境
• 用Docker Desktop管理容器，将本地代码目录挂载到容器内
• 通过远程调试连接容器中的Java进程实现代码调试

调试过滤器的通用步骤 #

• 在自定义过滤器代码中添加日志输出或断点
• 确保APISIX配置文件已启用Java Runner，指定正确的unix_socket或tcp连接地址
• 发送测试请求到APISIX触发过滤器逻辑，结合IDE断点或日志排查问题

内容的提问来源于stack exchange，提问作者Hoàng Hưng