本教程旨在指导开发者如何利用java 19及以上版本的`jlink`工具，为spring boot 3.0应用程序构建一个轻量级、定制化的java运行时镜像。文章将从一个基础spring boot项目出发，详细阐述使用`jdeps`分析模块依赖的过程，并解决在使用`jlink`创建运行时过程中常见的`noclassdeffounderror`问题，最终生成一个可独立部署的精简版java运行环境。
引言：定制化Java运行时与jlink
随着Java模块化系统（JPMS）的引入，jlink工具成为Java 9及更高版本中一个重要的部署特性。它允许开发者根据应用程序的实际需求，创建一个只包含所需Java模块的最小化运行时环境（JRE）。这不仅可以显著减小部署包的大小，还能提升应用程序的启动速度和安全性。对于Spring Boot这类框架构建的应用程序，利用jlink可以进一步优化其部署效率。
准备工作：基础Spring Boot应用程序
首先，我们创建一个简单的Spring Boot应用程序作为示例。该应用使用Maven、Java 19和Spring Boot 3.0，并额外引入了commons-lang3依赖。
pom.xml 配置：
4.0.0 org.springframework.boot spring-boot-starter-parent3.0.0 com.example demo0.0.1-SNAPSHOT demo Demo project for Spring Boot 19 org.springframework.boot spring-boot-starterorg.springframework.boot spring-boot-starter-testtest org.apache.commons commons-lang3org.springframework.boot spring-boot-maven-plugin
主应用程序类 DemoApplication.java：
package com.example.demo;
import org.apache.commons.lang3.StringUtils;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
String mix = "MIX";
if (StringUtils.isNoneBlank(mix)) {
System.out.println(mix);
}
SpringApplication.run(DemoApplication.class
, args);
}
}
, args);
}
}编译项目后，会在 target 目录下生成一个可执行的JAR文件，例如 demo-0.0.1-SNAPSHOT.jar。我们可以通过 java -jar target/demo-0.0.1-SNAPSHOT.jar 成功运行它。
分析模块依赖：jdeps 工具的使用
为了构建定制化运行时，我们需要知道应用程序依赖哪些Java模块。jdeps工具可以帮助我们分析JAR文件中的类依赖。
执行以下命令分析我们的Spring Boot JAR：
jdeps target/demo-0.0.1-SNAPSHOT.jar
jdeps的输出可能会比较长，但我们可以从中观察到一些关键信息：
demo-0.0.1-SNAPSHOT.jar -> java.base demo-0.0.1-SNAPSHOT.jar -> java.logging demo-0.0.1-SNAPSHOT.jar -> not found com.example.demo -> java.io java.base com.example.demo -> java.lang java.base com.example.demo -> org.apache.commons.lang3 not found com.example.demo -> org.springframework.boot not found ... (其他Spring Boot内部类和第三方库的依赖)
jdeps输出解读：
- demo-0.0.1-SNAPSHOT.jar -> java.base 和 demo-0.0.1-SNAPSHOT.jar -> java.logging 表明应用程序直接依赖了这两个Java标准模块。
- not found 标识通常表示 jdeps 无法在当前模块路径中找到对应的模块，这对于Spring Boot的"fat jar"来说是正常的，因为Spring Boot的类和第三方库（如commons-lang3）都被打包在同一个JAR文件中，它们并不是独立的Java模块。jdeps 主要关注的是应用程序对Java平台模块的依赖。
基于初步分析，我们至少需要 java.base 和 java.logging 模块。
构建定制化运行时：初次尝试与问题解决
现在我们尝试使用jlink构建一个包含这些模块的定制化运行时：
jlink --module-path $JAVA_HOME/jmods --add-modules java.base,java.logging --output mycustomrt
这条命令会在当前目录下创建一个名为 mycustomrt 的目录，其中包含了精简后的Java运行时。
尝试使用这个定制化运行时运行Spring Boot应用程序：
./mycustomrt/bin/java -jar target/demo-0.0.1-SNAPSHOT.jar
此时，应用程序可能会抛出 java.lang.NoClassDefFoundError 错误，例如：
java.lang.NoClassDefFoundError: java/beans/PropertyEditorSupport
at org.springframework.boot.context.properties.bind.BindConverter$TypeConverterConverter.(BindConverter.java:180)
...
Caused by: java.lang.ClassNotFoundException: java.beans.PropertyEditorSupport
... 这个错误表明在定制化运行时中缺少了 java.beans.PropertyEditorSupport 类。java.beans 包是Java标准库的一部分，但它不属于 java.base 或 java.logging。实际上，java.beans 模块位于 java.desktop 模块中，即使应用程序没有图形界面，Spring框架的某些内部机制（如属性绑定和转换）也可能依赖它。
识别并添加缺失模块
NoClassDefFoundError 是构建定制化运行时时常见的挑战。当遇到此类错误时，我们需要根据错误信息来判断缺少哪个Java模块。解决此问题通常是一个迭代的过程，可能需要根据堆栈跟踪中缺失的类来逐步添加模块。
根据错误 java.lang.NoClassDefFoundError: java/beans/PropertyEditorSupport，我们可以推断出需要添加 java.desktop 模块。此外，Spring Boot应用在运行时还可能隐式依赖其他一些通用模块，例如：
- java.xml: 用于XML处理，Spring框架常用于配置和数据绑定。
- java.sql: 用于数据库连接（即使不直接使用JDBC，一些数据源配置也可能需要）。
- java.prefs: 用于用户偏好设置。
综合考虑这些潜在的依赖，我们需要更新 jlink 命令以包含这些额外的模块。
正确的 jlink 命令：
jlink --module-path $JAVA_HOME/jmods --add-modules java.base,java.logging,java.xml,java.sql,java.prefs,java.desktop --output mycustomrt
这条命令会创建一个更完整的定制化运行时，包含了Spring Boot应用所需的核心Java模块。
使用定制化运行时运行应用程序
重新执行上述 jlink 命令后，再次尝试运行应用程序：
./mycustomrt/bin/java -jar target/demo-0.0.1-SNAPSHOT.jar
现在，应用程序应该能够成功启动并正常运行，显示Spring Boot的启动日志和我们自定义的输出。
MIX . ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v3.0.0) 2025-11-30T19:47:53.468+01:00 INFO 18179 --- [ main] com.example.demo.DemoApplication : Starting DemoApplication v0.0.1-SNAPSHOT using Java 19.0.1 with PID 18179 (...) ... 2025-11-30T19:47:54.131+01:00 INFO 18179 --- [ main] com.example.demo.DemoApplication : Started DemoApplication in 1.172 seconds (process running for 1.666)
总结与注意事项
- 模块发现的迭代性： 使用jlink构建定制化运行时，特别是对于非模块化（classpath-based）的复杂应用如Spring Boot，往往是一个迭代的过程。jdeps提供初步指导，但最终的模块列表可能需要通过运行应用程序并根据NoClassDefFoundError来补充。
- Spring Boot的特殊性： Spring Boot的“fat jar”机制将所有依赖打包在一起，这使得jdeps在分析时可能无法直接识别所有深层Java模块依赖。因此，运行时错误是发现缺失模块的关键信号。
- 常见额外模块： 除了java.base和java.logging，Spring Boot应用常常需要java.desktop（用于java.beans）、java.xml、java.sql、java.naming、java.management等模块，具体取决于应用程序使用的Spring Boot Starter和其他库。
- 部署优势： 定制化运行时显著减小了部署包的大小，因为它只包含了应用程序实际需要的Java运行时组件，而不是完整的JDK或JRE。这对于容器化部署（如Docker）和云环境尤其有利。
- Maven插件集成： 在实际项目中，可以将jlink命令集成到Maven构建生命周期中，例如使用maven-jlink-plugin或spring-boot-maven-plugin的jlink相关目标，实现自动化的定制化运行时构建。
通过本教程，您应该能够成功为您的Spring Boot应用程序创建一个精简、高效的定制化Java运行时镜像，从而优化应用程序的部署和运行效率。
