java项目pom.xml报错、mvn命令无效，根本原因是maven未正确安装配置：需先确认jdk已装并配好java_home，再下载官方maven二进制包、解压至无中文路径，接着配置maven_home与path，最后修改settings.xml启用阿里云镜像并重定向本地仓库。
刚接触Java项目，一打开pom.xml就满屏红色报错，mvn命令提示“不是内部或外部命令”，依赖死活下不下来——这不是你代码写错了，而是Maven根本没装对、没配好。从JDK检查到本地仓库路径，每一步都卡在细节上，新手最容易在这里反复折腾两三天。
确认JDK已正确安装并生效
这一步跳过，后续所有操作都会失败。Maven是Java写的，没有JDK它连启动都不行。
打开CMD（Windows）或Terminal（Mac/Linux），输入：java -version
必须看到类似“java version "1.8.0_381"”或“11.0.15”的输出。如果提示“不是内部或外部命令”，说明JAVA_HOME没配，或者系统根本没装JDK——请立刻去Adoptium或Oracle官网下载JDK 8或11，安装后重启终端再试。
注意：JDK安装后必须手动配置JAVA_HOME环境变量，仅安装不配置等于没装。
下载与解压Maven（选对版本、放对位置）
别直接搜“Maven下载”，容易进第三方镜像站或下载源码包。只认准一个地址：https://maven.apache.org/download.cgi
Windows用户下载 apache-maven-xxx-bin.zip（不是source.zip）；Mac/Linux用户下载 apache-maven-xxx-bin.tar.gz。
解压路径严禁含中文、空格、特殊符号。推荐直接解压到：
D:\maven（Windows）
/usr/local/maven（Mac）
/opt/maven（Linux）
【关键提醒】 如果解压到“D:\我的软件\Maven 3.9.6”，后续执行mvn命令时会报错“无法识别路径”，且错误信息极其隐晦，排查耗时超2小时。
配置MAVEN_HOME与PATH环境变量
这是让系统全局识别mvn命令的唯一方式。路径写错、大小写混淆、漏掉\bin，三者任一都会导致命令无效。
第一步：新建系统变量
变量名：MAVEN_HOME（必须全大写，一个字母都不能错）
变量值：Maven解压后的根目录完整路径（例如 D:\maven\apache-maven-3.9.6）
第二步：编辑系统变量Path
在Path变量里新增一行：%MAVEN_HOME%\bin（Windows）或 $MAVEN_HOME/bin（Mac/Linux）
第三步：验证是否生效
关闭所有已打开的CMD/Terminal窗口，重新打开一个，执行：mvn -v
成功时会显示Maven版本、Maven home路径、Java version三行信息。
如果仍报“mvn不是内部或外部命令”，请立即检查：①是否重启了终端；②MAVEN_HOME变量值末尾有没有多余空格；③Path里是否误写了%MAVEN_HOME%/bin（斜杠方向错误）。
修改settings.xml加速依赖下载
默认用中央仓库下载依赖，国内用户大概率超时失败。必须换阿里云镜像，否则连第一个Spring Boot依赖都拉不下来。
找到Maven解压目录下的 conf/settings.xml 文件，用记事本或VS Code打开。
定位到 <mirrors></mirrors> 标签内（通常在文件中后部），在 前插入以下配置：
<mirror><br> <id>nexus-aliyun</id><br> <mirrorof>central</mirrorof><br> <name>Nexus aliyun</name><br> <url>https://maven.aliyun.com/repository/public</url><br></mirror>
保存文件。这一步做完，下次执行mvn compile或mvn clean install时，依赖下载速度将从几kb/s提升至1–3MB/s。
重定向本地仓库到非系统盘
默认仓库在C盘用户目录下（如 C:\Users\XXX\.m2\repository），首次构建可能瞬间占满几十GB空间，且C盘满了会导致IDE卡死、编译失败。
在同一个 conf/settings.xml 文件中，搜索 <localrepository></localrepository>，将其替换为：
<localrepository>D:\.m2\repository</localrepository>（Windows）
或<localrepository>/Users/xxx/.m2/repository</localrepository>（Mac，建议放在非系统分区）
注意：该路径必须是**已存在的空文件夹**，Maven不会自动创建父级目录。若D:\.m2不存在，请先手动创建该目录。
