IntelliJ Maven项目报错Module not found JavaFX解决方法

云上老周

2026-8-28

问题说明

该问题为JavaFX搭配Maven使用时的高频报错，公开渠道可检索到的通用解决方案均无法解决当前异常
项目环境：通过pom.xml管理依赖的Maven项目，已尝试过同问题的通用解决步骤，未产生效果
当前pom.xml中已声明的JavaFX相关依赖片段如下：

<dependencies>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-controls</artifactId>
            <version>18.0.1</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-base</artifactId>
            <version>18.0.1</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-fxml</artifactId>
            <version>18.0.1</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-graphics</artifactId>
            <version>18.0.1</version>
        </dependency>
        <dependency>
            <groupId>org.openjfx</groupId>
            <artifactId>javafx-media</artifactId>
            <version>18.0.1</version>
        </dependency>
      ...

可行解决步骤

按顺序操作，每做完一步验证一次问题是否解决：

清理本地Maven仓库损坏的JavaFX缓存依赖，在项目根目录执行命令：
mvn dependency:purge-local-repository -DincludeArtifactIds=javafx-*
命令执行完成后，继续执行mvn clean install -U强制从中央仓库拉取全量正确依赖，全程不要点IDE自带的依赖刷新按钮，IDE自带刷新不会清理损坏的本地缓存包。
核对module-info.java配置，模块名必须和官方定义完全一致，拼写错误是高频触发原因：
- fxml模块固定声明为requires javafx.fxml;
- 其余对应依赖的模块声明分别为requires javafx.controls;、requires javafx.base;、requires javafx.graphics;、requires javafx.media;
- 必须补充包开放配置：opens 启动类所在的包路径 to javafx.fxml;，缺这个配置就算依赖拉对了也会报模块找不到或者fxml加载失败。
检查pom.xml里的JavaFX依赖配置，不要手动给任何javafx依赖添加<classifier>标签指定操作系统版本，17及以上版本的OpenJFX会自动匹配当前系统的对应依赖包，手动指定classifier会导致依赖拉取不全，模块元数据缺失。同时确认所有JavaFX依赖的<scope>都是默认的compile，不要设为provided、test等其他作用域，非compile作用域的依赖不会进入模块路径。
清理IDE缓存，以IntelliJ IDEA为例，依次点击File -> Invalidate Caches...，勾选所有缓存清理选项，确认后等待IDE重启，重启完成后重新导入Maven项目，删除之前旧的运行配置后重新创建启动配置。
以上操作都无效的话，直接把所有JavaFX依赖的版本号统一升级到21.0.2（OpenJFX当前长期支持稳定版），18.0.1属于非LTS过渡版本，存在部分发布包模块元数据损坏的已知问题，升级时所有JavaFX依赖版本必须完全一致，严禁版本混用。

注意：如果是模块化项目，不要把JavaFX依赖通过VM参数手动指定路径导入，Maven引入的依赖会自动进入模块路径，手动重复指定路径会触发模块冲突，同样会报模块找不到的错误。

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