基于Maven与jpackage构建的JavaFX应用.exe无法运行

1. 如何调试.exe的故障？ #

• 捕获日志输出：在主类main方法开头添加代码，将标准输出和错误重定向到文件：

  System.setOut(new PrintStream(new FileOutputStream("app.log")));
  System.setErr(new PrintStream(new FileOutputStream("error.log")));
  

  或者在jpackage打包时指定日志参数：--java-options "-Djava.util.logging.config.file=logging.properties"，提前配置日志输出规则。
• 手动启动Java命令：找到exe安装目录下的runtime/bin/java.exe，执行：

  java -jar GradeTracker-1.0.jar
  

  直接查看控制台报错，这是最直观的调试方式。
• 查看Windows事件日志：打开「事件查看器」→「Windows日志」→「应用程序」，查找Java相关的错误条目，里面会记录崩溃的具体原因。
• 切换控制台模式：用jpackage --type app-image生成应用镜像，修改镜像中的启动脚本，将javaw.exe替换为java.exe，运行时会弹出控制台显示所有输出。

2. 处理自动模块的替代方案 #

• 非模块化打包：放弃jlink，用maven-shade-plugin将所有依赖（包括JavaFX）打包成胖jar，再用jpackage打包。这种方式无需处理模块声明，适合依赖较多自动模块的场景。
• 使用官方模块化依赖：优先选择支持JPMS的依赖版本，比如Gson 2.10+、Apache POI 5.x本身已提供模块信息，你的module-info.java已正确引用，说明这些依赖不是问题根源。
• 手动生成模块信息：用jdeps工具分析自动模块依赖：

  jdeps --generate-module-info . your-auto-module.jar
  

  生成基础module-info.java后手动调整，再用maven-jmod-plugin将jar转为jmod文件供jlink使用。
• 使用javafx-maven-plugin：官方插件内置模块化/非模块化项目支持，自动处理依赖收集和模块配置，减少手动操作错误。

3. jlink/jpackage的使用问题排查 #

从你的操作和配置看，问题大概率出在jpackage参数使用上：

• 当前命令jpackage --input target --main-jar GradeTracker-1.0.jar属于非模块化打包，但你的项目是模块化的，且target目录仅包含主jar，缺少JavaFX和其他依赖jar，导致运行时找不到类直接闪崩。
• 正确模块化打包流程：先用jlink生成包含所有依赖模块的运行时镜像，再用jpackage基于镜像打包：

  jpackage --runtime-image target/jlink-image --module ironbyte.gradetracker/ironbyte.gradetracker.Application
  

• 你的pom.xml未配置JavaFX打包插件，导致JavaFX模块未被正确包含到jlink镜像或打包目录，这也是常见问题。

4. Maven构建JavaFX模块化项目的最佳实践 #

• 优先使用官方插件：org.openjfx:javafx-maven-plugin集成编译、运行、jlink、jpackage全流程，自动处理JavaFX模块路径和依赖。
• 准确编写module-info.java：像你当前配置一样，确保requires正确声明依赖模块，exports/opens正确暴露需要访问的包（如JavaFX FXML和Gson的反射访问）。
• 分离测试依赖：测试依赖（如JUnit）设置为test scope，避免被打包到运行时镜像。
• 灵活选择打包方式：若依赖大量未模块化库，直接用非模块化打包（胖jar）更简单，无需强行模块化。
• 版本对齐：确保Java、JavaFX、Maven插件版本相互兼容（如Java 22搭配JavaFX 23是兼容的，但插件版本需对应）。

5. 是否需要从头开始？ #

如果当前流程已混乱，从头重建是高效排查方式：

1. 用官方JavaFX Maven archetype创建新项目：

   mvn archetype:generate -DarchetypeGroupId=org.openjfx -DarchetypeArtifactId=javafx-archetype-fxml -DarchetypeVersion=23
   

2. 逐步迁移代码（controller、model、view等）到新项目。
3. 逐个添加依赖（Gson、POI），每次添加后测试运行和打包，确保每一步正常。
4. 先测试非模块化打包（胖jar + jpackage），确认可用后再尝试模块化打包（jlink + jpackage）。

附：项目配置文件 #

module-info.java

module ironbyte.gradetracker {
    requires javafx.controls;
    requires javafx.fxml;
    requires com.google.gson;
    requires java.desktop;
    requires org.apache.poi.poi;
    requires org.apache.poi.ooxml;

    exports ironbyte.gradetracker;
    opens ironbyte.gradetracker to javafx.fxml;
    exports ironbyte.gradetracker.controller;
    opens ironbyte.gradetracker.controller to javafx.fxml;
    exports ironbyte.gradetracker.view;
    opens ironbyte.gradetracker.view to javafx.fxml;
    exports ironbyte.gradetracker.view.data;

    exports ironbyte.gradetracker.model;
    opens ironbyte.gradetracker.model to com.google.gson;
    exports ironbyte.gradetracker.model.action;
    opens ironbyte.gradetracker.model.action to com.google.gson;
    exports ironbyte.gradetracker.model.data;
    opens ironbyte.gradetracker.model.data to com.google.gson;
}

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>IronByte</groupId>
    <artifactId>GradeTracker</artifactId>
    <version>1.0</version>
    <name>GradeTracker</name>
    <description>An intuitive GPA tracking tool that monitors and calculates academic performance</description>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.appClass>ironbyte.gradetracker.Application</project.appClass>
        <project.launchClass>ironbyte.gradetracker.Launcher</project.launchClass>
        <junit.version>5.10.0</junit.version>
        <javafx.version>23</javafx.version>
        <javafx.home>C:\Program Files\JavaFX\javafx-sdk-23</javafx.home>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-controls</artifactId>
            <version>${javafx.version}</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-fxml</artifactId>
            <version>${javafx.version}</version>
        </dependency>

        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.11.0</version>
        </dependency>

        <dependency>
            <groupId>org.apache.poi</groupId>
            <artifactId>poi</artifactId>
            <version>5.3.0</version>
        </dependency>
        <dependency>
            <groupId>org.apache.poi</groupId>
            <artifactId>poi-ooxml</artifactId>
            <version>5.3.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>22</source>
                    <target>22</target>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>2.4</version>
                <configuration>
                    <archive>
                        <manifest>
                            <addClasspath>true</addClasspath>
                            <mainClass>${project.appClass}</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

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