一、起源
- 手工管理依赖时,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 一次构建的执行路径
- 读取全局 settings.xml 与用户 settings.xml,确定本地仓库路径、镜像、认证与激活的 profile。
- 解析 POM 及其父 POM,合并属性、依赖管理与插件管理。
- 根据依赖坐标从本地仓库或远程仓库解析构件,处理传递依赖与冲突调解。
- 按生命周期阶段顺序执行,每个阶段调用绑定的插件目标。
- 产物写入
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 | 当前用户 |
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 与本地应保持同一主版本,避免插件与生命周期绑定行为不一致。
五、总结
- Maven 用坐标、仓库、生命周期、插件四个要素把构建过程固化,减少人工约定。
- POM 是配置入口,实际生效配置是父子 POM 与 settings 合并后的结果。
- 标准目录与最小 POM 足以完成一次完整构建,非必要不改默认结构。
- 环境问题优先用
mvn -v 与 help:effective-settings 确认,依赖问题优先用 dependency:tree 定位。