Maven从入门到实战：依赖管理、仓库配置与高频报错排查指南

1. Maven到底是什么：先搞懂它解决了什么问题

我经常在群里看到有人问"maven是干嘛的"，然后热心网友回一句"依赖管理工具"，提问的人还是一脸懵。这个回答不能算错，但太单薄了。我从实际项目角度拆一下，你就能理解它对你每天写代码意味着什么。

假设你现在负责一个订单系统，需要用到Spring、MyBatis、Log4j，还要连数据库驱动。没有Maven的时候，你得手动去各个网站下载jar包，放进lib目录，再在IDE里逐个Add as Library。这还只是安装阶段。后续升级组件版本，你得重新下载jar、重新配置；不同模块依赖同一个库的不同版本，冲突起来能让人怀疑人生。这套流程我非常熟悉，因为刚入行那几年就是这么过来的。

Maven把这一切变成三件核心事：

• 依赖管理：用groupId:artifactId:version这一段坐标，从中央仓库自动拉取jar包及其传递依赖。
• 标准化构建：把编译、测试、打包、部署这些动作用固定的生命周期命令串起来，mvn clean package一条命令出可运行产物。
• 统一的工程结构：规定源码、资源、测试、输出目录的位置，团队协作时不用再花时间解释"你的src放哪儿、配置文件放哪儿"。

所以Maven本质上不是"一个下载jar的工具"，而是一套构建模型和项目生命周期管理机制。你只需要在pom.xml里声明"我要什么"，Maven负责搞定"从哪拿、拿到后放哪、怎么编排构建顺序"。理解这一点，后面所有配置和报错排查都是水到渠成的事。

如果你之前只知道"maven是个下载依赖的东西"，那这篇内容会帮你把整张图补全：安装配置、仓库机制、镜像切换、IDE集成、高频报错的排查链路，按实战顺序全部过一遍。

2. 安装与配置：三个平台的实操记录

2.1 版本选择：不要盲目追新

先聊版本。目前生产环境里最常见的是两类系列：3.6.3和3.8.x（包括3.8.6、3.8.8一直往后）。3.6.3是很多老项目的默认选择，稳定、插件兼容性好；3.8.x修复了一些安全问题和bug，对JDK 8~17的支持都很好，也是新项目的常见起点。

有人一上来就想装最新版，我个人建议是：先看项目里已有的.mvn配置或文档要求，如果没有特殊要求，直接选3.8.x系列即可。另外有个热词提到"老系统windows7中安装maven"，这种情况要注意Maven 3.8+某些版本需要较新的JDK支持，而Windows 7能跑的最高JDK版本往往受限，所以老系统继续用3.6.3反而更稳。Maven本身是Java编写的，它的运行前提是系统里已经装好了JDK，mvn -v会同时打印Maven版本和它使用的Java版本，两者是绑定的。

下载入口建议认准官方地址：maven.apache.org/download.cgi。不要从第三方站点下压缩包，我见过太多因为下载了被篡改的包导致依赖拉取异常或者构建报错的案例。

2.2 Windows安装与环境变量配置

Windows下的安装流程，搜索热词里反复出现"maven安装与配置"和"maven环境变量配置"，说明这一步确实卡了很多人。拆开来说。

第一步：解压与目录规划。下载apache-maven-3.8.x-bin.zip后，解压到一个路径中不包含中文和空格的目录，比如D:\tools\apache-maven-3.8.8。注意，解压出来的是apache-maven-3.8.8这样的目录，里层是bin、conf、lib等子目录。很多人配置错了环境变量，就是因为在MAVEN_HOME里多写了一层或写错了位置。

第二步：配置环境变量。按Win键搜索"环境变量"，打开系统属性里的环境变量设置窗口，按顺序操作：

• 新建系统变量MAVEN_HOME，值填Maven解压路径，例如D:\tools\apache-maven-3.8.8。
• 找到Path变量，点击编辑，新增一行%MAVEN_HOME%\bin。
• 不要新建一个叫PATH的变量，也不要把MAVEN_HOME写进用户变量和系统变量各一份，只要系统变量里一份就够了。

第三步：验证。重新打开一个命令行窗口（重要，旧窗口不刷新环境变量），执行：

mvn -v

