55. 【Java】Maven：项目构建的“管家”

摘要： 本文是Java项目构建工具Maven的入门实战指南，从零开始讲解Maven的核心概念、安装配置、依赖管理、生命周期等关键知识。通过实际示例演示如何创建Maven项目、添加依赖、打包运行，并分享多模块项目构建和常见问题解决方案，帮助Java开发者告别手动管理JAR包的繁琐，实现项目构建的标准化和自动化。

关键词： Maven, Java项目构建, 依赖管理, POM, 生命周期

---

经过前面五个阶段的学习，你已经从“Java 小白”成长为能够编写高并发网络服务的开发者了。你写的代码不再是几行的小练习，而是可能包含几十个类、依赖多个第三方库、需要编译测试打包的项目了。

但你有没有发现，随着项目越来越大，有些“杂事”开始变得越来越烦人？

• 你需要手动下载 JAR 包（比如 HttpClient、JUnit），把它们放到 lib/ 目录下，还要手动配置 classpath。
• 当你想升级一个库的版本时，你得重新下载 JAR，替换旧文件，然后检查有没有兼容性问题。
• 你的项目需要编译、测试、打包成 JAR，每次你都手动执行 javac、java -jar 命令，或者写一个笨拙的 .bat/.sh 脚本。
• 当你想引入一个依赖，发现它自己又依赖了其他库（“传递性依赖”），你就得一个个手动下载，像俄罗斯套娃一样没完没了。
• 你的同事想把你的项目跑起来，需要先折腾半天环境，才勉强能编译。

如果你有这些烦恼，那你已经在渴望一个项目构建工具了。

Maven 就是 Java 世界中最早、最成熟、最广泛使用的项目构建工具之一。它不仅仅是一个“依赖管理工具”，它是一整套项目生命周期管理的框架——从编译、测试、打包、部署，到文档生成、报告统计，Maven 都能帮你自动化完成。

今天，我们就来学习 Maven 的核心概念和使用方法。学会它，你的 Java 项目开发效率会提升一个档次。

---

1. 为什么需要 Maven？—— 从一个“痛苦”的场景说起

假设你要写一个使用 HttpClient 调用 REST API 的小项目。你的做法可能是这样：

1. 去 Maven 中央仓库（https://mvnrepository.com）找到 HttpClient 的 JAR 包，下载下来。
2. 发现 HttpClient 依赖了 httpcore、commons-logging 等几个库，你再去逐个下载。
3. 把所有这些 JAR 包放到项目的 lib/ 目录下。
4. 在 IDE 中配置 classpath，把这些 JAR 包加进去。
5. 开始写代码。
6. 当你需要升级 HttpClient 版本时，重复步骤 1-4。

这个过程有什么问题？

• 繁琐：每次引入新库，都要手动下载一堆 JAR 文件，还要处理传递性依赖。
• 容易出错：版本冲突、不同库之间的兼容性问题，经常让你摸不着头脑。
• 不可重现：你的项目能跑起来，是因为你的 lib/ 目录里有特定的 JAR 文件。换一台机器，你可能就缺某个 JAR，或者版本不对。
• 没有标准化：每个项目都有自己的目录结构、构建方式，新加入的成员需要花时间理解每个项目的结构。

Maven 的出现，就是为了解决这些问题。它规定了：

• 一套标准的项目目录结构：源代码放哪里，测试代码放哪里，资源文件放哪里。
• 一个统一的依赖管理机制：你只需要在 pom.xml 中声明需要什么库，Maven 自动帮你下载（包括所有传递性依赖）。
• 一组标准化的构建生命周期：mvn clean、mvn compile、mvn test、mvn package、mvn install……从编译到部署，全部标准化。

打个比方：在没有 Maven 的时代，每个 Java 项目都像一栋自己盖的房子——图纸各不相同，材料自己采购，施工方法各有特色。而 Maven 像是一套成熟的商品房开发流程——蓝图规范、材料由供应链统一配送、施工有标准工序。你只需要填写需求（pom.xml），剩下的交给 Maven 去做。

