如何使用javafx-maven-plugin导出含JFoenix组件的JavaFX Maven项目

我之前也踩过JavaFX jlink导出的坑，结合你已经搞定运行配置的情况，咱们一步步来把导出的问题解决掉：

1. 补全pom.xml中javafx-maven-plugin的jlink配置 #

你之前已经配置了运行相关的参数，但jlink需要额外的配置项。确保你的插件配置里包含这些关键内容：

<plugin>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-maven-plugin</artifactId>
    <version>0.0.8</version>
    <configuration>
        <!-- 必须和module-info.java里的模块名完全一致 -->
        <moduleName>your.module.name</moduleName>
        <!-- 主类格式：模块名/全限定类名，比如com.example.myfxapp/com.example.myfxapp.Main -->
        <mainClass>your.module.name/your.full.package.MainClass</mainClass>
        <!-- 生成的镜像文件夹名称，默认是target/image -->
        <jlinkImageName>my-fx-app</jlinkImageName>
        <!-- 可选：生成一个直接运行的启动器，不用手动敲java命令 -->
        <launcher>my-fx-app-launcher</launcher>
    </configuration>
    <!-- 绑定到package阶段，执行mvn package时自动触发jlink -->
    <executions>
        <execution>
            <id>jlink-build</id>
            <phase>package</phase>
            <goals>
                <goal>jlink</goal>
            </goals>
        </execution>
    </executions>
</plugin>

这里重点注意：

• moduleName要和你的module-info.java里声明的模块名丝毫不差
• mainClass的格式是模块名/全限定类名，别搞反顺序或者漏了模块名
• 加上launcher配置后，jlink会自动生成可执行脚本，Windows是.exe，Linux/macOS是可执行文件，能避免手动输入命令的错误

2. 检查module-info.java的模块声明是否正确 #

jlink是基于Java模块系统的，你的模块声明必须包含所有依赖，包括JavaFX和JFoenix：

module your.module.name {
    // 引入JavaFX核心模块
    requires javafx.controls;
    requires javafx.fxml;
    // 引入JFoenix，如果是自动模块（没有module-info），用Jar包的名称，比如requires jfoenix;
    requires com.jfoenix;

    // 主类所在的包需要导出给FXML（如果用FXML的话）
    opens your.full.package to javafx.fxml;
    // 导出主类所在的包，让模块系统能找到主类
    exports your.full.package;
}

如果JFoenix没有官方模块声明，它会被当作自动模块，requires后面写它的Jar包名称（比如jfoenix，看你Maven依赖里的artifactId）。

3. 执行正确的Maven命令生成镜像 #

先清理之前的构建缓存，再执行jlink命令，避免旧文件干扰：

mvn clean javafx:jlink

或者如果绑定了package阶段，直接执行：

mvn clean package

成功后，镜像文件会生成在target/my-fx-app（就是你配置的jlinkImageName）目录下。

4. 正确运行导出的应用 #

• 如果你配置了launcher：直接进入target/my-fx-app/bin目录，运行生成的启动器即可：
  • Windows：双击my-fx-app-launcher.exe
  • Linux/macOS：在终端运行./my-fx-app-launcher
• 如果没配置launcher，手动运行的话，不要给模块名或主类加引号，正确命令格式是：

  cd target/my-fx-app/bin
  java -m your.module.name/your.full.package.MainClass
  

  很多人失败就是因为加了多余的引号，导致模块系统无法正确解析。

常见问题排查 #

• 报错“找不到模块”：检查moduleName和module-info.java里的模块名是否一致，命令里的模块名有没有拼写错误
• 报错“找不到主类”：检查mainClass的格式是否正确，主类是否在对应的模块里，module-info.java是否导出了主类所在的包
• JFoenix控件显示异常：确保module-info.java里正确requires了JFoenix，并且Maven依赖已经正确拉取到本地仓库

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