一、起源

  • 手工管理依赖时,jar 包存放在项目目录中,版本来源靠口头约定,传递依赖需要人工补齐,换人接手后无法复现构建结果。
  • Ant 把构建步骤写成脚本,解决了自动化问题,但没有统一约定:目录结构、依赖位置、构建产物路径由每个项目自行定义。
  • Maven 的出发点是把构建中重复出现的部分固化为约定:依赖用坐标描述,构件从仓库获取,构建按生命周期推进,特殊动作交给插件。
  • 由此形成一条固定的构建路径:读取配置、解析坐标、获取构件、按阶段执行、输出产物。理解这条路径即可解释大多数 Maven 报错。

二、原理

2.1 四个核心要素

要素 作用 典型表现形式
坐标 唯一标识一个构件 groupId、artifactId、version
仓库 存放与获取构件的位置 本地仓库、私服、中央仓库、镜像
生命周期 定义构建的固定阶段顺序 clean、default、site
插件 在阶段上执行具体动作 compiler、surefire、jar、deploy
  • 坐标解决"是谁",仓库解决"从哪里取",生命周期解决"按什么顺序做",插件解决"具体怎么做"。
  • 四者组合后,构建过程不再依赖个人经验,而是由 POM 与 settings.xml 完整描述。

2.2 POM 是唯一入口

  • 每个工程有一个 pom.xml,描述自身坐标、依赖、构建配置、插件与继承关系。
  • POM 支持继承:子 POM 通过 <parent> 复用父 POM 的依赖管理、插件管理与属性。
  • 构建时实际生效的配置是多个来源合并的结果,可用 mvn help:effective-pom 查看合并后的完整 POM。

2.3 标准目录约定

路径 用途
src/main/java 主源码
src/main/resources 主资源文件
src/test/java 测试源码
src/test/resources 测试资源文件
target 构建输出目录
pom.xml 项目描述文件
  • 目录约定是默认值,不是强制值。修改后需要同步调整编译插件与资源插件的配置,因此除非有明确理由,保持默认结构。

2.4 一次构建的执行路径

  1. 读取全局 settings.xml 与用户 settings.xml,确定本地仓库路径、镜像、认证与激活的 profile。
  2. 解析 POM 及其父 POM,合并属性、依赖管理与插件管理。
  3. 根据依赖坐标从本地仓库或远程仓库解析构件,处理传递依赖与冲突调解。
  4. 按生命周期阶段顺序执行,每个阶段调用绑定的插件目标。
  5. 产物写入 target,install 写入本地仓库,deploy 推送到远程仓库。

三、实现

3.1 安装与环境变量

  • 前置条件:已安装 JDK,且 JAVA_HOME 指向 JDK 而非 JRE。
  • 下载 Maven 二进制包并解压到固定目录,例如 D:\tools\apache-maven-3.9.9 或 /opt/apache-maven-3.9.9。
  • 配置环境变量:
变量 取值 作用
JAVA_HOME JDK 根目录 Maven 启动时定位 Java
MAVEN_HOME Maven 解压目录(部分文档写作 M2_HOME) 定位 Maven 安装目录
PATH 追加 %MAVEN_HOME%\bin 或 $MAVEN_HOME/bin 使 mvn 命令可直接调用
  • 验证方式:执行 mvn -v,输出中应包含 Maven 版本、Maven 主目录、Java 版本与 Java 主目录。Java 版本与项目要求不一致时,后续编译报错通常源于此处。

3.2 配置文件位置

文件 位置 作用范围
全局 settings.xml ${maven.home}/conf/settings.xml 当前机器上所有用户
用户 settings.xml ${user.home}/.m2/settings.xml 当前用户
  • 工程内的配置写入 POM,与机器、账号相关的配置写入 settings.xml。两者的分工见 Maven settings.xml 配置详解。
  • 需要同时使用多套配置时,可用 -s 指定用户配置文件、-gs 指定全局配置文件。

3.3 本地仓库

  • 默认位置为 ${user.home}/.m2/repository,所有下载的构件按坐标层级存放。
  • 构件首次解析时从远程仓库下载并缓存到本地,之后优先使用本地副本。
  • 本地仓库中出现 *.lastUpdated 文件,表示上一次下载失败留下的标记,删除对应版本目录后可重新下载。

3.4 最小 POM

<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
</project>
  • modelVersion 固定为 4.0.0,与 Maven 版本无关。
  • packaging 省略时默认为 jar,可选值包括 jar、war、pom、maven-plugin 等。
  • 该 POM 未声明任何依赖与插件,编译、测试、打包均由默认绑定完成。

3.5 首次构建验证

mvn -v
mvn clean package

3.6 与 IDE 的分工

四、常见误解

  • 把 Maven 当作依赖下载工具:下载只是第一步,依赖解析、冲突调解与生命周期执行才是构建的主体。
  • 认为 mvn package 会把构件安装到本地仓库:只有 install 才写入本地仓库,deploy 才推送远程仓库。
  • 认为 IDE 编译通过即构建通过:IDE 的编译路径与 Maven 的插件配置可能不一致,最终以命令行构建结果为准。
  • 认为目录结构可以随意修改:修改标准目录需要同步调整插件配置,否则出现源码或资源未被处理的情况。
  • 认为 Maven 版本越新越好:构建环境、CI 与本地应保持同一主版本,避免插件与生命周期绑定行为不一致。

五、总结

  1. Maven 用坐标、仓库、生命周期、插件四个要素把构建过程固化,减少人工约定。
  2. POM 是配置入口,实际生效配置是父子 POM 与 settings 合并后的结果。
  3. 标准目录与最小 POM 足以完成一次完整构建,非必要不改默认结构。
  4. 环境问题优先用 mvn -v 与 help:effective-settings 确认,依赖问题优先用 dependency:tree 定位。