安装与验证

本章承接"Maven 是什么"与"约定优于配置"，将理论落地为实践。安装 Maven 并验证环境，是后续所有命令操作（创建项目、编译打包、依赖管理）的物理前提。

核心机制

Apache Maven 官方安装文档的定位非常明确：

Maven 是一个基于 Java 的工具，唯一的先决条件是安装 JDK。官方强调了两点：

Maven 本身是用 Java 编写的，因此运行 Maven 需要 JVM 环境
Maven 不是安装包（installer），而是压缩包（archive），解压即用，无需执行安装向导

这意味着 Maven 的"安装"本质上是解压 + 配置环境变量，而不是传统 Windows 软件的"下一步→下一步→完成"。

Maven 的"安装"到底在做什么？

当你下载并"安装"Maven 时，实际上是在完成三件事：

步骤	操作内容	目的
1. 获取分发包	下载 `apache-maven-3.9.x-bin.zip` 或 `.tar.gz`	获得 Maven 的运行时文件
2. 解压到本地	解压到无中文、无空格的目录（如 `C:\apache-maven-3.9.6`）	让系统能找到 Maven 的可执行文件
3. 配置环境变量	设置 `MAVEN_HOME` 和 `Path`	让命令行任何位置都能执行 `mvn` 命令

为什么需要 `MAVEN_HOME` 和 `Path` 两个变量？

MAVEN_HOME：告诉系统"Maven 住在哪里"。它指向 Maven 的根目录（包含 bin/、conf/、lib/ 的目录）。这个变量本身不直接参与命令查找，但它是 Maven 内部脚本（如 mvn 脚本）定位自身资源的基础。
Path：告诉系统"去哪里找可执行程序"。将 %MAVEN_HOME%\bin（Windows）或 $MAVEN_HOME/bin（Linux/Mac）加入 Path 后，你在任何目录输入 mvn，操作系统都知道去 bin/ 目录下找 mvn 可执行文件。

生活类比：给快递小哥一张准确的地址卡

想象你（开发者）要叫快递（执行 mvn 命令）来家里取件：

MAVEN_HOME 就像你家的小区名称和楼栋号。快递系统需要知道"Maven 小区 3 号楼"的存在。
Path 就像你写在订单上的详细门牌号。快递小哥根据门牌号（bin/ 目录）直接找到你家门口，而不是在小区里迷路。

如果只写小区名（只有 MAVEN_HOME），快递知道你在哪个小区，但找不到具体楼栋；如果只写门牌号（只有 Path），快递可能找到楼栋，但不知道小区配套设施（如 conf/settings.xml）在哪。两者缺一不可。

图示

上图展示了 Maven 安装的完整链路：下载 → 解压 → 配置环境变量 → 验证。注意 JAVA_HOME 是隐式依赖——如果 JDK 未安装或未配置，mvn -v 会报错，因为 Maven 本身需要 JVM 才能运行。

完整示例

场景

飞翔科技来了一位新后端开发小崔。CTO 大翔要求所有开发者的环境必须统一：JDK 17 + Maven 3.9.6。架构师白歌负责指导小崔完成安装，运维李眉负责验收。

操作前：环境检查

小崔的电脑是一台 Windows 11 笔记本，已经安装了 JDK 17，但尚未安装 Maven。白歌先让小崔确认 JDK 是否正常：

java -version

预期输出：

openjdk version "17.0.8" 2023-07-18 LTS
OpenJDK Runtime Environment (build 17.0.8+7-LTS)
OpenJDK 64-Bit Server VM (build 17.0.8+7-LTS, mixed mode, sharing)

如果这里报错，说明 JDK 未安装或未配置 JAVA_HOME，必须先解决，否则 Maven 无法运行。

操作步骤

步骤 1：下载 Maven

小崔访问 Maven 官方下载页，选择 Binary zip archive：

apache-maven-3.9.6-bin.zip

注意：下载 -bin.zip（二进制分发包），而不是 -src.zip（源码包）。源码包是给想研究 Maven 内部实现的人用的，普通开发者只需要二进制包。

步骤 2：解压到指定目录

小崔将压缩包解压到 C:\apache-maven-3.9.6。解压后的目录结构如下：

C:\apache-maven-3.9.6
├── bin/                 # 可执行脚本（mvn、mvnDebug）
├── boot/                # 类加载器相关
├── conf/                # 全局配置文件（settings.xml）
├── lib/                 # Maven 核心依赖 JAR
└── LICENSE、NOTICE、README

关键要求：解压路径不能包含中文或空格。例如 C:\Program Files\apache-maven-3.9.6 会导致某些脚本解析异常，C:\工具\maven 更会导致不可预知的错误。

步骤 3：配置环境变量（Windows）

小崔打开"系统属性 → 高级 → 环境变量"，在系统变量区域操作：

新建 MAVEN_HOME：

变量名：MAVEN_HOME
变量值：C:\apache-maven-3.9.6

编辑 Path，新建一行：

%MAVEN_HOME%\bin

