Maven 安装指南

Note

本文是一份面向开发者的 Maven 安装手册，覆盖：

  • 如何下载并安装 Apache Maven
  • macOS（Apple Silicon / ARM）环境变量配置
  • Windows 环境变量配置
  • 安装验证与常见问题

0. Maven 是什么（以及为什么要装它）

Maven 是 Java 生态最常用的构建与依赖管理工具之一。常见用途包括：

  • 管理依赖（自动下载 jar）
  • 统一项目构建（compile / test / package）
  • 与 IDE、CI/CD 结合（例如 IntelliJ IDEA、Jenkins、GitHub Actions）

1. 下载 Maven（官方推荐方式）

  1. 打开 Apache Maven 官网下载页：
  2. 在 Files 区域选择二进制压缩包下载：
    • macOS / Linux：通常选择 apache-maven-<version>-bin.tar.gz
    • Windows：通常选择 apache-maven-<version>-bin.zip

建议：下载完成后，把 Maven 解压到一个 “不会轻易移动的位置”，否则环境变量会失效。

2. macOS（Apple Silicon / ARM）安装与配置

以下步骤同样适用于 Intel Mac。

2.1 解压并放置目录（建议位置）

假设你下载的文件为：apache-maven-3.x.x-bin.tar.gz

在终端执行：

Bash
cd ~/Downloads
tar -xzf apache-maven-3.*-bin.tar.gz
sudo mkdir -p /opt
sudo mv apache-maven-3.* /opt/apache-maven

你将得到 Maven 主目录：

  • /opt/apache-maven

2.2 配置环境变量（zsh 默认）

编辑 ~/.zshrc：

Bash
nano ~/.zshrc

在文件末尾追加：

Bash
export MAVEN_HOME=/opt/apache-maven
export PATH=$MAVEN_HOME/bin:$PATH

保存（Ctrl + O、回车、Ctrl + X）后让配置生效：

Bash
source ~/.zshrc

如果你使用的是 bash，则把上面的内容写到 ~/.bash_profile 或 ~/.bashrc。

2.3 验证安装

Bash
mvn -v

你应该能看到 Maven 版本、Java 版本、以及运行环境信息。

Bash
refinex@192 ~ % mvn -v
Apache Maven 3.9.12 (848fbb4bf2d427b72bdb2471c22fced7ebd9a7a1)
Maven home: /Users/refinex/develop/maven/apache-maven-3.9.12
Java version: 17.0.18, vendor: Azul Systems, Inc., runtime: /Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
Default locale: zh_CN_#Hans, platform encoding: UTF-8
OS name: "mac os x", version: "26.2", arch: "aarch64", family: "mac"

3. Windows 安装与配置

3.1 解压并放置目录（建议位置）

假设你下载的是 apache-maven-3.x.x-bin.zip。

建议解压到：

  • C:\DevTools\apache-maven（示例）

最终目录结构应类似：

  • C:\DevTools\apache-maven\bin\mvn.cmd

3.2 配置环境变量（图形化方式）

  1. 打开：系统属性 → 高级 → 环境变量
  2. 在“系统变量” 中点击 “新建”，添加：
    • 变量名：MAVEN_HOME
    • 变量值：C:\DevTools\apache-maven
  3. 找到系统变量 Path，点击 “编辑”，新增一行：
    • %MAVEN_HOME%\bin
  4. 一路确定保存。

3.3 验证安装

重要：打开一个新的 PowerShell 或 CMD 窗口（旧窗口不会自动刷新环境变量）。

执行：

Powershell
mvn -v

4. 建议同步检查：Java 环境是否正常

Maven 依赖 JDK（或至少 JRE）才能工作。若 mvn -v 报错，建议你同时确认：

  • java -version 能正常输出
  • 已安装 JDK（例如 Temurin / Oracle JDK）
  • Windows 上建议配置 JAVA_HOME 并将 %JAVA_HOME%\bin 加入 Path

5. 常见问题（FAQ）

5.1 macOS 执行 mvn 提示 command not found

  • 检查是否执行过：source ~/.zshrc
  • 检查 PATH 是否包含 $MAVEN_HOME/bin：
Bash
echo $PATH
  • 检查 /opt/apache-maven/bin 下是否存在 mvn

5.2 Windows 配置后仍然找不到 mvn

  • 确认已打开“新的”终端窗口
  • 确认 Path 中的条目是否为：%MAVEN_HOME%\bin
  • 确认 MAVEN_HOME 指向 Maven 根目录（必须包含 bin 目录）

5.3 Maven 下载依赖很慢

这通常与网络环境有关。常见处理方式是配置镜像源（例如在 ~/.m2/settings.xml 中配置镜像）。

6. 快速自检清单

  • mvn -v 正常
  • java -version 正常
  • 项目目录下能执行 mvn -q -DskipTests package
下一篇 →