GraalVM native image如何将classpath下多JAR打包为单可执行程序

绝大多数入门教程只演示单JAR构建的简化用法，本质是省略了classpath参数的传值逻辑。native-image对类路径的处理和原生java命令完全一致，原生支持传入多个JAR、多个目录组成的全量classpath，不需要提前把所有依赖打包成单个胖JAR，就能输出整合了所有依赖的单一可执行程序。

手动命令行构建的基础写法 #

命令行模式下直接通过-cp参数传入完整类路径即可，注意不同操作系统的类路径分隔符差异：

• Linux/macOS下类路径条目用冒号:分隔
• Windows下类路径条目用分号;分隔

示例命令（以Linux/macOS环境为例）：

native-image \
  -cp "build/classes/java/main:libs/dep-core.jar:libs/dep-utils.jar:libs/config-resources" \
  com.example.ApplicationMain \
  ./build/native/my-app

参数说明：

• -cp后面依次拼接项目编译输出目录、所有依赖JAR路径、资源目录路径
• 倒数第二个参数是程序入口的全限定类名
• 最后一个参数是最终输出的可执行文件路径

native-image会自动扫描classpath路径下的所有类、资源文件，全部纳入编译范围，最终生成的可执行文件不需要额外附带依赖JAR即可独立运行。

Gradle项目的自动配置 #

针对Gradle默认按单JAR存储依赖的组织方式，不需要手动逐一拼接依赖路径，直接在构建脚本中引用项目自带的全量运行时classpath即可完成配置：

1. 在build.gradle中注册自定义构建任务

tasks.register('buildNative', Exec) {
  // 自动获取项目全量运行时类路径，包含所有拉取的第三方依赖
  def fullRuntimeClasspath = sourceSets.main.runtimeClasspath.asPath
  // 获取项目指定的主类名
  def entryClass = project.mainClassName

  commandLine 'native-image',
    '-cp', fullRuntimeClasspath,
    entryClass,
    "${buildDir}/native/${project.name}"
}

2. 执行./gradlew buildNative即可触发构建，整个流程不需要提前生成Fat JAR，完全适配Gradle依赖缓存的目录结构。

如果项目用到反射、动态代理等需要手动配置的native-image特性，直接在commandLine的参数列表里追加对应配置项即可，和单JAR场景的参数写法没有区别。

Maven项目的简化配置 #

Maven场景下同样可以借助插件能力自动生成全量classpath，避免手动拼路径的冗余：

1. 先通过Maven自带的依赖插件把全量运行时classpath导出到临时文件

mvn dependency:build-classpath -Dmdep.outputFile=target/cp.txt

2. 将导出的classpath值传入native-image命令

native-image \
  -cp "target/classes:target/$(cat cp.txt)" \
  com.example.ApplicationMain \
  ./target/native/my-app

常见操作误区 #

• 不要强行先打Fat JAR：不少教程引导用户先把所有依赖打包成单个JAR再执行native-image，本质是增加了一步无意义的构建流程。native-image原生支持多路径、多JAR的classpath传参，完全可以跳过Fat JAR打包步骤。
• 不要遗漏资源目录：如果项目的配置文件、静态资源是独立存放的，需要把资源目录的路径追加到classpath中，native-image会自动将资源整合到最终的可执行文件中。
• 不要忘记指定入口类：如果传了完整classpath但没有指定程序入口的全限定类名，native-image会因找不到主类构建失败。

内容的提问来源于stack exchange，提问作者Dzmitry Lazerka