Maven 完全指南 - 新手必读
Maven 命令、IDEA 操作与依赖排查的长篇入门记录,保留 ddcc-cloud 历史示例;简明构建模型另见 Maven 基础。
Maven 完全指南 - 新手必读
文档版本:v1.0
原记录标注日期:2025-11-15 适合人群:Java 开发新手
本文保留旧教程与 ddcc-cloud 操作上下文;其中 Java 11、Spring Boot 2.7.0、Druid 1.2.8 等是历史示例版本,不表示当前选型。简明模型与可验证的普通 JAR 示例见 Maven 基础,测试发现与配置见 JUnit。
📋 目录
- [[maven#🎯 什么是 Maven|什么是 Maven]]
- [[maven#📚 Maven 核心概念|Maven 核心概念]]
- [[maven#🔧 Maven 常用命令详解|Maven 常用命令详解]]
- [[maven#💻 IDEA 中的 Maven 操作|IDEA 中的 Maven 操作]]
- [[maven#🎯 实战经验|实战经验]]
- [[maven#📊 经验总结|经验总结]]
- [[maven#❓ 常见问题|常见问题]]
🎯 什么是 Maven
简单理解
Maven 是什么?
- Maven 是一个 Java 项目管理工具
- 帮你管理项目依赖(jar 包)
- 帮你编译、测试、打包项目
- 统一项目结构
类比生活场景:
想象你要做一道菜:
- 食材管理 → Maven 依赖管理(自动下载需要的 jar 包)
- 烹饪步骤 → Maven 生命周期(编译→测试→打包)
- 菜谱标准 → Maven 项目结构(统一的目录规范)
📚 Maven 核心概念
1. Maven 仓库
本地仓库(Local Repository)
- 位置:
C:\Users\user\.m2\repository - 作用:存储下载的 jar 包
- 类比:你家的冰箱(存储食材)
中央仓库(Central Repository)
- 位置:https://repo.maven.apache.org/maven2/
- 作用:Maven 官方的 jar 包仓库
- 类比:超市(购买食材的地方)
私服/镜像仓库
- 位置:公司内部或阿里云镜像
- 作用:加速下载,提供内部 jar 包
- 类比:社区超市(离家更近)
2. Maven 坐标(GAV)
GAV(groupId、artifactId、version)标识构件版本;具体文件还可能区分 type/extension 与 classifier,例如同一版本的主 JAR 和 sources JAR。以下为旧版本坐标示例:
<dependency>
<groupId>org.springframework.boot</groupId> <!-- 组织/公司 -->
<artifactId>spring-boot-starter-web</artifactId> <!-- 项目名称 -->
<version>2.7.0</version> <!-- 版本号 -->
</dependency>
类比: 就像快递地址
groupId:省份/城市(com.alibaba、org.springframework)artifactId:小区名称(druid、mybatis-plus)version:门牌号(1.0.0、2.5.3)
3. pom.xml 文件
POM = Project Object Model(项目对象模型)
这是 Maven 项目的核心配置文件,类比为项目的”身份证”。
原教程的 POM 结构片段(保留历史,不可独立构建):
这段缺少 modelVersion,starter 也没有可见的版本管理来源;仅声明 spring.boot.version 属性不会自动导入 BOM,java.version 也不会自动设置通用编译插件。packaging=pom 表示 POM 构件,不会自行产出应用 JAR。实际 ddcc-cloud 的父 POM、模块与插件配置未保存在本仓库,不能据此补造。完整最小 POM 使用 Maven 基础 中的示例。
<?xml version="1.0" encoding="UTF-8"?>
<project>
<!-- 1️⃣ 项目基本信息 -->
<groupId>com.credat.ddcc</groupId>
<artifactId>ddcc-cloud</artifactId>
<version>1.0.0</version>
<packaging>pom</packaging> <!-- 打包方式:pom/jar/war -->
<!-- 2️⃣ 属性配置 -->
<properties>
<java.version>11</java.version>
<spring.boot.version>2.7.0</spring.boot.version>
</properties>
<!-- 3️⃣ 依赖管理 -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
<!-- 4️⃣ 构建配置 -->
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
4. Maven 生命周期
Maven 有三个独立的生命周期:
🔵 Clean 生命周期(清理)
pre-clean → clean → post-clean
- 作用: 清理编译产生的文件
🟢 Default 生命周期(构建)
validate → … → compile → … → test → package → … → verify → install → deploy
- 作用: 完成项目的构建和发布
🟡 Site 生命周期(站点)
pre-site → site → post-site → site-deploy
- 作用: 生成项目文档和站点
🔧 Maven 常用命令详解
1. mvn compile(编译)
作用: 编译项目源代码
详细说明:
mvn compile
做了什么:
- 检查
src/main/java目录下的 Java 源文件 - 将
.java文件编译成.class字节码文件 - 输出到
target/classes目录
类比: 把你写的中文菜谱(Java 代码)翻译成厨师能看懂的专业术语(字节码)
使用场景:
- ✅ 想快速检查代码是否有语法错误
- ✅ 修改代码后,想验证能否正常编译
- ❌ 不适合最终打包部署
输出结果:
[INFO] Compiling 150 source files to D:\workProgram\ddcc-cloud\target\classes
[INFO] BUILD SUCCESS
2. mvn clean(清理)
作用: 删除之前编译生成的所有文件
详细说明:
mvn clean
做了什么:
- 删除整个
target目录 - 清理编译产生的
.class文件 - 清理打包产生的
.jar或.war文件
类比: 打扫厨房,把上次做菜的残留物都清理掉
使用场景:
- ✅ 编译出现奇怪问题(清理后重新编译)
- ✅ 切换分支或版本前
- ✅ 打包部署前(确保是最新的)
- ✅ 项目占用空间太大时
重要提示:
- ⚠️ clean 会删除
target目录,但不会删除源代码 - ⚠️ clean 不会删除本地仓库的 jar 包
实际效果:
执行前:target 文件夹存在(200MB)
执行后:target 文件夹被删除
3. mvn install(安装)
作用: 打包项目并安装到本地仓库
详细说明:
mvn install
默认生命周期到 install 的简图:
validate → … → compile → … → test → package → … → verify → install
install 不隐含 clean。各阶段实际执行哪些目标取决于 packaging 和插件绑定;JAR/WAR 构件与 packaging=pom 的聚合工程行为不同。
做了什么:
- 执行完整的构建流程
- 将项目打包成
.jar或.war文件 - 把打包文件复制到本地 Maven 仓库(
~/.m2/repository) - 其他项目可以引用这个 jar 包
类比: 做好一道菜,装盘,然后放进冰箱(本地仓库)保存,下次可以直接用
使用场景:
- ✅ 多模块项目中,A 模块被 B 模块依赖
- ✅ 本地开发公共组件,需要给其他项目使用
- ✅ 发布新版本前的测试
实际例子:
假设你的项目结构:
ddcc-cloud
├── ddcc-common ← 公共模块
├── ddcc-system ← 业务模块(依赖 ddcc-common)
└── pom.xml
操作步骤:
# 1. 先安装公共模块到本地仓库
cd ddcc-common
mvn install
# 2. 再编译业务模块(会从本地仓库找 ddcc-common)
cd ../ddcc-system
mvn compile
输出结果:
[INFO] Installing D:\workProgram\ddcc-cloud\ddcc-common\target\ddcc-common-1.0.0.jar
to C:\Users\user\.m2\repository\com\credat\ddcc\ddcc-common\1.0.0\ddcc-common-1.0.0.jar
[INFO] BUILD SUCCESS
4. mvn clean install(组合命令)
作用: 先清理,再完整构建并安装
详细说明:
mvn clean install
等同于:
mvn clean # 第1步:清理
mvn install # 第2步:完整构建并安装
使用场景:
- ✅ 最常用的命令!
- ✅ 修改代码后重新构建
- ✅ 切换分支后重新编译
- ✅ 解决依赖问题
什么时候需要 clean?
它用于清除旧构建产物,不是每次修改代码都必须执行,也不能解决错误的依赖版本、网络或运行进程未重启。
| 场景 | 不加 clean | 加 clean |
|---|---|---|
| 删除了某个类 | 旧的 .class 文件还在 | ✅ 彻底清除 |
| 修改了配置文件 | 可能用旧的配置 | ✅ 使用最新配置 |
| 切换了分支 | 可能混合新旧代码 | ✅ 干净的构建 |
常用参数:
# 跳过测试(加快速度)
mvn clean install -DskipTests
# 跳过测试编译和执行
mvn clean install -Dmaven.test.skip=true
# 激活名为 dev 的 Maven profile(不是指定配置文件)
mvn clean install -P dev
5. mvn package(打包)
作用: 打包项目但不安装到本地仓库
详细说明:
mvn package
执行流程:
compile → test → package
做了什么:
- 编译源代码
- 运行测试
- 打包成
.jar或.war文件 - 输出到
target目录 - ❌ 不会安装到本地仓库
与 install 的区别:
| 命令 | 打包 | 安装到本地仓库 | 使用场景 |
|---|---|---|---|
mvn package | ✅ | ❌ | 单纯打包部署 |
mvn install | ✅ | ✅ | 需要被其他项目依赖 |
使用场景:
- ✅ 打包部署到服务器
- ✅ 单体应用打包
- ✅ 不需要被其他项目引用
6. mvn test(测试)
作用: 运行单元测试
详细说明:
mvn test
做了什么:
- 编译
src/test/java下的测试代码 - 由所配置测试插件发现并运行测试;Surefire 常见默认命名包括 Test*、*Test、*Tests、*TestCase,不是所有类都会自动执行。JUnit Jupiter 还需要相应引擎支持。
- 生成测试报告
使用场景:
- ✅ 验证代码是否正确
- ✅ 持续集成(CI)
- ✅ 回归测试
7. mvn dependency:tree(查看依赖树)
作用: 查看项目的依赖关系
详细说明:
mvn dependency:tree
历史树形展示片段(不是完整、已核实的解析结果):
[INFO] com.credat.ddcc:ddcc-system:jar:1.0.0
[INFO] +- org.springframework.boot:spring-boot-starter-web:jar:2.7.0
[INFO] | +- org.springframework.boot:spring-boot-starter:jar:2.7.0
[INFO] | | +- org.springframework.boot:spring-boot:jar:2.7.0
[INFO] | | +- org.springframework:spring-core:jar:5.3.20
[INFO] | | \- org.yaml:snakeyaml:jar:1.30
[INFO] | +- org.springframework:spring-web:jar:5.3.20
[INFO] | \- org.springframework:spring-webmvc:jar:5.3.20
使用场景:
- ✅ 排查依赖冲突
- ✅ 查看传递依赖
- ✅ 了解项目依赖关系
💻 IDEA 中的 Maven 操作
1. Reload All Maven Projects(刷新所有 Maven 项目)
在哪里找:
- 方式1:IDEA 右侧 Maven 面板 → 点击刷新图标 🔄
- 方式2:右键项目 → Maven → Reload Project
作用:
- 重新读取
pom.xml文件 - 下载新添加的依赖
- 更新项目配置
- 刷新依赖树
什么时候用:
- ✅ 修改了
pom.xml文件 - ✅ 添加了新的依赖
- ✅ 修改了 Maven 版本
- ✅ 依赖下载失败后重试
- ✅ 切换了 Maven 配置文件
类比: 你修改了购物清单,告诉系统重新检查并下载新商品
实际例子:
<!-- 1. 在 pom.xml 中添加新依赖 -->
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>druid</artifactId>
<version>1.2.8</version>
</dependency>
<!-- 2. 点击 IDEA 右侧 Maven 面板的刷新按钮 -->
<!-- 3. IDEA 会自动下载 druid-1.2.8.jar -->
2. Maven 面板常用操作
打开 Maven 面板:
- View → Tool Windows → Maven
- 或点击右侧的 “Maven” 标签
面板功能:
Maven 面板
├── 🔄 Reload All Maven Projects (刷新)
├── ⬇️ Download Sources/Documentation (下载源码)
├── 🔍 Show Dependencies (查看依赖)
├── Lifecycle(生命周期)
│ ├── clean (清理)
│ ├── validate (验证)
│ ├── compile (编译)
│ ├── test (测试)
│ ├── package (打包)
│ ├── verify (验证)
│ └── install (安装)
└── Plugins(插件)
└── 各种 Maven 插件命令
3. IDEA 中执行 Maven 命令
方式1:使用 Maven 面板
- 打开右侧 Maven 面板
- 展开 Lifecycle
- 双击要执行的命令(如
clean、install)
方式2:使用命令行
- 点击 IDEA 底部 “Terminal” 标签
- 输入 Maven 命令:
mvn clean install
方式3:使用 Run Configuration
- Run → Edit Configurations
- 点击 + 号 → Maven
- 配置命令:
clean install -DskipTests - 点击运行
🎯 实战经验
场景1:修改代码后重新运行
问题: 修改了 Java 代码,但运行时还是旧的效果
解决方案:
# 方案1:重新编译(快速)
mvn compile
# 方案2:清理后重新编译(彻底)
mvn clean compile
# 方案3:在 IDEA 中
# Build → Rebuild Project
场景2:添加新依赖后无法使用
问题: 在 pom.xml 中添加了新依赖,但代码中无法导入
解决方案:
# 步骤1:刷新 Maven 项目
IDEA 右侧 Maven 面板 → 点击刷新图标 🔄
# 步骤2:检查 Maven 控制台中的具体解析错误及 settings、仓库、代理配置
# IDE 索引异常时才考虑 Invalidate Caches / Restart;它不是重新导入 POM
# 步骤3:需要重新检查远端时
mvn -U compile
# -U 强制检查缺失的 release 和更新的 SNAPSHOT,不是升级所有固定 release 版本
场景3:多模块项目构建
项目结构:
ddcc-cloud(父项目)
├── ddcc-common ← 公共模块
├── ddcc-system ← 系统模块(依赖 ddcc-common)
├── ddcc-gateway ← 网关模块
└── pom.xml
构建顺序:
# 方式1:在父项目根目录执行(推荐)
cd ddcc-cloud
mvn clean install
# reactor 按实际模块依赖排序;仅此图能确定 common 在 system 前
# gateway 与其他模块的相对次序不能只凭名称判断
# 方式2:在聚合根选择模块并同时构建其 reactor 依赖
mvn -pl ddcc-system -am install
# 单独进入子目录构建则要求所需父 POM 和其他模块产物已可解析
场景4:依赖冲突排查
问题: 项目中有多个版本的同一个 jar 包
排查步骤:
# 1. 查看依赖树
mvn dependency:tree
# 2. 查找特定依赖
mvn dependency:tree -Dincludes=org.springframework:spring-core
# 3. 分析冲突
mvn dependency:tree -Dverbose
处理原则:
先查看实际选中的版本与引入路径,优先在现有 BOM/dependencyManagement 中对齐兼容版本。exclusions 只切断指定依赖路径;不要把 Spring 核心依赖 spring-core 排除后就视为“冲突已修复”。如确需排除,应说明替代来源并运行编译、测试与启动验证。
场景5:加速 Maven 构建
方法1:临时跳过测试(不作为质量验证结果)
# 跳过测试执行
mvn clean install -DskipTests
# 跳过测试编译和执行
mvn clean install -Dmaven.test.skip=true
方法2:使用本地缓存
# 离线模式要求插件、依赖及其元数据已完整缓存,否则失败
mvn clean install -o
方法3:并行构建
# 使用 4 个线程并行构建
mvn clean install -T 4
# 或者自动检测 CPU 核心数
mvn clean install -T 1C
方法4:配置阿里云镜像
以下 mirrors 是 ~/.m2/settings.xml 的 settings 元素内片段。镜像替换 central 的解析来源,不保证更快;应按实际网络与可信仓库策略选择。
<mirrors>
<mirror>
<id>aliyun</id>
<mirrorOf>central</mirrorOf>
<name>Aliyun Maven Mirror</name>
<url>https://maven.aliyun.com/repository/public</url>
</mirror>
</mirrors>
📊 经验总结
Maven 命令速查表
耗时和使用频率栏是原记录的经验印象,受项目、插件与缓存影响,不构成基准。
| 命令 | 作用 | 耗时 | 使用频率 |
|---|---|---|---|
mvn compile | 编译源代码 | ⚡ 快 | ⭐⭐⭐ |
mvn clean | 清理构建目录 | ⚡ 快 | ⭐⭐⭐⭐⭐ |
mvn test | 运行测试 | ⏱️ 中 | ⭐⭐ |
mvn package | 打包项目 | ⏱️ 中 | ⭐⭐⭐⭐ |
mvn install | 安装到本地仓库 | 🐌 慢 | ⭐⭐⭐⭐⭐ |
mvn clean install | 清理并安装 | 🐌 慢 | ⭐⭐⭐⭐⭐ |
mvn dependency:tree | 查看依赖树 | ⚡ 快 | ⭐⭐⭐ |
最佳实践
✅ DO(应该做)
- 按目标选择 compile、test、package、verify 或 install;怀疑旧产物残留时再 clean。
- 多模块构建优先从聚合根执行,或用
-pl <模块> -am选择所需闭包。 - 把测试纳入日常反馈;临时跳过执行不等于验证通过。
- 按环境配置可信仓库与镜像。
- 仅在确认缓存损坏等原因后定向处理本地缓存。
dependency:purge-local-repository默认针对当前项目依赖并重新解析,不是“删除所有 SNAPSHOT”,不应作为例行全库清理命令。
❌ DON’T(不应该做)
-
不要手动修改 target 目录
- target 是自动生成的,手动修改会被覆盖
-
不要直接删除本地仓库
- 除非确实需要,否则不要删除
~/.m2/repository
- 除非确实需要,否则不要删除
-
不要在生产环境使用 SNAPSHOT 版本
- SNAPSHOT 版本不稳定,可能随时变化
-
不要提交 target 目录到 Git
- 在
.gitignore中添加:target/
- 在
常用组合命令
mvn clean install # 清理、构建并安装到本地仓库
mvn package -DskipTests # 跳过测试执行,通常仍编译测试
mvn compile # 编译主代码,不打包
mvn package # 打包,不安装到本地仓库
mvn -U compile # 强制检查缺失 release / 更新 SNAPSHOT
mvn -o package # 离线;要求缓存完整
mvn -T 4 install # reactor 并行构建;需核对插件线程安全性
mvn -P dev package # 激活 dev profile
mvn -X compile # 调试日志
mvn -q compile # 安静模式
❓ 常见问题
Q1: mvn compile 和 IDEA 的 Build 有什么区别?
A:
mvn compile:使用 Maven 编译,遵循 Maven 生命周期IDEA Build:可以使用 IDE 构建系统,也可以配置为委托 Maven;实际行为由项目设置决定,不保证更快
建议:
- 日常开发可用 IDE 构建,但核对 JDK、profile 与是否委托 Maven。
- 打包使用 package,连同已配置检查验证使用 verify;compile 本身不产出部署 JAR。
Q2: 为什么 mvn install 这么慢?
A: 因为 install 会执行完整流程:
validate → … → compile → … → test → package → … → verify → install(不含 clean)
解决方案:
先从构建日志定位下载、编译、测试或插件目标的耗时;只需编译时执行 mvn compile,需要验证交付物时仍应保留相应测试。
Q3: target 目录可以删除吗?
A:
- ✅ 可以删除,这是自动生成的
- 执行
mvn clean就是删除 target 目录 - 下次编译会重新生成
Q4: 依赖下载失败怎么办?
A:
先检查坐标、仓库/镜像、认证、代理与网络错误;必要时用 mvn -U compile 重新检查。仅确认本地条目损坏后定向处理,不把清空整个本地仓库作为第一步。
Q5: IDEA 中看不到 Maven 面板?
A:
View → Tool Windows → Maven
或者点击 IDEA 左侧/右侧边栏的 “Maven” 标签。
Q6: 多模块项目构建顺序是怎样的?
A: Maven 会自动按依赖关系排序:
reactor 根据实际项目依赖、插件等关系排序;modules 声明顺序仅在没有更强排序关系时作为依据。示例中 system 依赖 common,因此 common 在前;修改 modules 顺序不能覆盖真实依赖。
Q7: 如何查看 Maven 版本?
A:
运行 mvn -version。原记录输出为 Maven 3.8.1、D:\apache-maven-3.8.1、Java 11.0.12;这是历史环境,不代表当前机器。
Q8: 本地仓库在哪里?
A:
- Windows:
C:\Users\user\.m2\repository - Mac/Linux:
~/.m2/repository
📚 信息参考
官方文档
- Maven 官网:https://maven.apache.org/
- Maven 中央仓库:https://search.maven.org/
推荐阅读
- 《Maven 实战》 - 许晓斌
- 《Maven 权威指南》
在线工具
- Maven 依赖搜索:https://mvnrepository.com/
- POM 模型参考:https://maven.apache.org/pom.html
🎓 学习路径建议
第1天:基础概念
- 理解什么是 Maven
- 了解 Maven 仓库
- 学习 pom.xml 基本结构
第2天:常用命令
- 掌握 compile、clean、install
- 学会在 IDEA 中使用 Maven
- 练习添加依赖
第3天:实战练习
- 创建多模块项目
- 练习依赖管理
- 解决依赖冲突
第4天:进阶技巧
- 学习 Maven 生命周期
- 使用 Maven 插件
- 配置镜像加速
📞 需要帮助?
如果还有问题,可以:
- 查看 Maven 官方文档
- 搜索 Stack Overflow
- 查看项目中的
pom.xml示例
Happy Coding! 🚀
附录:ddcc-cloud 历史操作记录
针对 ddcc-cloud 项目
仅保留原教程中的项目名、路径与操作,不据此判断项目当前仍存在或模块结构未变。两个不同粒度的结构图也不能当作当前仓库清单。重新执行前应在该项目实际 checkout 中核对 POM、模块名、JDK 和启动方式;本仓库没有这些项目文件。
原记录中的项目结构:
ddcc-cloud
├── ddcc-dependencies ← 依赖管理
├── ddcc-framework ← 框架模块
├── ddcc-gateway ← 网关
├── ddcc-module-system ← 系统模块
└── pom.xml ← 父 POM
原记录的操作流程(按项目实况复核):
1️⃣ 首次构建项目(不是启动服务)
cd D:\workProgram\ddcc-cloud
mvn clean install -DskipTests
原记录跳过测试;首次下载耗时取决于网络与缓存,“10–20 分钟”只是历史估计。构建成功不等于服务已启动或测试通过。
2️⃣ 日常开发
mvn clean compile
# 或在 IDEA 中使用 Build → Rebuild Project(核对是否委托 Maven)
3️⃣ 修改了 AdminUserDO.java 后
从原项目根目录出发,旧记录给出两个替代位置(不要把它们串成连续 cd):
cd ddcc-module-system\ddcc-module-system-biz
mvn clean compile
或从原项目根目录出发:
cd ddcc-module-system
mvn clean install -DskipTests
独立子模块构建需要父 POM 和依赖模块产物可解析;模块路径以真实 POM 为准。
4️⃣ 添加新依赖后
在 pom.xml 中声明依赖后刷新 Maven 项目,再执行 mvn compile;若仍失败,先检查解析错误与所选 profile。
排查时先区分旧产物、依赖解析、编译、测试与运行状态,再选对应命令;clean install 不是通用修复。
Related notes
- 简明构建模型: Maven 基础
- 所属 MOC: Java MOC
- 所属 MOC: Development Environment MOC