正常输出里能看到Maven home、Java version等信息。如果提示"mvn 不是内部或外部命令"，按这个顺序排查：环境变量是否保存后窗口重启、MAVEN_HOME路径是否真的指向了包含bin的那一层、Path里是否写的是%MAVEN_HOME%\bin而不是%MAVEN_HOME%。

2.3 macOS与Linux安装

macOS下常见两种方式：手动解压配置或通过Homebrew。热词里"maven下载安装与配置mac"说明很多人还是习惯手动操作。手动流程和Windows思路一致：下载apache-maven-3.8.x-bin.tar.gz，解压到/usr/local/或用户目录，然后编辑~/.zshrc（或~/.bash_profile，取决于shell），写入：

export MAVEN_HOME=/usr/local/apache-maven-3.8.8 export PATH=$MAVEN_HOME/bin:$PATH

然后执行source ~/.zshrc刷新。Homebrew方式更省事：

brew install maven

装完直接mvn -v验证，但用Homebrew装的话包版本可能不是最新，如果你需要特定版本（比如项目指定3.6.3），还是手动解压更可控。

Linux同理，解压到/opt或/usr/local后配置/etc/profile或用户级环境变量。服务器上常见的坑是：JDK装了但JAVA_HOME没导，Maven能跑但依赖某些插件时会出现找不到Java相关的错误。所以Linux环境务必确认JAVA_HOME和PATH都正确。

2.4 验证安装后的信息解读

mvn -v输出里值得注意的不只是版本号。它还会显示Java version和系统信息。如果你发现Maven默认识别的JDK版本和你项目需要的不一致，不要慌，两个解决方向：

• 修改JAVA_HOME环境变量指向期望的JDK路径。
• 在项目的.mvn/jvm.config或IDE的Maven Runner配置里单独指定JDK路径。

这个细节在"id"配置里经常被忽略，但很多构建报错（比如编译时用了Java 8语法却拿Java 11去跑，或者反过来）都跟它有关。

3. 仓库机制与镜像配置：local仓库、中央仓库与阿里云

3.1 本地仓库是什么，默认在哪

Maven做的第一件事，是检查你本地有没有对应的jar包。这个"本地缓存区"就是本地仓库（local repository）。默认位置在用户目录下的.m2/repository，例如Windows是C:\Users\你的用户名\.m2\repository，Linux和macOS是~/.m2/repository。

我强烈建议不要在系统盘放本地仓库。原因很简单：依赖动辄几个GB，重装系统或者系统盘空间紧张都会让你痛苦。改位置的方式是在conf/settings.xml或用户级~/.m2/settings.xml里配置：

<settings> <localRepository>D:/maven-repository</localRepository> </settings>

注意这里的路径分隔符用正斜杠，Windows下也不要写反斜杠。另外要理解两个settings.xml的区别：conf/settings.xml是全局配置，~/.m2/settings.xml是当前用户的配置，后者的优先级更高。排查问题的时候先确认你改的是哪一个，很多"我怎么配置了没生效"的问题都出在这里。

3.2 配置阿里云镜像：解决下载慢的黄金方案

热词里"maven配置阿里云仓库"是搜索量非常高的一个。为什么需要它？因为默认的中央仓库服务器在国外，国内下载快的时候几百KB/s，慢的时候直接超时。阿里云Maven镜像在国内几乎是标配。

在settings.xml的mirrors节点里加入：

<mirror> <id>aliyunmaven</id> <mirrorOf>central</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>

这里稍微解释一下工作原理：mirrorOf表示这个镜像要拦截哪些仓库的请求，central表示拦截中央仓库。也就是说，当你声明依赖时，Maven本来要去中央仓库下载，现在会被这个镜像接管。阿里云public仓库聚合了central和jcenter的绝大部分内容，日常项目够用了。

配置完之后，执行任意依赖下载命令时，能看到日志里解析的URL已经变成https://maven.aliyun.com/repository/public，说明镜像生效。如果还是显示repo.maven.apache.org，要么是你改错了settings.xml（改成了全局生效但被用户级覆盖），要么是IDE里配置的Maven settings路径不对，指向了别的文件。

3.3 配置多个镜像仓库的注意事项

有人因为某些私有依赖需要同时用多个仓库，问"maven配置多个镜像仓库"怎么搞。先说结论：**mirror适合做中央仓库的替代或拦截，但如果你需要从多个真实仓库拿依赖，应该是配置repositories而不是多个mirror。**这是个非常容易混淆的点。