---

2. Maven 的核心概念 —— 三个基石

在开始使用之前，我们先理解 Maven 的三个核心概念。

2.1 POM —— 项目对象模型

POM（Project Object Model，项目对象模型） 是 Maven 的核心配置文件。它叫 pom.xml，放在项目的根目录下。

pom.xml 描述了：

• 这个项目是谁的（groupId）
• 这个项目叫什么（artifactId）
• 当前是什么版本（version）
• 它依赖哪些外部库
• 它有哪些插件
• 它如何构建

一个最简单的 pom.xml 长这样：

<?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>
    <artifactId>my-project</artifactId>
    <version>1.0.0</version>

    <!-- 打包方式：jar（默认）、war、pom 等 -->
    <packaging>jar</packaging>
</project>

2.2 坐标（GAV）—— Maven 世界的“身份证”

每一个 Maven 项目（以及每一个依赖库）都有一个唯一的坐标，由三部分组成：

部分	含义	示例
groupId	组织或公司标识（通常是域名倒序）	com.example
artifactId	项目或模块名称	my-project
version	版本号	1.0.0

这三个合起来，就是 com.example:my-project:1.0.0，在 Maven 世界中唯一标识一个构件（artifact）。

当你在 pom.xml 中声明依赖时，你就是在声明“我需要一个坐标是 xxx:yyy:zzz 的库”：

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.14</version>
</dependency>

Maven 就会去仓库里查找这个坐标对应的 JAR 文件。

2.3 仓库 —— JAR 包的“商店”

Maven 从仓库（Repository） 中下载依赖。仓库分为三种：

1. 本地仓库（Local Repository）：在你电脑上的一个文件夹（默认是 ~/.m2/repository）。Maven 下载的所有依赖都缓存在这里。同一个库只需要下载一次。
2. 中央仓库（Central Repository）：Maven 官方维护的公共仓库，包含了海量的开源库（https://repo1.maven.org/maven2/）。
3. 私有仓库（Private Repository）：公司或组织内部的仓库，用于存放内部开发的库或不便公开的依赖。Nexus、Artifactory 是常用的私有仓库管理工具。

依赖下载的顺序：本地仓库 → 私有仓库（如果配置了） → 中央仓库。

---

3. 安装 Maven

在使用 Maven 之前，需要先安装它。

3.1 下载与安装

1. 访问 Maven 官网（https://maven.apache.org/download.cgi），下载最新版本的 apache-maven-x.x.x-bin.zip（或 .tar.gz）。
2. 解压到你喜欢的目录，比如 C:\tools\apache-maven（Windows）或 /usr/local/apache-maven（macOS/Linux）。
3. 配置环境变量：
   • MAVEN_HOME = Maven 安装目录。
   • 把 %MAVEN_HOME%\bin（Windows）或 $MAVEN_HOME/bin（macOS/Linux）添加到 PATH 中。
4. 打开命令行，输入 mvn -version 验证安装。

Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)
Maven home: C:\tools\apache-maven
Java version: 21.0.1, vendor: Oracle Corporation
...

如果你看到类似的输出，说明 Maven 安装成功。

3.2 配置国内镜像（可选，但推荐）

由于中央仓库在国外，下载速度可能较慢。你可以配置阿里云等国内镜像，加速依赖下载。

修改 ~/.m2/settings.xml（如果没有就创建）：

<?xml version="1.0" encoding="UTF-8"?>
<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 
          http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <mirrors>
        <mirror>
            <id>aliyun</id>
            <mirrorOf>central</mirrorOf>
            <name>阿里云 Maven 镜像</name>
            <url>https://maven.aliyun.com/nexus/content/groups/public/</url>
        </mirror>
    </mirrors>
</settings>

这个配置会让 Maven 从阿里云镜像下载依赖，速度会快很多。

---

