运行Spring Boot 3原生应用时遭遇libfreetype.so缺失错误

问题原因 #

你通过mvn -Pnative native:compile生成的原生二进制文件，依赖系统级的libfreetype共享库，但当前运行环境未安装该库，导致启动时加载失败。

解决方案 #

1. 本地运行环境安装依赖库 #

根据你使用的Linux发行版执行对应命令：

• Debian/Ubuntu系：

  sudo apt-get update && sudo apt-get install -y libfreetype6
  

• RHEL/CentOS/Rocky系：

  sudo dnf install -y freetype-devel
  

• Arch Linux：

  sudo pacman -S freetype2
  

安装完成后重新执行./target/blog即可启动应用。

2. 编译阶段静态链接依赖（可选） #

如果希望生成的二进制不依赖系统库，可修改pom.xml中native-maven-plugin的配置，添加静态链接参数：

<plugin>
    <groupId>org.graalvm.buildtools</groupId>
    <artifactId>native-maven-plugin</artifactId>
    <configuration>
        <buildArgs>
            <buildArg>--static</buildArg>
            <buildArg>-lfreetype</buildArg>
        </buildArgs>
    </configuration>
</plugin>

重新执行mvn -Pnative native:compile，生成的二进制将包含libfreetype的静态版本，无需在运行环境单独安装。

3. 容器化部署时解决依赖 #

如果用容器运行，选择包含libfreetype的基础镜像，比如BellSoft的官方镜像：

FROM bellsoft/liberica-runtime-container:jdk-17-cds-slim
COPY target/blog /app/blog
ENTRYPOINT ["/app/blog"]

构建镜像后运行即可规避依赖问题。

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