两个mirror的典型场景反而是"一个镜像负责拦截central，另一个拦截其他远程仓库"，比如：

<mirror> <id>aliyunmaven</id> <mirrorOf>central</mirrorOf> <url>https://maven.aliyun.com/repository/public</url> </mirror> <mirror> <id>aliyun-public-snapshots</id> <mirrorOf>snapshots</mirrorOf> <url>https://maven.aliyun.com/repository/snapshots</url> </mirror>

如果你只是想在项目的pom.xml里声明多个远程仓库，写法是：

<repositories> <repository> <id>my-repo</id> <url>https://nexus.example.com/repository/maven-public/</url> </repository> </repositories>

多个repository会自动按顺序轮询查找依赖。但要注意，mirror和repository不要配置出互相矛盾的逻辑，比如一个mirror拦截了所有仓库又声明了私有仓库，结果私有依赖永远走镜像去拉，导致404。排查这类问题，可以用mvn dependency:tree或者mvn -X看解析日志。

3.4 仓库网页版入口

热词里"maven仓库网页版入口"和"maven仓库网页版"让我确认一下大家想问的其实是：我想在浏览器里搜索某个依赖的坐标，去哪儿搜？两个最高频的入口：

• 中央仓库搜索：search.maven.org，官方，全、权威，支持Maven坐标检索。
• 阿里云仓库搜索：developer.aliyun.com/mvn/search，国内访问快，还能直接看到group、artifact、version列表，复制坐标很方便。

这两个地方都支持搜"某个库的最新版本"和"某个版本是否存在于仓库中"。排查依赖版本问题时，先在这里确认坐标存在性，再去找本地配置的毛病，能省很多时间。

4. 核心配置：pom.xml与依赖管理实战

4.1 最小pom.xml结构

每新建一个Maven工程，根目录下都要有一个pom.xml，它就是这个项目的"说明书"。一个最小可用的pom长这样：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>demo-project</artifactId> <version>1.0.0</version> <packaging>jar</packaging> <properties> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <dependencies> ... </dependencies> </project>

groupId通常对应公司域名倒序，artifactId是模块名，version是版本号。这三个合起来是Maven里的坐标，Maven靠它去仓库里精确定位一个jar包。你会看到网上很多人问"maven依赖管理"到底管什么，本质上就是管这些坐标之间的解析、下载和版本冲突调整。

packaging有jar、war、pom三种常见值。多模块项目里父pom的packaging一定是pom，它的<modules>节点里声明子模块。这个结构在构建大型系统时是必须掌握的，否则你只能一直堆单模块项目，模块间代码复用全靠复制粘贴。

4.2 依赖Scope：别小看这个属性

依赖声明里最常见的属性包括scope和optional，很多人初级学习时写依赖只会复制粘贴，从没注意过scope。Scope表示依赖在哪些阶段生效，直接影响打包结果和运行时行为：

最典型的一个坑：开发Web应用时，servlet-api这类依赖应该用provided，因为Tomcat等容器自带。有人习惯性什么都不写，结果打包出可执行jar或war部署到服务器后，出现类冲突或NoSuchMethodError，就是因为把容器要提供的东西也塞进去了。

optional和provided经常被搞混。optional表示"本项目会用到这个依赖，但使用方可以选择不传递下去"。比如一个工具包内部用了某个日志实现，但允许使用者自己决定日志框架，它就会把日志依赖标成optional。理解了这两个属性，你在排查"为什么我引入A依赖却多了一堆jar"时，思路会清晰很多。

4.3 依赖传递与版本冲突

依赖传递是Maven省心的地方，也是出幺蛾子的地方。你写了spring-webmvc，它会自动把spring-core、spring-beans等一串jar拉进来。但当你多个模块引入了不同版本的同一坐标时，Maven有一套固定的冲突仲裁规则：

• 最近依赖原则：依赖树中离当前项目最近的那一级优先。
• 最先声明原则：同一深度下，先声明的优先。

听起来很清楚，实际项目里还是会出现你很确信引入了A版本，最后运行却加载了B版本的情况。这时候别猜，直接用命令在项目根目录执行：

mvn dependency:tree -Dverbose

