本文档涵盖 Apache Maven 的核心概念、常用命令、POM 配置、生命周期管理、插件体系、多模块项目构建、仓库配置以及企业级最佳实践。适合从入门到进阶的 Java 开发者参考。
Maven 是 Apache 开源的 项目管理和构建自动化工具，基于 项目对象模型（Project Object Model, POM） 的概念。Maven 不仅仅是构建工具，它还提供了：
- 依赖管理：自动下载和管理项目依赖（JAR 包）
- 构建标准化：统一的构建生命周期和目录结构
- 项目信息管理：版本号、开发者信息、许可证等元数据
- 插件体系：通过插件扩展构建能力（编译、测试、打包、部署）
| 术语 |
说明 |
| POM |
Project Object Model，pom.xml 文件，Maven 的核心配置文件 |
| 坐标（Coordinate） |
groupId:artifactId:version 唯一标识一个构件 |
| GAV |
GroupId + ArtifactId + Version 的简称 |
| 仓库（Repository） |
存放构件的地方，分为本地仓库、中央仓库、远程仓库 |
| 生命周期（Lifecycle） |
预定义的构建阶段序列（clean、default、site） |
| 阶段（Phase） |
生命周期中的具体步骤，如 compile、test、package |
| 插件（Plugin） |
绑定到阶段执行具体任务，如 maven-compiler-plugin |
| 目标（Goal） |
插件的具体功能，如 compiler:compile |
| 维度 |
Maven |
Gradle |
| 配置方式 |
XML（声明式） |
Groovy/Kotlin DSL（脚本式） |
| 学习曲线 |
平缓，约定优于配置 |
较陡，灵活性高 |
| 构建性能 |
较慢（增量构建支持有限） |
更快（增量构建、构建缓存） |
| 插件生态 |
丰富成熟 |
丰富，且可复用 Maven 生态 |
| 多模块项目 |
原生支持 |
原生支持，更灵活 |
| 适用场景 |
传统企业级 Java 项目 |
Android、微服务、需要高度定制化的项目 |
选型建议：
- 团队熟悉 XML 配置、追求稳定性 → Maven
- 需要构建性能优化、多语言混合项目 → Gradle
- 已有 Maven 项目迁移成本较高，除非性能瓶颈明显，否则不建议迁移
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install maven
# macOS (Homebrew)
brew install maven
# 验证安装
mvn -v
编辑 ~/.m2/settings.xml 配置阿里云镜像，加速依赖下载：
<settings>
<mirrors>
<mirror>
<id>aliyunmaven</id>
<name>阿里云公共仓库</name>
<url>https://maven.aliyun.com/repository/public</url>
<mirrorOf>central</mirrorOf>
</mirror>
</mirrors>
</settings>
| 配置项 |
说明 |
示例 |
localRepository |
本地仓库路径 |
<localRepository>/data/maven-repo</localRepository> |
proxies |
HTTP 代理配置 |
企业内网需要 |
servers |
私服认证信息 |
部署到 Nexus/Artifactory |
profiles |
多环境配置 |
开发/测试/生产环境切换 |
<?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-project</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<!-- 项目信息 -->
<name>Demo Project</name>
<description>示例项目</description>
<!-- 属性配置 -->
<properties>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<!-- 依赖管理 -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>3.2.0</version>
</dependency>
</dependencies>
</project>
| Scope |
编译 |
测试 |
运行 |
打包 |
说明 |
compile |
✅ |
✅ |
✅ |
✅ |
默认范围，全程参与 |
provided |
✅ |
✅ |
- |
- |
容器提供，如 Servlet API |
runtime |
- |
✅ |
✅ |
✅ |
运行时需要，如 JDBC 驱动 |
test |
- |
✅ |
- |
- |
仅测试使用，如 JUnit |
system |
✅ |
✅ |
- |
- |
本地系统路径依赖（不推荐） |
import |
- |
- |
- |
- |
仅用于 <dependencyManagement> 导入 BOM |
Maven 使用 最近优先（Nearest Definition） 和 先声明优先（First Declaration） 原则解决依赖冲突：
项目 A
├── B → C → D(v1.0)
└── E → D(v2.0)
结果：D(v2.0) 被采用（路径更短）
排查依赖冲突：
# 查看依赖树
mvn dependency:tree
# 查看冲突依赖
mvn dependency:tree -Dverbose
# 生成依赖分析报告
mvn dependency:analyze
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-logging</artifactId>
</exclusion>
</exclusions>
</dependency>
<properties>
<spring-boot.version>3.2.0</spring-boot.version>
<lombok.version>1.18.30</lombok.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<version>${spring-boot.version}</version>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>3.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
BOM（Bill of Materials）导入：Spring Boot、Google Cloud 等框架提供 BOM，一次性管理所有相关依赖的版本，避免版本冲突。
| 生命周期 |
用途 |
主要阶段 |
| clean |
清理项目 |
pre-clean → clean → post-clean |
| default |
构建部署 |
validate → compile → test → package → verify → install → deploy |
| site |
生成站点文档 |
pre-site → site → post-site → site-deploy |
validate → initialize → generate-sources → process-sources →
generate-resources → process-resources → compile → process-classes →
generate-test-sources → process-test-sources → generate-test-resources →
process-test-resources → test-compile → process-test-classes →
test → prepare-package → package → pre-integration-test →
integration-test → post-integration-test → verify →
install → deploy
常用阶段速查：
| 阶段 |
说明 |
典型绑定插件 |
compile |
编译主源码 |
maven-compiler-plugin |
test |
运行单元测试 |
maven-surefire-plugin |
package |
打包成 JAR/WAR |
maven-jar-plugin / maven-war-plugin |
verify |
验证包完整性 |
maven-failsafe-plugin（集成测试） |
install |
安装到本地仓库 |
内置 |
deploy |
部署到远程仓库 |
内置 |
<build>
<plugins>
<!-- 编译插件 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>17</source>
<target>17</target>
<compilerArgs>
<arg>-parameters</arg>
</compilerArgs>
</configuration>
</plugin>
<!-- Spring Boot 打包插件 -->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>3.2.0</version>
<configuration>
<mainClass>com.example.Application</mainClass>
<executable>true</executable>
</configuration>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
# 检查当前生效的 POM（合并所有父 POM 和 Profile 后的最终配置）
mvn help:effective-pom
# 查看生效的 settings.xml
mvn help:effective-settings
# 查看系统属性和环境变量
mvn help:system
# 查看插件描述信息
mvn help:describe -Dplugin=compiler -Ddetail
# 完整构建（编译 + 测试 + 打包）
mvn clean package
# 跳过测试编译和运行（快速构建）
mvn clean package -DskipTests
# 跳过测试运行但编译测试代码
mvn clean package -Dmaven.test.skip=true
# 仅编译主代码
mvn compile
# 仅运行测试
mvn test
# 安装到本地仓库
mvn clean install
# 部署到远程仓库
mvn clean deploy
# 查看依赖树
mvn dependency:tree
# 查看依赖树（包含重复/冲突）
mvn dependency:tree -Dverbose
# 分析依赖（找出未使用/缺失的依赖）
mvn dependency:analyze
# 下载源码和文档
mvn dependency:sources
mvn dependency:resolve -Dclassifier=javadoc
# 复制依赖到指定目录
mvn dependency:copy-dependencies -DoutputDirectory=libs
# 创建普通 Java 项目
mvn archetype:generate -DgroupId=com.example -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
# 创建 Web 项目
mvn archetype:generate -DarchetypeArtifactId=maven-archetype-webapp
# 生成项目站点文档
mvn site
# 生成 IDEA 项目文件
mvn idea:idea
# 生成 Eclipse 项目文件
mvn eclipse:eclipse
# 开启调试模式（查看详细执行过程）
mvn clean package -X
# 仅显示错误信息
mvn clean package -q
# 离线模式（不连接远程仓库）
mvn clean package -o
# 强制更新依赖（忽略本地缓存）
mvn clean package -U
# 指定 Profile 构建
mvn clean package -P production
# 并行构建（多模块项目加速）
mvn clean package -T 4
my-project/
├── pom.xml # 父 POM（聚合 + 继承）
├── module-common/ # 公共模块
│ └── pom.xml
├── module-domain/ # 领域模型
│ └── pom.xml
├── module-service/ # 业务服务
│ └── pom.xml
└── module-web/ # Web 入口
└── pom.xml
<!-- 父 POM：my-project/pom.xml -->
<project>
<groupId>com.example</groupId>
<artifactId>my-project</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<!-- 聚合子模块 -->
<modules>
<module>module-common</module>
<module>module-domain</module>
<module>module-service</module>
<module>module-web</module>
</modules>
<!-- 统一依赖版本 -->
<properties>
<java.version>17</java.version>
<spring-boot.version>3.2.0</spring-boot.version>
</properties>
<!-- 依赖版本管理（子模块不强制继承，可自选） -->
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- 内部模块版本管理 -->
<dependency>
<groupId>com.example</groupId>
<artifactId>module-common</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
</dependencyManagement>
<!-- 插件版本管理 -->
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>${java.version}</source>
<target>${java.version}</target>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>
</project>
<!-- module-web/pom.xml -->
<project>
<parent>
<groupId>com.example</groupId>
<artifactId>my-project</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>module-web</artifactId>
<packaging>jar</packaging>
<dependencies>
<!-- 引用内部模块（版本由父 POM 管理） -->
<dependency>
<groupId>com.example</groupId>
<artifactId>module-service</artifactId>
</dependency>
<!-- 引用外部依赖（版本由 BOM 管理） -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
</project>
# 构建所有模块
mvn clean install
# 仅构建特定模块（及其依赖模块）
mvn clean install -pl module-web -am
# 仅构建特定模块（不构建依赖）
mvn clean install -pl module-web
# 构建特定模块及其下游模块
mvn clean install -pl module-common -amd
# 跳过子模块测试
mvn clean install -DskipTests
# 并行构建加速
mvn clean install -T 1C # 每个 CPU 核心一个线程
<profiles>
<!-- 开发环境 -->
<profile>
<id>dev</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<env>dev</env>
<db.url>jdbc:mysql://localhost:3306/dev_db</db.url>
<db.password>dev123</db.password>
</properties>
</profile>
<!-- 测试环境 -->
<profile>
<id>test</id>
<properties>
<env>test</env>
<db.url>jdbc:mysql://test-db:3306/test_db</db.url>
</properties>
</profile>
<!-- 生产环境 -->
<profile>
<id>prod</id>
<properties>
<env>prod</env>
<db.url>${PROD_DB_URL}</db.url>
<db.password>${PROD_DB_PASSWORD}</db.password>
</properties>
</profile>
</profiles>
# 激活指定 Profile
mvn clean package -P prod
# 查看当前激活的 Profile
mvn help:active-profiles
# 资源过滤（替换占位符）
# src/main/resources/application.properties:
# db.url=${db.url}
Spring Boot 项目通常将环境配置放在 application-{profile}.properties 中，Maven Profile 用于控制打包时包含哪些资源：
<profile>
<id>prod</id>
<build>
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
<excludes>
<exclude>application-dev.properties</exclude>
<exclude>application-test.properties</exclude>
</excludes>
</resource>
</resources>
</build>
</profile>
| 类型 |
说明 |
地址示例 |
| 本地仓库 |
本机缓存 |
~/.m2/repository |
| 中央仓库 |
Maven 官方 |
https://repo.maven.apache.org/maven2 |
| 远程仓库 |
第三方或企业私服 |
https://nexus.company.com/repository/maven-public |
<!-- 在 pom.xml 或 settings.xml 中配置 -->
<repositories>
<repository>
<id>company-nexus</id>
<name>Company Nexus</name>
<url>https://nexus.company.com/repository/maven-public/</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
<!-- 部署配置 -->
<distributionManagement>
<repository>
<id>company-releases</id>
<url>https://nexus.company.com/repository/maven-releases/</url>
</repository>
<snapshotRepository>
<id>company-snapshots</id>
<url>https://nexus.company.com/repository/maven-snapshots/</url>
</snapshotRepository>
</distributionManagement>
<!-- settings.xml -->
<servers>
<server>
<id>company-releases</id>
<username>${env.NEXUS_USERNAME}</username>
<password>${env.NEXUS_PASSWORD}</password>
</server>
</servers>
安全提示：密码应使用环境变量或 Maven 密码加密功能，避免明文存储。
| 插件 |
用途 |
常用目标 |
maven-compiler-plugin |
Java 编译 |
compiler:compile |
maven-jar-plugin |
打 JAR 包 |
jar:jar |
maven-war-plugin |
打 WAR 包 |
war:war |
maven-shade-plugin |
打包依赖（Fat JAR） |
shade:shade |
spring-boot-maven-plugin |
Spring Boot 可执行 JAR |
spring-boot:repackage |
| 插件 |
用途 |
配置示例 |
maven-surefire-plugin |
单元测试 |
默认绑定 test 阶段 |
maven-failsafe-plugin |
集成测试 |
绑定 integration-test 阶段 |
jacoco-maven-plugin |
代码覆盖率 |
生成 HTML/XML 报告 |
spotbugs-maven-plugin |
静态分析 |
查找潜在 Bug |
checkstyle-maven-plugin |
代码风格检查 |
统一团队编码规范 |
| 插件 |
用途 |
mybatis-generator-maven-plugin |
生成 MyBatis 实体和 Mapper |
openapi-generator-maven-plugin |
根据 OpenAPI 规范生成客户端/服务端代码 |
protobuf-maven-plugin |
编译 Protocol Buffers 文件 |
| 版本格式 |
说明 |
使用场景 |
1.0.0-SNAPSHOT |
开发中版本 |
日常开发、CI 构建 |
1.0.0-RC1 |
发布候选 |
预发布测试 |
1.0.0 |
正式版本 |
生产发布 |
1.0.1 |
补丁版本 |
Bug 修复 |
# Jenkins/GitLab CI 常用构建命令
mvn clean verify \
-DskipITs=false \
-Dmaven.test.failure.ignore=true \
-Djacoco.reportPaths=target/jacoco.exec
<!-- 启用并行编译 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<fork>true</fork>
<compilerArgs>
<arg>-J-XX:+UseG1GC</arg>
</compilerArgs>
</configuration>
</plugin>
# 构建加速技巧
mvn clean install -T 1C # 并行构建
mvn clean install -o # 离线模式（已下载完依赖后）
mvn clean install -DskipTests # 跳过测试
| 问题 |
原因 |
解决方案 |
| 依赖下载失败 |
网络或仓库配置 |
检查 settings.xml 镜像配置 |
| 版本冲突 |
传递依赖冲突 |
mvn dependency:tree 排查，使用 <exclusion> |
| 编译失败 |
JDK 版本不匹配 |
检查 maven.compiler.source/target |
| 测试失败 |
环境依赖缺失 |
使用 -DskipTests 跳过或配置测试环境 |
| 打包缺失依赖 |
依赖 scope 为 provided |
确认 scope 设置，或改用 shade 插件 |
# 基础构建
mvn clean package # 清理并打包
mvn clean install # 清理并安装到本地仓库
mvn clean deploy # 清理并部署到远程仓库
# 调试诊断
mvn clean package -X # 调试模式
mvn clean package -q # 静默模式
mvn help:effective-pom # 查看生效 POM
mvn dependency:tree # 依赖树
# 测试相关
mvn test # 运行测试
mvn test -Dtest=ClassName # 运行指定测试类
mvn clean package -DskipTests # 跳过测试
mvn clean package -Dmaven.test.skip # 跳过测试编译和运行
# 多模块
mvn clean install -pl module -am # 构建模块及依赖
mvn clean install -pl module -amd # 构建模块及下游
mvn clean install -T 4 # 4 线程并行构建
<!-- Spring Boot Web -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Lombok -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<scope>provided</scope>
</dependency>
<!-- JUnit 5 -->
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
<!-- SLF4J + Logback -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-logging</artifactId>
</dependency>
原始内容保留：本文档基于 Hugo 的 Maven 常用命令笔记扩展而成，原笔记中的核心命令（如 mvn help:effective-pom）已整合进第 5 节「常用命令」中，并补充了完整的上下文说明和使用场景。