JavaFX 21模块化Maven项目javafx-media运行时类找不到及模块异常解决

我用Maven和module-info.java开发JavaFX 21桌面应用，为实现背景视频播放给pom.xml添加了javafx-media依赖，但运行时抛出以下错误：

Caused by: java.lang.ClassNotFoundException: javafx.media.MediaView
    at javafx.fxml@21.0.2/javafx.fxml.FXMLLoader.loadTypeForPackage(FXMLLoader.java:3062)
    ...

环境信息 #

• Java版本：21.0.10
• JavaFX版本：21.0.2
• 构建工具：Maven
• IDE：IntelliJ IDEA 2025.3.2

当前配置 #

pom.xml依赖 #

<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.openjfx</groupId>
    <artifactId>javafx-media</artifactId>
    <version>${javafx.version}</version>
</dependency>

module-info.java #

module com.plasticstock {
    requires javafx.controls;
    requires javafx.fxml;
    requires javafx.media;
    requires java.sql;

    opens com.plasticstock to javafx.fxml;
    opens com.plasticstock.controllers to javafx.fxml;
    opens com.plasticstock.models to javafx.base;

    exports com.plasticstock;
    exports com.plasticstock.controllers;
    exports com.plasticstock.models;
}

已尝试的操作 #

• 确认javafx-media已下载并显示在IDEA的「External Libraries」中
• 多次执行mvn clean install
• 清除IntelliJ缓存并重启IDE
• 在VM选项中添加--add-modules javafx.media，但触发java.lang.module.FindException: Module javafx.media not found异常

解决方法 #

1. 添加OpenJFX Maven插件配置 #

JavaFX模块化项目必须通过OpenJFX的Maven插件处理模块路径，仅添加依赖无法确保运行时模块被正确识别。在pom.xml的<build>节点下添加以下插件：

<build>
    <plugins>
        <plugin>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-maven-plugin</artifactId>
            <version>0.0.8</version>
            <configuration>
                <mainClass>com.plasticstock.Main</mainClass> <!-- 替换为你的主类全路径 -->
                <modules>
                    <module>javafx.controls</module>
                    <module>javafx.fxml</module>
                    <module>javafx.media</module>
                </modules>
            </configuration>
        </plugin>
    </plugins>
</build>

该插件会自动将JavaFX模块添加到运行时的模块路径，无需手动配置--add-modules参数。

2. 调整IDEA运行配置 #

• 打开IDEA的「运行/调试配置」，选择你的JavaFX应用配置
• 删除「VM options」中手动添加的--add-modules javafx.media参数
• 将「Build and run using」设置为Maven，确保使用Maven插件的配置启动应用

3. 验证版本一致性 #

确认pom.xml中${javafx.version}变量的值为21.0.2，保证所有JavaFX依赖版本统一，避免版本不匹配导致的模块加载异常。

4. 用Maven插件直接启动应用 #

执行以下命令彻底清理并启动项目：

mvn clean javafx:run

通过javafx:run目标启动，确保Maven插件全程处理模块路径和依赖加载。

关键原因 #

JavaFX模块属于命名模块，无法通过普通classpath加载，必须通过模块路径（module path）提供。手动添加--add-modules时若未正确配置模块路径，就会出现找不到模块的异常；而OpenJFX Maven插件会自动完成模块路径的配置，确保运行时能正确识别所有JavaFX模块。

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