-Dverbose会输出每个依赖的完整路径和冲突细节。能直观看到某个坐标"omitted for conflict"是在哪个分支里被主导掉的。定位到冲突后，解决方式两种：在dependencyManagement里统一指定版本，或者用exclusion排除不需要的传递依赖：

<dependency> <groupId>org.springframework</groupId> <artifactId>spring-context</artifactId> <version>5.3.30</version> <exclusions> <exclusion> <groupId>commons-logging</groupId> <artifactId>commons-logging</artifactId> </exclusion> </exclusions> </dependency>

还有一个经验之谈：别为了图省事把<dependencyManagement>扔在子项目里。它是用来统一管控版本的地方，应该放在父pom，子模块声明依赖时不写版本号，从父pom继承。

4.4 常用命令：clean、install、package、deploy

热词里"maven命令行 clean install"是最高的，我按实际使用频率排序说明。

• mvn clean：删除target目录，清掉上一次构建的产出物。
• mvn compile：只编译到target/classes。
• mvn test：编译并跑单元测试。
• mvn package：编译+测试+打包，产出jar或war到target。
• mvn install：把构建产物安装到本地仓库，供其他本地模块引用。
• mvn deploy：把构建产物部署到远程仓库（私服），供团队其他人拉取。

很多人问"clean install和package的区别"。核心区别在于install不只是打包，它还把产物安装到了本地仓库。多模块项目里，如果B依赖A，你改了A之后只mvn package，B去引用A时还是会从本地仓库里拿旧的A，必须对A执行mvn install才能让更新生效。这个点我见过无数人踩坑：改了底层模块，怎么跑上层都还是旧行为，最后发现是没install。

这些命令是可以组合的，mvn clean install -DskipTests是日常最常用的一条。-DskipTests只是跳过测试执行，但会编译测试代码；-Dmaven.test.skip=true连测试代码都不编译。两者区别在并发拉代码换分支时很有用。

5. IDE集成：IDEA、Eclipse、VSCode中的Maven日常

5.1 IntelliJ IDEA中的Maven配置

热词里有一系列IDEA相关的："idea设置maven默认配置"、"idea maven工具栏不见了"、"idea创建maven工程src"等。IDEA自带内置Maven，但很多项目对Maven版本有要求，所以大家都会改成自己装的版本。配置入口在File -> Settings -> Build, Execution, Deployment -> Build Tools -> Maven，关键设置有三处：

• Maven home path：选择你自己安装的Maven目录。
• User settings file：指定settings.xml，通常是~/.m2/settings.xml，勾选Override让右侧路径可编辑。
• Local repository：会跟着settings.xml自动读取，如果没自动更新，可以手动指到本地仓库目录。

如果你想让所有新项目都默认用这套配置，IDEA是支持把设置设为默认的。在Settings里改完后，File -> New Projects Settings -> Settings for New Projects，同样一套配置在"新项目"窗口里再设置一次即可。很多人的问题是：当前项目正常，一新建项目Maven配置就变回内置了，就是这个"新项目设置"没改。

还有一个经典场景：IDEA的Maven JDK配置。在Maven -> Runner里有个JRE选项，默认可能是Use Project JDK。如果项目要用不同JDK构建，在这里显式指定。否则可能出现命令行下mvn package正常，IDEA里点构建却报错的情况。

5.2 IDEA maven工具栏不见了

"idea maven工具栏不见了"这个问题很多新手遇到，原因是IDEA右侧或顶部的Maven工具窗口被误关了。恢复方式：右侧边缘如果没有Maven垂直标签栏，打开View -> Tool Windows -> Maven。如果这样还找不到，检查File -> Settings -> Plugins里Maven插件是否被误禁用。另外Project Structure里确认项目还被识别为Maven项目：右键项目根目录 ->Add Framework Support，找Maven。

还有一个隐蔽情况：IDEA打开的不是pom.xml所在的根目录，而是某个子目录，也会导致Maven工具栏消失。这种情况用File -> Open重新选中pom.xml所在的目录打开。

5.3 IDEA创建Maven工程时src目录缺失

"idea创建maven工程src"这个热词一般是两类情况。一类是创建完Maven项目后，标准的src/main/java、src/main/resources、src/test/java没生成，需要手动建。手动建的目录如果颜色不对（不是蓝色Sources Root），右键目录 ->Mark Directory as -> Sources Root。另一类是创建时选的Archetype问题，maven-archetype-quickstart是最常用的基础骨架，选它一般能带出标准结构。