4. 创建第一个 Maven 项目

在 IntelliJ IDEA 中创建 Maven 项目是最简单的。当然你也可以用命令行 mvn archetype:generate，但 IDEA 提供了更直观的方式。

4.1 在 IDEA 中创建 Maven 项目

1. 点击 New Project。
2. 左侧选择 Maven。
3. 填写 GroupId（如 com.example）、ArtifactId（如 demo-maven）、Version（默认 1.0-SNAPSHOT）。
4. 选择 JDK 版本（JDK 21）。
5. 点击 Create。

IDEA 会创建一个标准的 Maven 项目结构：

demo-maven/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/          ← 你的 Java 源代码
│   │   └── resources/     ← 配置文件、资源文件
│   └── test/
│       ├── java/          ← 测试源代码
│       └── resources/     ← 测试资源文件

这就是 Maven 的标准目录结构——所有 Maven 项目都长这样。这意味着，任何人拿到你的项目，都知道源代码在哪里、测试在哪里、资源在哪里。

4.2 理解 pom.xml

让我们来看看 IDEA 生成的 pom.xml：

<?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>

    <groupId>com.example</groupId>
    <artifactId>demo-maven</artifactId>
    <version>1.0-SNAPSHOT</version>

    <!-- 打包方式：jar（默认） -->
    <packaging>jar</packaging>

    <properties>
        <!-- 声明一个属性，可以在其他地方引用 -->
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- 在这里添加你的依赖 -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>5.10.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- 在这里配置构建插件 -->
        </plugins>
    </build>
</project>

关键元素解释：

元素	说明
<modelVersion>	POM 模型的版本（4.0.0 是当前唯一标准）
<groupId>、<artifactId>、<version>	项目的坐标（GAV）
<packaging>	打包类型：jar（默认）、war（Web应用）、pom（父项目）等
<properties>	自定义属性，可以在其他地方用 ${xxx} 引用
<dependencies>	所有外部依赖的列表
<build>	构建相关的配置，包括插件

---

5. 依赖管理 —— Maven 最核心的能力

Maven 最让你省心的功能就是依赖管理。你只需要在 <dependencies> 中声明你需要的库，Maven 自动帮你下载一切。

5.1 添加一个依赖

假设我们要使用 HttpClient。我们找到它的坐标（在 Maven 中央仓库网站 https://mvnrepository.com 上搜索），然后加入 pom.xml：

<dependencies>
    <!-- 原来的 JUnit -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-api</artifactId>
        <version>5.10.0</version>
        <scope>test</scope>
    </dependency>
    
    <!-- HttpClient -->
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>4.5.14</version>
    </dependency>
</dependencies>

保存文件后，IDEA 会自动触发 Maven 下载（或者你可以手动点击 Maven 面板的刷新按钮）。你会看到 Maven 不仅下载了 httpclient-4.5.14.jar，还把它的传递性依赖（httpcore、commons-logging 等）也一起下载了。

5.2 依赖的范围（Scope）

依赖可以指定一个 <scope>，用来控制该依赖在哪些阶段被使用：

Scope	含义	示例
compile	默认值，在所有阶段（编译、测试、运行时）都可用	核心业务库
test	仅在测试阶段可用	JUnit、Mockito
provided	编译和测试时需要，但运行时由容器提供	Servlet API（Tomcat 已提供）
runtime	测试和运行时需要，但编译不需要	JDBC 驱动
system	从本地系统路径加载（不推荐）	—

5.3 版本管理 —— 用 properties 统一管理版本

当你有多个依赖时，把每个依赖的版本号分散写在不同的 <dependency> 中，维护起来很不方便。更好的做法是把版本号抽到 <properties> 中：

