Maven jlink插件生成镜像后无法加载LWJGL本地库问题

云原生阿岚

2026-7-16

解决思路

检查本地库实际存放路径
生成的Java镜像中，本地库通常位于image/lib或对应模块的子目录（比如image/modules/org.lwjgl/lib）。手动确认liblwjgl.so是否存在于这些路径，同时注意是否为当前系统架构（x86_64）的版本。

修正Maven jlink插件配置
确保插件正确提取本地库到镜像的可访问路径，而非仅打包在JAR中。需添加--bind-services并明确指定本地库处理，示例配置：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jlink-plugin</artifactId>
  <version>3.1.0</version>
  <configuration>
    <moduleName>你的主模块名</moduleName>
    <outputDirectory>target/image</outputDirectory>
    <bindServices>true</bindServices>
    <launcher>app=你的主模块/你的主类全限定名</launcher>
    <modules>
      <module>java.base</module>
      <module>org.lwjgl</module>
      <!-- 添加所有依赖的LWJGL子模块 -->
    </modules>
    <arguments>
      <argument>--add-modules</argument>
      <argument>org.lwjgl,org.lwjgl.glfw,org.lwjgl.opengl</argument>
      <argument>--include-natives</argument>
      <argument>linux</argument>
    </arguments>
  </configuration>
</plugin>

同时确保LWJGL的Maven依赖指定了classifier=natives-linux，拉取对应平台的本地库JAR。

检查module-info.java声明
主模块需正确依赖LWJGL模块，示例：

module 你的主模块名 {
  requires org.lwjgl;
  requires org.lwjgl.glfw;
  requires org.lwjgl.opengl;
  // 若主类需被LWJGL反射访问，添加opens声明
  opens 你的主类所在包 to org.lwjgl;
}

调整运行脚本的JVM参数
在生成的shell脚本中，显式指定本地库路径，示例：
```
#!/bin/sh
BASEDIR=$(dirname "$0")
"$BASEDIR/java" -Djava.library.path="$BASEDIR/lib" -m 你的主模块/你的主类全限定名 "$@"
```
若本地库在模块子目录中，调整路径为"$BASEDIR/modules/org.lwjgl/lib"。
验证本地库兼容性
使用ldd liblwjgl.so命令检查库的系统依赖，确认是否缺少libc.so.6等系统库，如有缺失安装对应系统包（比如libc6-dev）。