GraalVM生成的Native Image无法加载libzstd-jni运行时报错求助

问题现象 #

用mvn package -Dpackaging=native-image生成Native Image后，服务器启动正常，但运行时抛出java.lang.UnsatisfiedLinkError，提示找不到/darwin/aarch64/libzstd-jni-1.5.2-5.dylib或无法从系统库加载该文件。

环境信息 #

• 硬件：MacBook Pro Apple M3 Pro
• 框架：Micronaut Parent 4.2.1
• JDK：Oracle GraalVM 17.0.12+8.1
• 依赖：com.github.luben:zstd-jni:1.5.7-2

解决方案 #

1. 添加Native Image专属配置文件 #

在项目的src/main/resources/META-INF/native-image/com.github.luben/zstd-jni目录下创建native-image.properties文件，写入以下配置：

Args = --initialize-at-build-time=com.github.luben.zstd.Zstd,com.github.luben.zstd.ZstdJNI \
       --native-library-path=${com.github.luben:zstd-jni:jar}/darwin/aarch64 \
       --add-modules=jdk.incubator.vector \
       --allow-incomplete-classpath

该配置会让GraalVM在构建阶段初始化zstd核心类，明确指定本地库路径，并启用必要的模块支持。

2. 调整依赖配置，确保本地库正确引入 #

在pom.xml中修改zstd-jni的依赖，添加架构专属的classifier和type，避免依赖版本混淆：

<dependency>
    <groupId>com.github.luben</groupId>
    <artifactId>zstd-jni</artifactId>
    <version>1.5.7-2</version>
    <classifier>darwin-aarch64</classifier>
    <type>jar</type>
</dependency>

同时添加maven-dependency-plugin，将本地库复制到Native Image构建的资源目录：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
        <execution>
            <id>copy-native-libs</id>
            <phase>package</phase>
            <goals>
                <goal>copy</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>com.github.luben</groupId>
                        <artifactId>zstd-jni</artifactId>
                        <version>1.5.7-2</version>
                        <classifier>darwin-aarch64</classifier>
                        <type>jar</type>
                        <outputDirectory>${project.build.directory}/native-image-libs</outputDirectory>
                    </artifactItem>
                </artifactItems>
            </configuration>
        </execution>
    </executions>
</plugin>

之后构建时添加参数-Dnative-image.libpath=${project.build.directory}/native-image-libs，确保GraalVM能定位到本地库。

3. 配置native-image-maven-plugin #

如果使用Micronaut集成的native-image插件，在pom.xml中显式添加本地库和初始化规则：

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-image-maven-plugin</artifactId>
    <version>0.10.2</version>
    <executions>
        <execution>
            <id>native-image</id>
            <goals>
                <goal>native-image</goal>
            </goals>
            <phase>package</phase>
        </execution>
    </executions>
    <configuration>
        <mainClass>你的应用主类全路径</mainClass>
        <buildArgs>
            <buildArg>--initialize-at-build-time=com.github.luben.zstd</buildArg>
            <buildArg>--native-library-path=${project.build.directory}/native-image-libs</buildArg>
            <buildArg>--allow-incomplete-classpath</buildArg>
        </buildArgs>
    </configuration>
</plugin>

替换你的应用主类全路径为实际的主类（如com.example.Application）。

4. 验证本地库完整性 #

解压zstd-jni-1.5.7-2-darwin-aarch64.jar，确认内部包含darwin/aarch64/libzstd-jni-1.5.7-2.dylib文件。错误中出现的1.5.2-5版本可能是库内部的旧引用，确保依赖的jar包版本与配置一致。

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