<properties>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <!-- 自定义属性 -->
    <httpclient.version>4.5.14</httpclient.version>
    <junit.version>5.10.0</junit.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
        <version>${httpclient.version}</version>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-api</artifactId>
        <version>${junit.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

当需要升级版本时，只需要修改 <properties> 中的一处即可。

5.4 依赖传递与冲突解决

Maven 会自动解析传递性依赖——A 依赖 B，B 依赖 C，你只需要声明 A，Maven 会把 B 和 C 都自动拉取下来。

但当两个依赖引用了同一个库的不同版本时，Maven 需要解决冲突。它采用最短路径优先原则：

• 路径最短的依赖版本被选中。
• 如果路径长度相同，则先声明的被选中。

你可以在 IDEA 的 Maven 面板中查看依赖树（mvn dependency:tree），了解最终使用了哪些版本的依赖。

---

6. Maven 生命周期 —— 标准化的构建流程

Maven 定义了一套标准化的生命周期（Lifecycle），让你可以用简单的命令完成从编译到部署的全过程。

最常用的生命周期是 default 生命周期，它包含以下核心阶段（按顺序）：

阶段	命令	作用
validate	mvn validate	验证项目是否正确，所有必要信息是否完整
compile	mvn compile	编译源代码（src/main/java）
test	mvn test	运行单元测试（src/test/java）
package	mvn package	打包成 JAR/WAR 文件（在 target/ 目录）
verify	mvn verify	对集成测试的结果进行检查
install	mvn install	把打包好的 JAR 安装到本地仓库（~/.m2/repository）
deploy	mvn deploy	把 JAR 上传到远程仓库（发布到私服或中央仓库）

⚠️ 关键理解：当你执行一个阶段时，前面的所有阶段都会自动执行。比如你执行 mvn package，Maven 会先执行 validate、compile、test，最后才执行 package。

还有一些实用的“清理”和“站点”生命周期：

• mvn clean：删除 target/ 目录（清理编译产物）。
• mvn site：生成项目文档站点（包括 Javadoc、测试报告等）。

常用组合命令：

命令	用途
mvn clean compile	清理后重新编译
mvn clean test	清理后编译并运行测试
mvn clean package	清理后编译、测试、打包
mvn clean install	清理后编译、测试、打包、安装到本地仓库

在 IDEA 中，你可以在 Maven 面板中双击某个生命周期阶段，或者从终端运行这些命令。

---

7. 多模块项目 —— 一个父项目 + 多个子模块

当项目变得复杂时，你可能需要把一个大项目拆分成多个子模块（比如 common、api、service、web）。Maven 支持多模块（Multi-Module） 项目。

父项目的 pom.xml 中：

<packaging>pom</packaging>   <!-- 父项目打包方式必须是 pom -->
<modules>
    <module>common</module>
    <module>api</module>
    <module>service</module>
    <module>web</module>
</modules>

每个子模块都有自己的 pom.xml，但可以继承父项目的公共配置（依赖版本、插件配置等）。

多模块项目的好处是：

• 统一管理所有子模块的依赖版本。
• 一次构建（mvn clean package）可以构建所有模块。
• 各模块之间职责清晰，便于团队协作。

---

8. 实际示例 —— 用 Maven 构建一个“Hello Maven”项目

我们来走一遍完整的流程：

Step 1：创建项目

在 IDEA 中新建一个 Maven 项目，groupId=com.example，artifactId=hello-maven。

Step 2：编写代码

在 src/main/java/com/example 下创建 Hello.java：

package com.example;

public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, Maven!");
        System.out.println("当前时间：" + java.time.LocalDateTime.now());
    }
}

Step 3：添加依赖

在 pom.xml 中加入 commons-lang3（一个常用的工具库）：

<dependencies>
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <version>3.14.0</version>
    </dependency>
</dependencies>

修改 Hello.java，使用 StringUtils：

import org.apache.commons.lang3.StringUtils;

public class Hello {
    public static void main(String[] args) {
        String msg = "Hello, Maven!";
        System.out.println("反转字符串：" + StringUtils.reverse(msg));
    }
}

Step 4：编译打包

在终端（或 IDEA 的 Maven 面板）执行：

