Maven 环境配置

本章将介绍如何在不同操作系统上安装 Maven，以及配置开发环境。

前置条件

Maven 是基于 Java 的工具，因此在安装 Maven 之前，需要先安装 JDK。

JDK 版本要求

不同版本的 Maven 对 JDK 有不同的要求：

Maven 版本	最低 JDK 版本	推荐 JDK 版本
Maven 3.9.x	JDK 8	JDK 11 或更高
Maven 3.8.x	JDK 7	JDK 8 或更高
Maven 3.6.x	JDK 7	JDK 8 或更高

建议使用 Maven 3.9.x 和 JDK 11 或更高版本的组合，以获得最佳体验。

验证 JDK 安装

在安装 Maven 之前，先确认 JDK 已正确安装。打开命令行，执行以下命令：

java -version
javac -version

如果看到类似以下输出，说明 JDK 已正确安装：

java version "17.0.2" 2022-01-18 LTS
Java(TM) SE Runtime Environment (build 17.0.2+8-LTS-86)
Java HotSpot(TM) 64-Bit Server VM (build 17.0.2+8-LTS-86, mixed mode, sharing)

在 Windows 上安装 Maven

方法一：手动安装（推荐）

第一步：下载 Maven

访问 Maven 官方下载页面
在"Files"部分找到"Binary zip archive"
下载 apache-maven-3.9.x-bin.zip 文件

第二步：解压文件

将下载的 zip 文件解压到一个不含中文和空格的目录，例如：

D:\apache-maven-3.9.6

解压后的目录结构如下：

apache-maven-3.9.6/
├── bin/          # 可执行文件
├── boot/         # 类加载器
├── conf/         # 配置文件
├── lib/          # 运行所需的库
└── LICENSE.txt
└── NOTICE.txt
└── README.txt

第三步：配置环境变量

右键点击"此电脑"，选择"属性"
点击"高级系统设置"
点击"环境变量"按钮
在"系统变量"区域，点击"新建"：
- 变量名：MAVEN_HOME
- 变量值：D:\apache-maven-3.9.6（你的 Maven 安装路径）
找到系统变量中的 Path，点击"编辑"，添加：
- %MAVEN_HOME%\bin

第四步：验证安装

打开新的命令提示符窗口，执行：

mvn -v

如果看到以下输出，说明安装成功：

Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)
Maven home: D:\apache-maven-3.9.6
Java version: 17.0.2, vendor: Oracle Corporation, runtime at: D:\Java\jdk-17
Default locale: zh_CN, platform encoding: GBK
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"

方法二：使用 Chocolatey 安装

如果你使用 Chocolatey 包管理器，可以直接执行：

choco install maven

在 macOS 上安装 Maven

方法一：使用 Homebrew 安装（推荐）

Homebrew 是 macOS 上最流行的包管理器，使用它可以轻松安装 Maven：

# 安装 Maven
brew install maven

# 验证安装
mvn -v

方法二：手动安装

第一步：下载并解压

# 下载 Maven
curl -O https://dlcdn.apache.org/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.tar.gz

# 解压到指定目录
tar -xzf apache-maven-3.9.6-bin.tar.gz -C /opt/

# 创建符号链接（方便后续升级）
ln -s /opt/apache-maven-3.9.6 /opt/maven

第二步：配置环境变量

编辑 ~/.zshrc 或 ~/.bash_profile 文件，添加：

export MAVEN_HOME=/opt/maven
export PATH=$MAVEN_HOME/bin:$PATH

使配置生效：

source ~/.zshrc

第三步：验证安装

mvn -v

在 Linux 上安装 Maven

Ubuntu/Debian

# 更新软件包列表
sudo apt update

# 安装 Maven
sudo apt install maven

# 验证安装
mvn -v

CentOS/RHEL

# 安装 Maven
sudo yum install maven

# 验证安装
mvn -v

手动安装（通用方法）

# 下载 Maven
cd /opt
sudo curl -O https://dlcdn.apache.org/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.tar.gz

# 解压
sudo tar -xzf apache-maven-3.9.6-bin.tar.gz

# 创建符号链接
sudo ln -s /opt/apache-maven-3.9.6 /opt/maven

# 配置环境变量
sudo tee /etc/profile.d/maven.sh <<EOF
export MAVEN_HOME=/opt/maven
export PATH=\$MAVEN_HOME/bin:\$PATH
EOF

# 使配置生效
source /etc/profile.d/maven.sh

# 验证安装
mvn -v

Maven 目录结构

安装完成后，了解 Maven 的目录结构有助于后续配置：

apache-maven-3.9.6/
├── bin/                    # 可执行脚本
│   ├── mvn                 # Unix/Linux 执行脚本
│   ├── mvn.cmd             # Windows 执行脚本
│   └── m2.conf             # 类加载器配置
├── boot/                   # 启动类加载器
│   └── plexus-classworlds-*.jar
├── conf/                   # 配置文件目录
│   ├── settings.xml        # 全局配置文件（重要）
│   ├── toolchains.xml      # 工具链配置
│   └── logging/            # 日志配置
└── lib/                    # Maven 运行所需的库文件

其中 conf/settings.xml 是最重要的配置文件，用于配置本地仓库位置、镜像源、代理等。

配置本地仓库位置

默认情况下，Maven 将下载的构件存储在用户主目录下的 .m2/repository 目录中。你可以修改这个位置。

修改 settings.xml

打开 conf/settings.xml 文件，找到 localRepository 标签，取消注释并修改：

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 
                              https://maven.apache.org/xsd/settings-1.0.0.xsd">
    
    <!-- 本地仓库路径 -->
    <localRepository>D:/maven/repository</localRepository>
    
