Maven 学习手册

发表于 更新于 分类于 阅读次数： 本文字数： 3.3k 阅读时长 ≈ 12 分钟

Maven 全流程学习手册

文档核心说明

本文档适用于 Java 开发入门者、需要快速搭建 Maven 开发环境的开发者，整合了 Maven 环境准备、下载安装、系统配置、核心配置、项目使用、IDE 集成的完整步骤，所有操作均为生产环境验证的稳定方案，新手可直接按步骤执行。

一、前置准备：JDK 环境

Maven 基于 Java 开发，必须先配置 JDK 环境，版本兼容规则如下：

Maven 版本 最低 JDK 要求 推荐生产版本
3.9.x 稳定版 JDK 8+ JDK 8 / JDK 17 / JDK 21（LTS 版本）
4.0.x 预览版 JDK 17+ 不推荐生产环境使用

验证 JDK 环境

打开终端 / 命令提示符，执行以下命令，均正常输出版本信息即为配置成功：

1
2
3
4
# 验证Java运行环境
java -version
# 验证Java编译环境（必须配置JAVA_HOME才会生效）
javac -version

若命令报错，需先完成 JDK 安装与JAVA_HOME环境变量配置，再进行后续步骤。

二、Maven 下载与安装

1. 官方下载

  • 官方下载地址：https://maven.apache.org/download.cgi

  • 生产环境推荐：最新稳定版 apache-maven-3.9.15

  • 安装包选择规则：

    系统 推荐安装包 说明
    Windows apache-maven-3.9.15-bin.zip 二进制免安装版，解压即可用
    macOS/Linux apache-maven-3.9.15-bin.tar.gz 二进制压缩包，解压即可用

❗ 避坑提醒：不要下载src源码包，必须下载带bin的二进制包；解压路径严禁包含中文、空格、特殊字符，推荐路径：

  • Windows：D:\dev\apache-maven-3.9.15

  • macOS/Linux：/usr/local/apache-maven-3.9.15 或 \~/opt/apache-maven-3.9.15

2. 解压安装

  • Windows：右键 zip 包，选择「解压到当前文件夹」，放到上述推荐路径即可

  • macOS/Linux：终端执行解压命令

    1
    2
    3
    4
    # 对应下载的tar.gz包路径
    tar -zxvf apache-maven-3.9.15-bin.tar.gz
    # 移动到目标目录（示例）
    sudo mv apache-maven-3.9.15 /usr/local/

三、系统环境变量配置

环境变量的作用是让系统在任意目录都能识别mvn命令，统一管理 Maven 路径，方便版本切换。

核心环境变量说明

变量名 作用 是否必须 示例
MAVEN_HOME Maven 安装根目录（bin 的上一级） ✅ 推荐 D:\dev\apache-maven-3.9.15
PATH 系统查找可执行文件的路径 ✅ 必须 %MAVEN_HOME%\bin（Win）/ $MAVEN_HOME/bin（macOS/Linux）
MAVEN_OPTS JVM 启动参数（内存、编码等） ❌ 可选 -Xms512m -Xmx1g -Dfile.encoding=UTF-8

1. Windows 系统配置

  1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」

  2. 在系统变量区域，点击「新建」：

    • 变量名：MAVEN_HOME

    • 变量值：Maven 解压根目录（如D:\dev\apache-maven-3.9.15）

  3. 找到系统变量中的Path，双击编辑，点击「新建」，添加：

    Text
    1
    %MAVEN_HOME%\bin

  4. 可选：新建系统变量MAVEN_OPTS，值为-Xms512m -Xmx1g -Dfile.encoding=UTF-8

  5. 依次点击所有窗口的「确定」，配置完成。

2. macOS/Linux 系统配置

  1. 打开终端，先确认当前使用的 shell：

    1
    2
    3
    echo $SHELL
    # 输出/bin/bash → 编辑~/.bash_profile
    # 输出/bin/zsh → 编辑~/.zshrc（macOS 10.15+默认）

  2. 执行编辑命令（以 zsh 为例）：

    1
    vim ~/.zshrc

  3. 按i进入编辑模式，在文件末尾添加以下内容：

    1
    2
    3
    4
    5
    # Maven 环境变量
    export MAVEN_HOME=/usr/local/apache-maven-3.9.15
    export PATH=$MAVEN_HOME/bin:$PATH
    # 可选：JVM参数
    export MAVEN_OPTS="-Xms512m -Xmx1g -Dfile.encoding=UTF-8"

  4. 按Esc，输入:wq保存退出，执行以下命令让配置立即生效：

    1
    2
    source ~/.zshrc
    # bash用户执行 source ~/.bash_profile