mvn clean package

你会看到 Maven 下载依赖、编译代码、运行测试（目前没有测试）、打包。最终在 target/ 目录下生成 hello-maven-1.0-SNAPSHOT.jar。

Step 5：运行 JAR

java -cp target/hello-maven-1.0-SNAPSHOT.jar com.example.Hello

输出：

反转字符串：!niveaM ,olleH

恭喜你，你已经用 Maven 构建并运行了你的第一个项目！

---

9. 常见陷阱与注意事项

1. 依赖版本冲突

这是 Maven 最常见的问题之一。使用 mvn dependency:tree 查看依赖树，找出冲突的来源。然后用 exclusion 排除不需要的传递性依赖：

<dependency>
    <groupId>a</groupId>
    <artifactId>a-lib</artifactId>
    <version>1.0</version>
    <exclusions>
        <exclusion>
            <groupId>c</groupId>
            <artifactId>c-lib</artifactId>
        </exclusion>
    </exclusions>
</dependency>

2. 每次 pom.xml 修改后，IDEA 需要刷新

在 IDEA 的 Maven 面板中点击“刷新”按钮（Reload All Maven Projects），或者在 pom.xml 上右键选择 Maven → Reload Project。

3. 本地仓库坏了怎么办？

有时候依赖下载不完整，会导致构建失败。你可以删除 ~/.m2/repository 下对应的文件夹，让 Maven 重新下载。或者彻底一点，直接删除整个 ~/.m2/repository（但这样所有依赖都要重新下载，比较耗时）。

4. SNAPSHOT 版本

如果在版本号中包含 SNAPSHOT（如 1.0-SNAPSHOT），表示这是一个“快照”版本——仍在开发中，可能会频繁更新。Maven 默认会每天检查一次快照版本是否有更新。

---

10. 今天的总结

今天我们学习了 Maven：

• Maven 是什么：一个项目构建和依赖管理工具。
• 核心概念：
  • POM（pom.xml）：项目对象模型，描述项目信息、依赖、插件。
  • 坐标（GAV）：groupId:artifactId:version，唯一标识一个构件。
  • 仓库：本地仓库、中央仓库、私有仓库。
• 依赖管理：通过 <dependencies> 声明依赖，Maven 自动下载并处理传递性依赖。
• 生命周期：compile → test → package → install → deploy，每个阶段自动执行之前的阶段。
• 常用命令：mvn clean、mvn compile、mvn test、mvn package、mvn install。
• 多模块项目：父项目 + 多个子模块，统一管理。
• 最佳实践：用 <properties> 管理版本号，用 mvn dependency:tree 排查冲突。

Maven 是 Java 开发生态中不可或缺的工具。它让项目从“手工劳作”变成了“自动化流水线”，你不再需要关心 JAR 从哪里来、编译命令怎么敲、测试怎么跑——一切都由 Maven 接管，你只需要关注代码本身。

---

动手试试

1. 创建一个新的 Maven 项目，添加一个依赖（比如 gson 或 jackson），在代码中使用它，然后用 mvn package 打包并运行。

2. 在 pom.xml 中配置 maven-compiler-plugin，指定 JDK 21 编译（IDEA 默认已经做了，你可以看看插件配置的写法）。

3. 写一个简单的 JUnit 5 测试，放在 src/test/java 下，然后用 mvn test 运行测试。

4. 用 mvn dependency:tree 查看你项目的依赖树，观察哪些是直接依赖，哪些是传递性依赖。

5. 创建一个多模块项目：一个父模块（packaging pom）和两个子模块（common 和 app），app 依赖 common。然后从父模块执行 mvn package，观察两个子模块是否都被构建。

下一篇文章，我们将学习单元测试 —— JUnit 5。在 Maven 的基础上，我们会编写可靠的、可自动化的测试代码，保证你的程序质量。

我们下一篇见。😃

📌 获取本系列示例代码请访问 GitCode。