VS Code运行Maven打包的JavaFX jar报javafx.controls模块找不到错误

• 你配置的--module-path路径错误：JDK 11及后续版本已经不再内置JavaFX组件，你填写的Adoptium JDK的lib目录是JDK自身的类库存放位置，本身不包含javafx.controls、javafx.fxml等JavaFX模块，执行命令时自然会抛出模块找不到的异常。
• mvn package默认生成的是仅包含项目自身代码的瘦jar包，既没有打包JavaFX相关依赖，也没有配置JavaFX程序启动所需的入口参数，所以直接运行jar不会有任何响应。
• VS Code中示例项目可以直接运行，是因为IDE在后台自动识别了Maven依赖、拼接了所需的启动参数，这些运行时配置不会自动同步到Maven的打包逻辑中。

1. 修复命令行运行的参数错误 #

首先找到你本地单独下载解压的JavaFX SDK存放位置，模块路径需要指向JavaFX SDK目录下的lib文件夹，而非JDK的lib目录。另外Windows系统下路径包含空格时，需要用双引号而非单引号包裹路径，参考正确命令格式：

java --module-path "D:\tools\javafx-sdk-17.0.8\lib" --add-modules javafx.controls,javafx.fxml -jar .\test.jar

把上述命令里的JavaFX lib路径替换成你本地的实际路径即可正常启动。

2. 配置Maven插件生成可直接运行的jar包 #

如果不想每次启动都手动拼接参数，可以修改项目的pom.xml配置，通过Maven插件直接打包出可独立运行的程序：

• 在pom.xml的<build><plugins>节点下添加JavaFX Maven插件，替换配置里的mainClass为你项目实际的启动类全限定名：

<plugin>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-maven-plugin</artifactId>
    <version>0.0.8</version>
    <configuration>
        <mainClass>com.example.demo.App</mainClass>
    </configuration>
</plugin>

配置完成后执行mvn clean javafx:run就可以直接通过Maven启动项目。

• 如果需要生成可以直接双击运行的胖jar（包含所有依赖），再追加maven-shade-plugin配置，把JavaFX依赖和项目代码打包到同一个jar文件中，打包完成后生成的jar不需要额外加启动参数即可直接运行。

3. 模块化项目配置检查 #

如果你的项目根目录存在module-info.java文件，确认文件内已经声明了对应的JavaFX模块依赖，参考配置：

module com.example.demo {
    requires javafx.controls;
    requires javafx.fxml;

    opens com.example.demo to javafx.fxml;
    exports com.example.demo;
}

注意：不要手动把JavaFX的jar文件拷贝到JDK的lib或ext目录下，这种操作会污染JDK环境，后续切换JDK版本、迁移项目时会重复出现依赖问题。

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