3. 安装验证

必须打开新的终端 / CMD 窗口（旧窗口无法读取新配置的环境变量），执行命令：

1
mvn -v

成功输出包含 Maven 版本、Java 版本、系统信息的内容，即为安装配置成功。

四、Maven 核心配置（settings.xml）

settings.xml是 Maven 的核心配置文件，用于控制本地仓库、镜像源、全局编译规则等，分为 2 个级别：

  • 全局配置：Maven 安装目录下的conf/settings.xml，对所有用户生效

  • 用户级配置：用户目录下的.m2/settings.xml，仅对当前用户生效，优先级更高，重装 Maven 不会丢失，推荐使用。

若用户目录下没有.m2文件夹，手动创建即可；没有settings.xml，直接新建该文件，复制下方完整配置模板。

完整配置模板（开箱即用）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">

  <!-- 本地仓库路径：建议使用非中文无空格路径，避免兼容问题 -->
  <localRepository>D:/works/maven/repository</localRepository>

  <pluginGroups></pluginGroups>
  <proxies></proxies>
  <servers></servers>

  <!-- 国内镜像仓库优化配置：覆盖主流中央仓库，补充网易/腾讯镜像 -->
  <mirrors>
    <!-- 阿里云核心镜像（首选）：覆盖最全，速度最快 -->
    <mirror>
      <id>aliyunmaven</id>
      <name>Aliyun Maven Repository</name>
      <url>https://maven.aliyun.com/repository/central</url>
      <mirrorOf>central</mirrorOf>
    </mirror>

    <!-- 阿里云spring专属镜像（解决spring组件下载慢） -->
    <mirror>
      <id>aliyun-spring</id>
      <name>Aliyun Spring Maven Repository</name>
      <url>https://maven.aliyun.com/repository/spring</url>
      <mirrorOf>spring-plugin,spring-milestones,spring-snapshots</mirrorOf>
    </mirror>

    <!-- 华为云镜像（备用1） -->
    <mirror>
      <id>huaweicloud</id>
      <name>HuaweiCloud Maven Repository</name>
      <url>https://repo.huaweicloud.com/repository/maven/</url>
      <mirrorOf>central</mirrorOf>
    </mirror>

    <!-- 网易云镜像（备用2） -->
    <mirror>
      <id>163maven</id>
      <name>NetEase Maven Repository</name>
      <url>http://mirrors.163.com/maven/repository/maven-public/</url>
      <mirrorOf>central</mirrorOf>
    </mirror>

    <!-- 腾讯云镜像（备用3） -->
    <mirror>
      <id>tencentmaven</id>
      <name>Tencent Maven Repository</name>
      <url>https://mirrors.cloud.tencent.com/nexus/repository/maven-public/</url>
      <mirrorOf>central</mirrorOf>
    </mirror>

    <!-- 中央仓库镜像兜底（国内可访问的官方镜像） -->
    <mirror>
      <id>maven-central</id>
      <name>Central Maven Repository</name>
      <url>https://repo1.maven.org/maven2</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>

  <!-- 全局构建配置：适配国内开发环境 -->
  <profiles>
    <profile>
      <id>default-global-config</id>
      <properties>
        <!-- JDK版本可根据实际需求修改（1.8/11/17/21） -->
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <maven.compiler.compilerVersion>21</maven.compiler.compilerVersion>
        <!-- 强制UTF-8编码，避免中文乱码 -->
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <!-- 解决maven-resources-plugin编码问题 -->
        <maven.resources.encoding>UTF-8</maven.resources.encoding>
        <!-- 跳过SSL校验（部分内网/镜像站可能证书问题） -->
        <maven.wagon.http.ssl.insecure>true</maven.wagon.http.ssl.insecure>
        <maven.wagon.http.ssl.allowall>true</maven.wagon.http.ssl.allowall>
      </properties>
    </profile>

    <!-- 激活国内仓库配置 -->
    <profile>
      <id>china-mirrors</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>https://maven.aliyun.com/repository/public</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>false</enabled></snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>central</id>
          <url>https://maven.aliyun.com/repository/public</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>false</enabled></snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

  <!-- 激活所有优化配置 -->
  <activeProfiles>
    <activeProfile>default-global-config</activeProfile>
    <activeProfile>china-mirrors</activeProfile>
  </activeProfiles>