注意：Windows 10/11 的 Path 是列表形式，直接点"新建"添加一行即可。不要在原有路径后面用分号拼接，那样容易出错。

步骤 4：配置环境变量（Linux / Mac）

白歌告诉小崔，如果公司配发的是 Linux 工作站（如 Ubuntu 22.04），配置方式略有不同。编辑 ~/.bashrc 或 ~/.zshrc：

# 解压到 /opt 目录（Linux 惯例）
sudo tar -xzf apache-maven-3.9.6-bin.tar.gz -C /opt/

# 配置环境变量
echo 'export MAVEN_HOME=/opt/apache-maven-3.9.6' >> ~/.bashrc
echo 'export PATH=$MAVEN_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Mac 用户如果使用 Homebrew，可以一键安装：

brew install maven

但大翔要求团队统一使用官网下载的 3.9.6 版本，避免 Homebrew 自动升级导致版本不一致，所以小崔的 Mac 也采用手动解压方式。

步骤 5：验证安装

小崔打开新的命令行窗口（环境变量修改后必须新开窗口才能生效），执行：

mvn -v

预期输出：

Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)
Maven home: C:\apache-maven-3.9.6
Java version: 17.0.8, vendor: Oracle Corporation, runtime: C:\Program Files\Java\jdk-17
Default locale: zh_CN, platform encoding: GBK
OS name: "windows 11", version: "10.0", arch: "amd64", family: "windows"

操作结果及分析

李眉验收时，重点检查输出中的四个信息：

输出项	含义	验收标准
`Apache Maven 3.9.6`	Maven 版本	必须与大翔规定的 3.9.6 一致
`Maven home`	Maven 安装路径	必须是无中文、无空格的路径
`Java version: 17.0.8`	JDK 版本	必须是 JDK 17，不能是 JDK 8 或 21
`OS name`	操作系统	确认平台信息，排查跨平台问题

如果 mvn -v 能正常输出以上信息，说明 Maven 已正确安装，小崔可以开始后续的项目操作了。

易错点与常见问题

误区一：`MAVEN_HOME` 指向了 `bin` 目录

错误配置：

MAVEN_HOME = C:\apache-maven-3.9.6\bin   ❌
Path = %MAVEN_HOME%                       ❌

后果：mvn 命令虽然能找到（因为 bin 在 Path 里），但 Maven 内部脚本需要读取 conf/settings.xml 和 lib/ 下的 JAR，它们相对于 MAVEN_HOME 的路径是 ../conf 和 ../lib。如果 MAVEN_HOME 指向 bin，Maven 会找不到配置文件，导致构建异常。

正确配置：

MAVEN_HOME = C:\apache-maven-3.9.6        ✅
Path = %MAVEN_HOME%\bin                   ✅

误区二：环境变量修改后没有重启命令行

错误现象：配置完 MAVEN_HOME 和 Path 后，在原来的命令行窗口执行 mvn -v，提示"'mvn' 不是内部或外部命令"。

纠正：Windows 的环境变量只在进程启动时加载一次。已经打开的命令行窗口不会感知到系统变量的修改。必须关闭所有命令行窗口，重新打开一个新的窗口，再执行 mvn -v。

误区三：JDK 安装了，但 `JAVA_HOME` 没设

错误现象：mvn -v 报错 JAVA_HOME should point to a JDK not a JRE，或者干脆找不到 Java。

纠正：Maven 启动脚本会检查 JAVA_HOME 环境变量。如果只有 java 命令在 Path 里，但 JAVA_HOME 未设置，Maven 的某些插件（如 maven-compiler-plugin）会无法正确定位 JDK 的 tools.jar。正确做法是：

JAVA_HOME = C:\Program Files\Java\jdk-17
Path = %JAVA_HOME%\bin;...其他路径...

注意：JAVA_HOME 指向 JDK 的根目录（包含 bin/、lib/ 的目录），而不是 bin 目录本身。

误区四：Maven 版本与 JDK 版本不兼容

错误现象：小崔的电脑之前装了 JDK 8，没装 JDK 17，直接运行 Maven 3.9.6。

纠正：Maven 3.9.x 要求 JDK 8 或更高，但飞翔科技的项目统一用 JDK 17 开发。虽然 Maven 3.9.6 能在 JDK 8 上运行，但编译项目时会因为项目源码是 Java 17 语法而报错。因此，mvn -v 中显示的 Java 版本必须与项目开发用的 JDK 版本一致。

小结

Maven 的安装本质是"解压 + 配置环境变量"，无需执行安装向导。核心配置只有两个变量：MAVEN_HOME（指向 Maven 根目录）和 Path（追加 %MAVEN_HOME%\bin）。验证命令 mvn -v 的输出包含版本、路径、JDK 和操作系统四项关键信息，是环境是否正确的唯一权威判断标准。

本章与全局的关系：本章完成了 Maven 的物理安装，让 mvn 命令可在命令行中执行。下一章"settings.xml"将讲解 Maven 的行为配置文件，让你能自定义仓库位置、镜像源等关键行为。