实际工作中我建议大家尽量用Maven Archetype创建而不是手工搭目录，但如果你是用IDEA的Spring Initializr，那生成的就是Gradle/Maven工程，不存在src缺失问题。要是用了某个冷门Archetype导致结构很怪，最稳妥的做法是删掉重新用quickstart创建。

5.4 Eclipse与VSCode/Cursor中的Maven

Eclipse里新建Maven项目，路径是File -> New -> Other -> Maven -> Maven Project，选择quickstart骨架后填写group和artifact。Eclipse的Maven配置在Window -> Preferences -> Maven -> Installations里添加你自己装的Maven，同时User Settings里指定settings.xml。Eclipse默认内嵌的Maven版本往往偏老，建议替换成3.8.x。

VSCode和Cursor里配置Maven，核心靠扩展。搜索并安装Maven for Java扩展，然后确认settings.json里的相关配置：maven.executable.path指向你本地的mvn路径，如果没有配置会尝试用内置。Cursor本质上是VSCode的分支，配置方式一样，所以热词里"cursor怎么配置java和maven"其实就是在VSCode那套逻辑下配好JDK和Maven，两个扩展：Extension Pack for Java+Maven for Java，装完在侧边栏会出现MAVEN面板。注意，命令行能不能跑mvn和IDE里能不能识别Maven项目是两回事：命令行依赖环境变量，IDE依赖扩展配置，两者都要各自确认。

6. 高频报错排查：从"download from maven failed"到依赖标红

6.1 download from maven failed的完整排查链路

热词里"intellij idea sqlserver jdbc 自动下载 download from maven failed"这类问题非常典型。你在IDEA里引入某个JDBC驱动或任意依赖时，IDE自动去下载，结果提示download from maven failed。出现这个报错，按下面顺序排查，基本能覆盖九成场景。

第一，确认坐标是否正确。先到search.maven.org搜一下你写的groupId:artifactId:version是否存在。常见问题是版本号写错、artifact名拼错，或者某个版本在阿里云镜像里同步不全而中央仓库里有。

第二，确认settings.xml镜像是否能用。如果你配了阿里云镜像，先看本地仓库里有没有残留的下载失败标记。Maven下载失败后会在本地仓库生成.lastUpdated结尾的文件，同时存在_remote.repositories标记。这些文件会让Maven在一段时间内不去重新下载。解决方式是删除对应目录下的.lastUpdated和*.lastUpdated文件，或者用强制更新参数重新拉：

mvn clean install -U

-U表示强制检查更新，会强制刷新SNAPSHOT依赖并清除一些失败缓存。在IDEA里对应的是Settings -> Maven -> Always update snapshots勾选，或者点Maven工具窗口的刷新按钮加-U参数。

第三，确认网络能访问配置的仓库地址。直接在浏览器打开镜像URL或中央仓库URL，看能否访问。如果地址配置没问题但下载超时，大概率是网络代理或防火墙问题。公司内网环境尤其要注意：IDEA的HTTP Proxy设置（Settings -> Appearance & Behavior -> System Settings -> HTTP Proxy）如果开了代理但代理失效，所有下载都会失败。这时候选Auto-detect或No proxy分别试一下。

6.2 依赖报错：jar包标红与无法解析依赖

IDEA里pom.xml中某个依赖红色下划线或Cannot resolve dependency，是最常见的问题。我的排查习惯是这套组合拳。

先看Event Log和IDEA右下角提示，有时是Maven项目导入失败，而不是依赖本身有问题。然后检查IDEA的Maven配置有没有选对settings.xml和本地仓库，见5.1。如果配置都对，关掉项目重新导入Maven工程：右键pom.xml ->Maven -> Reload project。注意是Reload project不是Reimport，两个动作效果不同，Reload会重新读取整个Maven模型，我遇到的大多数"生效不了"都能靠这个解决。

如果重新加载还是红，把IDEA里Maven的输出日志打开，Help -> Show Log in Explorer，搜索报错关键字。很多时候真正的原因藏在日志里，比如某个仓库需要认证返回401、某个镜像不支持某类协议、或者settings.xml本身有语法错误。settings.xml语法错误是个很隐蔽的原因，IDEA不会直接弹出来，但Maven解析时直接忽略整个文件，导致你用着默认配置却不自知。验证方法很简单：命令行执行mvn help:effective-settings，看实际生效的settings内容，如果和你预期不一致，八成就是语法或路径问题。

