Maven 构建 Java 项目（详细教程）

Maven 构建 Java 项目：从零开始掌握现代化构建工具

在 Java 开发的世界里，构建项目早已不是简单地运行 javac 和 java 命令就能搞定的事了。随着项目规模扩大，依赖库越来越多，手动管理 JAR 包不仅繁琐，还容易出错。这时候，Maven 就像一位经验丰富的“项目管家”，帮你自动处理依赖、编译、测试、打包和部署等所有流程。

今天，我们就来手把手带你用 Maven 构建一个完整的 Java 项目。无论你是刚接触 Java 的新手，还是有一定经验但对构建工具感到困惑的中级开发者，这篇文章都会让你真正理解 Maven 的工作原理，不再畏惧它复杂的配置。

为什么选择 Maven？

想象一下你正在搭建一座房子。如果每一块砖、每根钢筋都要自己去采购、运输、检查质量，那效率会非常低，还可能因为买错材料导致结构不稳。而现代建筑工地都有一个“材料清单”和“施工流程图”——这正是 Maven 的角色。

Maven 不仅能自动下载你需要的第三方库（比如 Spring 框架、JUnit 测试库），还能按照统一的规范组织代码结构，执行标准化的构建流程。它通过一个叫 pom.xml 的配置文件来描述项目，这个文件就像项目的“说明书”。

使用 Maven 构建 Java 项目，意味着你不再需要手动管理依赖版本、处理类路径冲突，也不用反复敲写编译命令。一切都有标准流程可循。

安装 Maven 并验证环境

在开始之前，确保你的开发环境中已经安装了 Maven。目前主流版本是 3.8.4 或更高，推荐使用 3.9.0 以获得更好的兼容性和性能。

下载与安装

访问 Apache Maven 官网（https://maven.apache.org/download.cgi）下载最新稳定版的二进制包（如 apache-maven-3.9.0-bin.zip），解压到任意目录，例如：

D:\tools\apache-maven-3.9.0

配置环境变量

打开系统环境变量设置，添加以下两个变量：

  • MAVEN_HOME：指向 Maven 安装目录，如 D:\tools\apache-maven-3.9.0
  • PATH：在原有值末尾添加 %MAVEN_HOME%\bin

✅ 注意：Windows 用户请使用分号 ; 分隔路径，macOS/Linux 用户用冒号 :

验证安装

打开命令行工具（CMD 或 Terminal），运行：

mvn -v

如果看到类似输出：

Apache Maven 3.9.0 (9b58d2d147c1a2632177d1027c0150c43449259e)
Maven home: D:\tools\apache-maven-3.9.0
Java version: 17.0.8, vendor: Microsoft, runtime: C:\Program Files\Java\jdk-17
Default locale: zh_CN, platform encoding: GBK
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"

说明 Maven 安装成功。此时你已经具备构建 Java 项目的基础条件。

创建第一个 Maven 项目

Maven 提供了“原型”（Archetype）机制，可以快速生成项目骨架。我们使用最常用的 maven-archetype-quickstart 来创建一个基础项目。

执行命令生成项目

在命令行中进入你希望存放项目的目录，比如 D:\projects，然后运行：

mvn archetype:generate -DgroupId=com.example -DartifactId=hello-maven -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

📌 参数说明：

  • -DgroupId=com.example：项目的组织标识，类似 Java 包名的前缀
  • -DartifactId=hello-maven：项目名称，也是最终生成的目录名
  • -DarchetypeArtifactId=maven-archetype-quickstart：使用标准快速启动模板
  • -DinteractiveMode=false：非交互模式，避免反复提问

执行完毕后，你会看到一个名为 hello-maven 的新文件夹，里面包含标准的 Maven 目录结构：

hello-maven/
├── src/
│   ├── main/
│   │   └── java/
│   │       └── com/
│   │           └── example/
│   │               └── App.java
│   └── test/
│       └── java/
│           └── com/
│               └── example/
│                   └── AppTest.java
├── pom.xml
└── README.md

目录结构详解

  • src/main/java/：存放主程序代码，遵循 Java 包命名规范
  • src/test/java/：存放单元测试代码
  • pom.xml：项目对象模型（Project Object Model），是 Maven 的核心配置文件
  • README.md：项目说明文档（可选）

这个结构是 Maven 的“约定优于配置”原则的体现——你不需要写额外配置，只要按这个结构放文件，Maven 就知道该怎么处理。

