Java项目Maven配置核心是确保mvn命令可识别且与JDK版本兼容，需正确设置JAVA_HOME和M2_HOME、使用官方二进制包、配置用户级settings.xml并验证编译成功。
Java项目用Maven管理依赖和构建，核心不是“装完就完”，而是确保 mvn 命令能被系统识别、且与JDK版本兼容——否则会遇到 UnsupportedClassVersionError 或 Command 'mvn' not found 这类问题。
确认JDK已正确安装并配置 JAVA_HOME
Maven 3.9+ 要求 JDK 11 或更高版本，但很多团队仍在用 JDK 8/17。关键不是版本多新，而是 mvn 启动时实际加载的 JDK 必须匹配你项目所需的字节码版本。
- 运行
java -version和echo $JAVA_HOME（Linux/macOS）或echo %JAVA_HOME%（Windows），确认输出路径真实存在且指向 JDK（不是 JRE） -
JAVA_HOME值不能带末尾斜杠（如/usr/lib/jvm/java-17-openjdk✅，/usr/lib/jvm/java-17-openjdk/❌） - Windows 用户注意：PowerShell 和 CMD 可能读取不同环境变量，建议在 CMD 中验证
mvn -v
下载二进制包而非用包管理器安装
Homebrew（macOS）、apt（Ubuntu）、choco（Windows）安装的 Maven 常存在权限、路径或版本滞后问题，尤其当需要指定 M2_HOME 或调试 settings.xml 时更难排查。
- 从 https://www.php.cn/link/5131f6caead4314643b671b624714d94 下载
apache-maven-3.x.x-bin.zip（不要选 src 包） - 解压到无空格、无中文路径下，例如
/opt/maven或C:\maven - 设置
M2_HOME环境变量，指向解压根目录（如/opt/maven），再把$M2_HOME/bin（Linux/macOS）或%M2_HOME%\bin（Windows）加进PATH
验证是否真正生效：不只是 mvn -v
mvn -v 成功只说明命令可执行，不保证本地仓库、镜像、代理等关键配置可用。真正有效的验证是初始化一个最简项目并编译成功。
立即学习“Java免费学习笔记（深入）”；
mvn archetype:generate -DgroupId=com.example -DartifactId=demo -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false cd demo mvn compile
- 如果卡在
Downloading from central:，检查~/.m2/settings.xml是否配置了国内镜像（如阿里云） - 若报错
Could not transfer artifact ... from/to central，大概率是公司网络需配置 HTTP 代理，需在settings.xml的<proxies>段添加 - 首次运行会下载大量插件，耗时可能超过 2 分钟，别误判为失败
settings.xml 放对位置比写对内容更关键
Maven 会按顺序查找三处 settings.xml：Maven 安装目录下的 conf/settings.xml（全局）、用户主目录下的 ~/.m2/settings.xml（用户级）、以及项目根目录的 .mvn/settings.xml（项目级）。只有用户级配置默认生效，其他需显式指定 -s 参数。
- 新手应优先修改
~/.m2/settings.xml，避免影响其他项目 - 配置镜像时，
<id>必须唯一，且<mirrorOf>推荐写成central（不是*），否则可能干扰私有仓库 - 改完别忘了删掉
~/.m2/repository下的org/apache/maven目录，否则旧插件可能缓存导致行为异常
环境配得再标准，只要 JAVA_HOME 和 M2_HOME 不在同一 shell 会话中生效，或者 settings.xml 被放在了 Maven 自己的 conf 目录却没加 -s 参数，mvn clean package 就可能在 CI 上跑通、本地却失败——这种差异才是最耗时间的点。