</settings>

五、Maven 核心概念与基础使用

1. 标准项目结构

Maven 遵循约定大于配置原则，所有项目必须遵循标准目录结构，无需额外配置即可自动识别：

Text
1
2
3
4
5
6
7
8
9
10
my-maven-project        # 项目根目录
├── pom.xml             # 项目核心配置文件，必须存在
├── src
│   ├── main
│   │   ├── java        # 项目Java源码目录
│   │   └── resources   # 项目配置文件目录
│   └── test
│       ├── java        # 测试代码目录
│       └── resources   # 测试配置文件目录
└── target              # 编译/打包输出目录，自动生成

2. 核心文件：pom.xml 详解

pom.xml（Project Object Model，项目对象模型）是 Maven 项目的灵魂，定义了项目的坐标、依赖、构建规则等，最小可运行模板如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 项目GAV坐标：全球唯一标识，定位一个项目/依赖包 -->
    <groupId>com.example</groupId>    <!-- 组织ID，一般是公司域名倒序 -->
    <artifactId>my-demo</artifactId>  <!-- 项目/模块ID，项目唯一名称 -->
    <version>1.0.0</version>          <!-- 版本号，SNAPSHOT为快照版，RELEASE为正式版 -->
    <packaging>jar</packaging>        <!-- 打包类型，默认jar，可选war/pom等 -->

    <!-- 依赖管理：所有第三方jar包都在这里声明 -->
    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.13.2</version>
            <scope>test</scope>  <!-- 依赖作用范围 -->
        </dependency>
    </dependencies>

</project>

依赖 scope 作用范围

scope 值 作用 生效范围 示例
compile 默认值 编译、测试、运行、打包全阶段生效 spring-core
test 仅测试阶段生效 仅测试代码编译、执行时生效 junit
provided 编译测试生效，运行时不生效，不会打包 编译、测试 servlet-api（Tomcat 容器提供）
runtime 运行时生效，编译时不生效 测试、运行 mysql-connector-java

3. 三大生命周期与核心命令

Maven 定义了三套生命周期，执行后面的阶段，会自动执行前面的所有前置阶段：

生命周期 核心作用
clean 清理项目，删除 target 目录
default（build） 核心构建，完成编译、测试、打包、部署全流程
site 生成项目文档，日常开发极少使用

高频常用命令

命令 核心作用
mvn clean 清理项目，删除 target 目录
mvn compile 编译主源码，检查编译错误
mvn test 执行所有测试用例
mvn package 编译测试后，打包成 jar/war 包
mvn install 打包后，安装到本地 Maven 仓库
mvn dependency:tree 打印依赖树，排查 Jar 包冲突
mvn clean package -DskipTests 打包时跳过测试，快速生成产物

六、VSCode 中集成与使用 Maven

1. 前置准备

确保系统级 JDK、Maven 环境已配置完成，终端执行mvn -v可正常输出版本信息。

2. 安装必备插件

  1. 打开 VSCode 扩展商店（快捷键Ctrl+Shift+X）

  2. 搜索安装 Extension Pack for Java（微软官方 Java 全家桶），该插件包已内置Maven for Java核心插件，同时包含语言支持、调试器等所有 Java 开发必备工具

  3. 安装完成后重启 VSCode

3. VSCode Maven 核心配置

默认情况下 VSCode 会自动读取系统环境变量和用户级settings.xml，识别失败可手动配置：

  1. 打开 VSCode 设置（快捷键Ctrl+,），点击右上角打开settings.json

  2. 添加以下配置，根据自己的路径修改：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  // 指定Maven可执行文件路径
  "maven.executable.path": "D:\dev\apache-maven-3.9.15\bin\mvn.cmd",
  // 自定义Maven JVM参数
  "maven.terminal.customEnv": [
    {
      "environmentVariable": "MAVEN_OPTS",
      "value": "-Xms512m -Xmx1g -Dfile.encoding=UTF-8"
    }
  ],
  // 自动下载依赖源码和JavaDoc
  "maven.autoDownloadSources": true,
  "maven.autoDownloadJavadoc": true,
  // JDK路径配置
  "java.home": "D:\dev\jdk1.8.0_402",
  // 开启注解处理，解决Lombok不生效
  "java.annotations.processor.enabled": true,
  // 文件编码
  "files.encoding": "utf8"
}