深入理解 pom.xml 配置文件

pom.xml 是 Maven 的灵魂文件，它定义了项目的元数据、依赖项、构建流程和插件。下面通过一个实际例子来解析它的关键部分。

示例：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>hello-maven</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <!-- 项目描述 -->
    <name>Hello Maven Project</name>
    <description>一个使用 Maven 构建的简单 Java 项目</description>

    <!-- 依赖管理 -->
    <dependencies>
        <!-- JUnit 5 测试框架 -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>5.9.2</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!-- 构建插件配置 -->
    <build>
        <plugins>
            <!-- 编译插件：指定 Java 版本 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>8</source>      <!-- 编译源码使用 Java 8 -->
                    <target>8</target>      <!-- 生成的字节码兼容 Java 8 -->
                    <release>8</release>   <!-- 使用 release 模式，更清晰 -->
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

关键字段解释

字段 说明
groupId 项目所属组织，通常为反向域名，如 com.example
artifactId 项目唯一标识名，如 hello-maven
version 当前版本号，SNAPSHOT 表示开发中版本
packaging 打包类型，jar 表示生成 JAR 文件
scope 依赖作用范围，test 表示仅在测试阶段使用

⚠️ 注意：<scope>test</scope> 表示该依赖只在运行测试时加载，不会被打包进最终的 JAR 包。

执行构建命令：编译、测试、打包

Maven 的强大之处在于它有一套标准生命周期（Lifecycle），每个阶段都有明确的含义。我们来一步步执行构建流程。

1. 编译源码

mvn compile

Maven 会自动：

  • 检查 pom.xml 中的依赖是否已下载
  • 将 src/main/java/ 下的 .java 文件编译为 .class 文件，输出到 target/classes/

2. 执行单元测试

mvn test

Maven 会：

  • 自动运行 src/test/java/ 中的测试类
  • 输出测试结果，包括通过数、失败数、异常信息
  • 如果测试失败，构建会中断

✅ 提示：你可以用 mvn test -Dtest=AppTest 只运行特定测试类。

3. 打包项目为 JAR

mvn package

Maven 会：

  • 将编译后的类文件、资源文件打包成一个可执行的 JAR 文件
  • 输出路径：target/hello-maven-1.0-SNAPSHOT.jar

💡 JAR 文件可以被其他项目引用，或直接用 java -jar hello-maven-1.0-SNAPSHOT.jar 运行（前提是主类有 main 方法）。

自定义构建行为与插件扩展

Maven 的灵活性不仅体现在默认流程，更在于强大的插件机制。你可以通过配置插件来自定义构建行为。

示例：添加 Maven Shade 插件，生成可执行 JAR

假设你希望生成一个包含所有依赖的“Fat JAR”，可以添加 maven-shade-plugin：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.5.0</version>
            <executions>
                <execution>
                    <phase>package</phase> <!-- 在打包阶段执行 -->
                    <goals>
                        <goal>shade</goal> <!-- 执行打补丁操作 -->
                    </goals>
                    <configuration>
                        <transformers>
                            <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                                <mainClass>com.example.App</mainClass> <!-- 设置主类 -->
                            </transformer>
                        </transformers>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

执行 mvn package 后，会在 target/ 生成一个带 jar-with-dependencies 后缀的文件，可以直接运行。

实际项目中的最佳实践建议

  1. 使用统一的依赖版本管理：在 <dependencyManagement> 中集中定义版本，避免重复声明。
  2. 避免使用 SNAPSHOT 版本发布正式产品，它代表不稳定版本。
  3. 使用 mvn clean 清理旧构建产物，防止缓存问题。
  4. 将 pom.xml 提交到 Git，确保团队成员使用相同的构建配置。
  5. 利用 mvn site 生成项目文档，便于知识沉淀。

结语

通过这篇文章，你应该已经掌握了如何使用 Maven 构建一个完整的 Java 项目。从环境安装、项目创建、配置解析，到实际构建流程，每一步都清晰可执行。

Maven 构建 Java 项目，不只是一个命令行工具的使用，更是一种工程化思维的体现。它帮你把重复性工作自动化，让你能更专注于业务逻辑本身。

当你以后面对复杂的多模块项目、CI/CD 流水线时，这些基础知识将成为你坚实的基石。别再为依赖混乱而烦恼，从今天开始，用 Maven 做你的项目“总控台”。