</settings>

建议将本地仓库放在非系统盘，避免占用系统盘空间。

配置镜像源

由于 Maven 中央仓库在国外，国内下载速度较慢。配置国内镜像可以显著提高下载速度。

配置阿里云镜像

编辑 conf/settings.xml，在 <mirrors> 标签内添加：

<mirrors>
    <mirror>
        <id>aliyunmaven</id>
        <mirrorOf>*</mirrorOf>
        <name>阿里云公共仓库</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>

常用镜像源

镜像源	地址	说明
阿里云	https://maven.aliyun.com/repository/public	推荐，速度快
华为云	https://repo.huaweicloud.com/repository/maven/	速度快
腾讯云	https://mirrors.cloud.tencent.com/nexus/repository/maven-public/	速度快

配置 JDK 版本

Maven 默认使用 JDK 1.5 编译项目，这显然不符合现代开发需求。可以在 settings.xml 中配置默认的 JDK 版本：

<profiles>
    <profile>
        <id>jdk-17</id>
        <activation>
            <activeByDefault>true</activeByDefault>
            <jdk>17</jdk>
        </activation>
        <properties>
            <maven.compiler.source>17</maven.compiler.source>
            <maven.compiler.target>17</maven.compiler.target>
            <maven.compiler.compilerVersion>17</maven.compiler.compilerVersion>
        </properties>
    </profile>
</profiles>

IDE 集成配置

IntelliJ IDEA 配置

打开 File -> Settings（macOS 为 Preferences）
导航到 Build, Execution, Deployment -> Build Tools -> Maven
配置以下选项：
- Maven home path：选择 Maven 安装目录
- User settings file：选择自定义的 settings.xml 文件
- Local repository：选择本地仓库目录

Eclipse 配置

打开 Window -> Preferences
导航到 Maven -> Installations
点击 Add 添加 Maven 安装目录
在 Maven -> User Settings 中配置 settings.xml 文件

创建第一个 Maven 项目

安装配置完成后，让我们创建第一个 Maven 项目来验证环境。

使用命令行创建

# 创建一个简单的 Java 项目
mvn archetype:generate \
    -DgroupId=com.example \
    -DartifactId=my-first-app \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DarchetypeVersion=1.4 \
    -DinteractiveMode=false

命令参数说明：

groupId：项目组织标识
artifactId：项目名称
archetypeArtifactId：项目模板类型
interactiveMode：是否交互模式

项目结构

创建的项目结构如下：

my-first-app/
├── pom.xml                 # 项目配置文件
├── src/
│   ├── main/
│   │   └── java/           # 源代码目录
│   │       └── com/example/App.java
│   └── test/
│       └── java/           # 测试代码目录
│           └── com/example/AppTest.java

构建项目

进入项目目录，执行以下命令：

# 编译项目
mvn compile

# 运行测试
mvn test

# 打包项目
mvn package

# 清理并打包
mvn clean package

运行程序

打包完成后，可以运行生成的 jar 文件：

java -cp target/my-first-app-1.0-SNAPSHOT.jar com.example.App

输出：

Hello World!

常见问题解决

问题一：mvn 命令找不到

原因：环境变量配置错误或未生效

解决：

检查 MAVEN_HOME 是否正确配置
检查 Path 中是否包含 %MAVEN_HOME%\bin
重新打开命令行窗口使环境变量生效

问题二：下载依赖速度慢

原因：默认使用国外中央仓库

解决：配置国内镜像源，参考上文"配置镜像源"部分

问题三：编译报错"无效的目标发行版"

原因：Maven 使用的 JDK 版本与项目要求不匹配

解决：

检查 JAVA_HOME 是否指向正确的 JDK 版本
在 pom.xml 中指定正确的编译版本：

<properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

问题四：IDE 中 Maven 配置不生效

原因：IDE 使用了内置的 Maven 或不同的 settings.xml

解决：

在 IDE 中明确指定 Maven 安装目录
在 IDE 中明确指定 settings.xml 文件路径
确保 IDE 使用的 JDK 版本正确

小结

本章我们学习了：

Maven 的前置条件和 JDK 版本要求
在 Windows、macOS、Linux 上安装 Maven 的方法
Maven 的目录结构和重要配置文件
配置本地仓库位置和镜像源
在 IDE 中集成 Maven
创建和构建第一个 Maven 项目
常见问题的解决方法

在下一章中，我们将深入学习 POM 文件的配置。

前置条件​

JDK 版本要求​

验证 JDK 安装​

在 Windows 上安装 Maven​

方法一：手动安装（推荐）​

方法二：使用 Chocolatey 安装​

在 macOS 上安装 Maven​

方法一：使用 Homebrew 安装（推荐）​

方法二：手动安装​

在 Linux 上安装 Maven​

Ubuntu/Debian​

CentOS/RHEL​

手动安装（通用方法）​

Maven 目录结构​

配置本地仓库位置​

修改 settings.xml​

配置镜像源​

配置阿里云镜像​

常用镜像源​

配置 JDK 版本​

IDE 集成配置​

IntelliJ IDEA 配置​

Eclipse 配置​

创建第一个 Maven 项目​

使用命令行创建​

项目结构​

构建项目​

运行程序​

常见问题解决​

问题一：mvn 命令找不到​

问题二：下载依赖速度慢​

问题三：编译报错"无效的目标发行版"​

问题四：IDE 中 Maven 配置不生效​

小结​