4. 创建 / 导入 Maven 项目

创建新项目

  1. 打开命令面板（Ctrl+Shift+P），选择Maven: Create Maven Project

  2. 选择项目模板，最常用maven-archetype-quickstart（标准 Java 项目）

  3. 填写 GAV 坐标，选择保存路径，等待自动生成项目结构

导入已有项目

  1. 点击「文件」→「打开文件夹」，选择包含pom.xml的项目根目录

  2. VSCode 会自动识别 Maven 项目，加载依赖，识别失败可右键pom.xml选择「Update Project Configuration」

5. 日常常用操作

  1. 执行 Maven 命令：左侧打开 Maven 侧边栏，展开项目→Lifecycle，双击对应命令即可执行

  2. 自定义命令：命令面板选择Maven: Execute Commands，输入自定义命令（如dependency:tree）

  3. 运行调试：右键 Java 主类，选择Run Java/Debug Java即可运行调试

  4. 多模块项目：打开父项目根目录，VSCode 会自动识别所有子模块，可单独对模块执行命令

七、常见问题与解决方案

1. mvn命令提示 “不是内部或外部命令”

  • 必须打开新终端 / CMD 窗口，旧窗口无法读取新环境变量

  • 检查MAVEN_HOME路径是否为 Maven 根目录，Path 中是否添加了%MAVEN_HOME%\bin

  • 检查路径是否包含中文、空格，修改为纯英文路径

2. 报错JAVA_HOME not set

  • 先配置 JDK 的JAVA_HOME环境变量，Maven 依赖 Java 环境

  • 可在 VSCode 的maven.terminal.customEnv中单独配置 JAVA_HOME

3. 依赖下载慢 / 下载失败

  • 检查settings.xml是否正确配置了阿里云镜像

  • 删除本地仓库中对应依赖的.lastUpdated文件，重新刷新依赖

  • 关闭 VPN，检查网络是否正常

4. Maven 项目识别失败，pom.xml 图标不对

  • 检查是否安装了 Java 全家桶插件，重启 VSCode

  • 确保打开了包含 pom.xml 的项目根目录

  • 执行Java: Clean Java Language Server Workspace清理缓存

5. 中文乱码 / 编译报错

  • 在settings.xml中配置 UTF-8 编码

  • 在MAVEN_OPTS中添加-Dfile.encoding=UTF-8

  • VSCode 文件编码设置为 UTF-8

6. Jar 包冲突（ClassNotFoundException/NoSuchMethodError）

  • 执行mvn dependency:tree查看依赖树，定位冲突版本

  • 在冲突依赖中使用<exclusions>排除不需要的版本

7. Lombok 注解不生效

  • 安装 Lombok 插件，开启注解处理："java.annotations.processor.enabled": true

8. 大项目打包内存溢出

  • 调大MAVEN_OPTS的内存配置，比如改为-Xms1g -Xmx2g

核心知识点速览

  • Maven 是 Java 项目的依赖管理与构建工具，核心遵循约定大于配置原则

  • 系统环境变量核心是配置MAVEN_HOME+PATH，实现全局mvn命令调用

  • settings.xml推荐使用用户级配置，可自定义本地仓库、阿里云镜像加速下载

  • Maven 生命周期执行后序阶段会自动执行所有前置阶段，常用组合命令mvn clean package

  • pom.xml 通过GAV 坐标唯一标识项目与依赖，scope 控制依赖的生效范围

  • VSCode 集成 Maven 只需安装官方 Java 全家桶插件，可自动读取系统 Maven 配置

  • 排查 Jar 包冲突可通过mvn dependency:tree查看完整依赖传递关系

  • 所有配置路径严禁包含中文、空格，避免出现识别错误

  • 国内开发必须配置阿里云镜像，解决中央仓库下载慢的问题

  • 多版本 Maven 切换只需修改MAVEN_HOME路径，无需修改其他配置