避坑指南：用javafx-maven-plugin打包Windows服务时遇到的3个典型错误（附解决方案）

避坑指南：用javafx-maven-plugin打包Windows服务时遇到的3个典型错误（附解决方案）

最近在帮一个做工业控制上位机软件的朋友折腾JavaFX应用的部署，他们想把一个基于Spring Boot和JavaFX开发的桌面应用，打包成一个标准的Windows安装程序，并且最好能注册为系统服务，方便在后台静默运行。听起来是个挺常规的需求，对吧？但实际操作起来，尤其是在使用javafx-maven-plugin这个插件进行本地打包时，我们踩的坑一个接一个，从插件版本冲突到JDK兼容性，再到Inno Setup配置的“玄学”问题，几乎把能遇到的典型错误都经历了一遍。

这篇文章，就是把这些踩坑的经历和最终的解决方案系统地梳理出来。它面向的是已经尝试过JavaFX打包，但在某个环节卡住的中级开发者。我们不会重复那些“如何创建一个JavaFX项目”的基础教程，而是直接切入故障现场，结合日志分析，深挖问题根源。你会发现，很多错误信息看似模糊，但背后往往有明确的指向性。无论是想把应用打包成独立的.exe，还是更进一步制作成Windows系统服务，希望这篇指南能帮你节省大量无谓的调试时间。

1. 插件版本与依赖冲突：从“无法找到主类”说起

第一个拦路虎，往往出现在项目配置层面。当你信心满满地运行 mvn clean package，期待在 target/jfx/native 目录下看到生成的安装包时，Maven却可能抛出一堆令人困惑的错误，其中最常见的就是“无法找到或加载主类”。

1.1 症状诊断与日志分析

这个错误信息本身很泛泛，但结合 javafx-maven-plugin 的执行日志，我们可以找到更具体的线索。通常，错误发生在插件的 create-native-bundle 阶段。你需要打开Maven的调试输出，使用 mvn clean package -X 命令。在繁杂的日志中，重点关注插件尝试组装应用包的部分。

一个典型的错误场景是，插件报告它无法从你指定的路径找到可执行的JAR文件。例如，日志中可能出现类似下面的片段（经过简化）：

[INFO] --- javafx-maven-plugin:8.8.3:create-native-bundle (default-cli) @ my-javafx-app ---
[DEBUG] Configuring mojo 'com.zenjava:javafx-maven-plugin:8.8.3:create-native-bundle' with basic configurator -->
[DEBUG]   (f) mainClass = com.example.MainApp
[DEBUG]   (f) jfxMainAppJarName = my-javafx-app-1.0.0.jar
[ERROR] Failed to execute goal com.zenjava:javafx-maven-plugin:8.8.3:create-native-bundle (default-cli) on project my-javafx-app: Error: Could not find application jar: /path/to/target/jfx/app/my-javafx-app-1.0.0.jar -> [Help 1]

注意：javafx-maven-plugin 在构建原生包时，会期望在 target/jfx/app 目录下找到主JAR文件及其依赖。如果这个目录结构不对，或者JAR文件没被正确复制过去，就会报错。

1.2 根源探究：Spring Boot打包插件与Javafx插件的执行顺序

问题根源往往在于Maven生命周期中插件的执行顺序冲突。特别是当你同时使用 spring-boot-maven-plugin 和 javafx-maven-plugin 时。

• Spring Boot插件：默认的 repackage 目标会将你的应用打包成一个可执行的、包含所有依赖的“fat jar”（比如 my-app-1.0.0.jar），这个JAR可以直接用 java -jar 运行。
• Javafx插件：它需要的是一个“瘦jar”，即只包含你项目编译后的类文件，依赖的库应该被放在单独的 lib 文件夹里。它会在 package 阶段执行，尝试从 target/jfx/app 目录获取这个瘦JAR。

如果配置不当，可能会出现两种情况：

1. Spring Boot的 repackage 在 javafx-maven-plugin 的 native 目标之后运行，导致Javafx插件找不到最终的可执行JAR。
2. 两个插件都去修改 target 目录下的JAR文件，造成冲突。

1.3 解决方案：明确的插件配置与依赖处理

解决这个冲突，需要精细地配置两个插件。以下是一个经过实战检验的POM.xml配置片段：

<build>
    <plugins>
        <!-- 1. 首先，使用maven-dependency-plugin在compile阶段将依赖复制到指定目录 -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-dependency-plugin</artifactId>
            <version>3.6.0</version>
            <executions>
                <execution>
                    <id>copy-dependencies</id>
                    <phase>compile</phase>
                    <goals>
                        <goal>copy-dependencies</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>${project.build.directory}/lib</outputDirectory>
                        <includeScope>runtime</includeScope>
                    </configuration>
                </execution>
            </executions>
        </plugin>

        <!-- 2. 使用maven-resources-plugin或antrun插件，将依赖lib和主JAR准备到jfx/app目录 -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-antrun-plugin</artifactId>