6.3 私有仓库认证与snapshot仓库的坑

企业内部搭建私服后，经常遇到依赖拉取401或404。这里有两个容易忽视的点。

一是认证信息必须配置在settings.xml里，不能写进pom.xml。常见的server配置如下：

<servers> <server> <id>my-nexus</id> <username>deployer</username> <password>password</password> </server> </servers>

其中id必须和pom.xml里repositories的id一致，Maven才会用这组账号密码去访问对应仓库。

二是snapshot版本与release版本解析的机制不同。默认情况下，Maven不会去远程仓库频繁检查SNAPSHOT更新，除非配置了updatePolicy或使用-U。如果你改了version为1.0.0-SNAPSHOT但始终拉到旧快照，先在dependency:tree里看实际解析到的版本，再决定是刷新元数据还是强制更新：

<repositories> <repository> <id>my-snapshots</id> <url>https://nexus.example.com/repository/maven-snapshots/</url> <snapshots> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </snapshots> </repository> </repositories>

updatePolicy的可选值有always、daily、interval:X、never。日常开发中快照依赖我倾向用always，避免"我依赖的那个模块改了却拉不到"问题；正式构建流程里则建议用daily或never，保证可重复构建。

6.4 几个容易忽略但频率很高的杂项问题

最后把一些不是Maven本身但经常跟Maven绑定出现的问题整理出来，这些都是我自己踩过、身边人也反复踩的坑。

编码问题。项目里中文注释或资源文件乱码，根源往往是project.build.sourceEncoding没设置，或者IDE与Maven的编译编码不一致。在pom.xml中固定为UTF-8：

<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

同时IDEA的Settings -> Editor -> File Encodings里Global Encoding和Project Encoding都设成UTF-8。不统一的话，同一段代码在Windows和macOS上编译结果可能都不一样。

JDK版本不一致。有时mvn clean install命令行一切正常，但IDEA里构建报"invalid target release"或"错误: 不支持发行版本"。原因几乎总是Maven Runner用的JDK与pom里maven.compiler.source/target不匹配。见过太多次pom里写1.8，但Runner JRE选了Java 17，然后报错。解决方式是把pom的源码/目标版本调成与项目JDK一致，或在IDEA的Maven Runner里显式指定正确JDK。

资源文件没打进去。默认情况下Maven只把src/main/resources里的资源文件复制到classpath，如果你把配置文件放在了src/main/java目录下，打包后就找不到。这个问题在热词里虽然没有直接出现，但几乎所有Maven新手都碰到过。解决办法是统一放到src/main/resources下，或者在pom里补充<resources>配置。

多模块项目install顺序。多模块执行mvn clean install时，Maven会自动按依赖关系排序构建，不需要你手动一个模块一个模块install。但如果你用IDE分别对单个模块操作，就得牢记：底层模块改了必须install，上层模块才能看到变化。这个我在4.4提过，值得再强调一次，因为它是多模块开发中最常见的"好像改了但没生效"的原因。

关于JavaFX的Maven配置。热词里有"javafx的maven配置"，简单提一句：JavaFX从JDK 11开始不再是JDK的一部分，需要单独加依赖。Oracle官方推荐的org.openjfx:javafx-controls、javafx-maven-plugin这套组合，版本要和你的JDK大版本对应。配置时最容易错的是把javafx-maven-plugin的mainClass写错，导致mvn javafx:run时找不到入口。这个插件会编译并运行JavaFX应用，适合本地调UI；真正打包分发时一般还会用jlink或jpackage，那又是另一个话题了。

我个人在实际操作里的最大体会是：Maven排错的核心不是背报错信息，而是会看位置。一个依赖报错，你要能快速定位出是坐标问题、仓库问题、settings问题还是本地缓存问题，这四类问题的处理方式完全不同。所以我一直建议团队里每个新人都试着在命令行里手动跑一遍mvn clean install，不要一上来就依赖IDE。命令行相当于Maven的"公开日志"，报错信息更全，IDE只是把很多东西藏起来了。命令行跑通了，再回IDE，配合起来才不容易被各种表面现象带偏。后面如果你们团队开始接触持续集成流水线，这些命令行基础也是直接可以平移过去的。