Maven无需传统安装，只需解压二进制包并配置M2_HOME与PATH；必须先装好JDK，下载-bin包而非-src包，注意Maven 4需JDK 17+；验证需执行mvn -v及mvn compile最小闭环。
Java项目里Maven到底要不要“安装”
不用装传统意义上的“软件安装包”，Maven本质是一套命令行工具集，核心是 mvn 命令。所谓“安装”，其实是把 Maven 的二进制分发包解压后配置好 M2_HOME 和 PATH，让终端能识别 mvn。JDK 是硬性前置——没装好 java 和 javac，mvn 启动直接报错。
下载与解压 Maven 时的关键选择
去官网 https://www.php.cn/link/5131f6caead4314643b671b624714d94 下载 apache-maven-x.x.x-bin.zip（Windows）或 -bin.tar.gz（macOS/Linux）。别下 -src 包，那是源码，不能直接用。版本建议选最新稳定版（如 4.0.0），但注意：Maven 4 要求 JDK 17+，若项目还在用 JDK 8 或 11，得退回到 3.9.7 或 3.8.8。
-
apache-maven-3.9.7-bin.zip解压后目录结构必须包含bin/mvn（Linux/macOS）或bin/mvn.cmd（Windows） - 路径中避免空格和中文，例如不要放在
C:\Program Files\或/Users/张三/maven，否则mvn执行常卡在初始化阶段 - 解压完先别急着配环境变量，先手动运行一次验证：
./apache-maven-3.9.7/bin/mvn -v（macOS/Linux）或apache-maven-3.9.7\bin\mvn.cmd -v（Windows）
配置环境变量最容易出错的三个地方
Windows 下设 M2_HOME 指向解压根目录（如 C:\tools\apache-maven-3.9.7），再把 %M2_HOME%\bin 加进 PATH；macOS/Linux 在 ~/.zshrc 或 ~/.bash_profile 中写：
export M2_HOME=/opt/apache-maven-3.9.7 export PATH=$M2_HOME/bin:$PATH
常见错误：
你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在
立即学习“Java免费学习笔记（深入）”；
-
M2_HOME指向了bin目录（如/opt/apache-maven-3.9.7/bin），导致mvn找不到lib下的 JAR 包，报Could not find or load main class org.apache.maven.cli.MavenCli - 改完配置没重开终端，或者没执行
source ~/.zshrc，mvn -v仍提示 command not found - 多个 Maven 版本共存时，
which mvn（macOS/Linux）或where mvn（Windows）发现调用的是旧版本，说明PATH里其他路径优先级更高
验证是否真正可用：别只信 mvn -v
mvn -v 只检查命令能否启动、JDK 是否匹配，不代表构建功能正常。下一步必须跑一个最小闭环：
mvn archetype:generate -DgroupId=com.example -DartifactId=demo -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false cd demo mvn compile
如果 mvn compile 成功生成 target/classes，说明本地仓库初始化、插件下载、编译器调用全部通路打通。常见失败点：
- 公司内网没配镜像，
mvn卡在下载maven-metadata.xml—— 需手动编辑$M2_HOME/conf/settings.xml，加<mirror>节点指向内部 Nexus - IDE（如 IntelliJ）没识别到 Maven 安装路径，需在 Settings → Build → Build Tools → Maven 中指定
Maven home path，不能只依赖系统 PATH -
mvn clean package报Failed to read artifact descriptor，大概率是本地仓库（默认~/.m2/repository）损坏，可删掉对应坐标文件夹重试
真正麻烦的从来不是“装上”，而是网络策略、权限限制、多版本冲突这些看不见的链路断点。动手前先确认你有没有权限写入 ~/.m2，公司代理是否拦截了 repo.maven.apache.org，以及 IDE 是否悄悄覆盖了你的 settings.xml。
