← [ BACK_TO_NOTES ]

Maven 完全指南 - 新手必读

Maven 命令、IDEA 操作与依赖排查的长篇入门记录,保留 ddcc-cloud 历史示例;简明构建模型另见 Maven 基础。

#java #howto #growing #dev

Maven 完全指南 - 新手必读

文档版本:v1.0
原记录标注日期:2025-11-15 适合人群:Java 开发新手

本文保留旧教程与 ddcc-cloud 操作上下文;其中 Java 11、Spring Boot 2.7.0、Druid 1.2.8 等是历史示例版本,不表示当前选型。简明模型与可验证的普通 JAR 示例见 Maven 基础,测试发现与配置见 JUnit。

📋 目录

  1. [[maven#🎯 什么是 Maven|什么是 Maven]]
  2. [[maven#📚 Maven 核心概念|Maven 核心概念]]
  3. [[maven#🔧 Maven 常用命令详解|Maven 常用命令详解]]
  4. [[maven#💻 IDEA 中的 Maven 操作|IDEA 中的 Maven 操作]]
  5. [[maven#🎯 实战经验|实战经验]]
  6. [[maven#📊 经验总结|经验总结]]
  7. [[maven#❓ 常见问题|常见问题]]

🎯 什么是 Maven

简单理解

Maven 是什么?

  • Maven 是一个 Java 项目管理工具
  • 帮你管理项目依赖(jar 包)
  • 帮你编译、测试、打包项目
  • 统一项目结构

类比生活场景:

想象你要做一道菜:

  • 食材管理 → Maven 依赖管理(自动下载需要的 jar 包)
  • 烹饪步骤 → Maven 生命周期(编译→测试→打包)
  • 菜谱标准 → Maven 项目结构(统一的目录规范)

📚 Maven 核心概念

1. Maven 仓库

本地仓库(Local Repository)

  • 位置:C:\Users\user\.m2\repository
  • 作用:存储下载的 jar 包
  • 类比:你家的冰箱(存储食材)

中央仓库(Central Repository)

私服/镜像仓库

  • 位置:公司内部或阿里云镜像
  • 作用:加速下载,提供内部 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

做了什么:

  1. 检查 src/main/java 目录下的 Java 源文件
  2. 将 .java 文件编译成 .class 字节码文件
  3. 输出到 target/classes 目录

类比: 把你写的中文菜谱(Java 代码)翻译成厨师能看懂的专业术语(字节码)

使用场景:

  • ✅ 想快速检查代码是否有语法错误
  • ✅ 修改代码后,想验证能否正常编译
  • ❌ 不适合最终打包部署

输出结果:

[INFO] Compiling 150 source files to D:\workProgram\ddcc-cloud\target\classes
[INFO] BUILD SUCCESS

2. mvn clean(清理)

作用: 删除之前编译生成的所有文件

详细说明:

mvn clean

做了什么:

  1. 删除整个 target 目录
  2. 清理编译产生的 .class 文件
  3. 清理打包产生的 .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 的聚合工程行为不同。

做了什么:

  1. 执行完整的构建流程
  2. 将项目打包成 .jar 或 .war 文件
  3. 把打包文件复制到本地 Maven 仓库(~/.m2/repository)
  4. 其他项目可以引用这个 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

做了什么:

  1. 编译源代码
  2. 运行测试
  3. 打包成 .jar 或 .war 文件
  4. 输出到 target 目录
  5. ❌ 不会安装到本地仓库

与 install 的区别:

命令打包安装到本地仓库使用场景
mvn package✅❌单纯打包部署
mvn install✅✅需要被其他项目依赖

使用场景:

  • ✅ 打包部署到服务器
  • ✅ 单体应用打包
  • ✅ 不需要被其他项目引用

6. mvn test(测试)

作用: 运行单元测试

详细说明:

mvn test

做了什么:

  1. 编译 src/test/java 下的测试代码
  2. 由所配置测试插件发现并运行测试;Surefire 常见默认命名包括 Test*、*Test、*Tests、*TestCase,不是所有类都会自动执行。JUnit Jupiter 还需要相应引擎支持。
  3. 生成测试报告

使用场景:

  • ✅ 验证代码是否正确
  • ✅ 持续集成(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

作用:

  1. 重新读取 pom.xml 文件
  2. 下载新添加的依赖
  3. 更新项目配置
  4. 刷新依赖树

什么时候用:

  • ✅ 修改了 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 面板

  1. 打开右侧 Maven 面板
  2. 展开 Lifecycle
  3. 双击要执行的命令(如 clean、install)

方式2:使用命令行

  1. 点击 IDEA 底部 “Terminal” 标签
  2. 输入 Maven 命令:mvn clean install

方式3:使用 Run Configuration

  1. Run → Edit Configurations
  2. 点击 + 号 → Maven
  3. 配置命令:clean install -DskipTests
  4. 点击运行

🎯 实战经验

场景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(应该做)

  1. 按目标选择 compile、test、package、verify 或 install;怀疑旧产物残留时再 clean。
  2. 多模块构建优先从聚合根执行,或用 -pl <模块> -am 选择所需闭包。
  3. 把测试纳入日常反馈;临时跳过执行不等于验证通过。
  4. 按环境配置可信仓库与镜像。
  5. 仅在确认缓存损坏等原因后定向处理本地缓存。dependency:purge-local-repository 默认针对当前项目依赖并重新解析,不是“删除所有 SNAPSHOT”,不应作为例行全库清理命令。

❌ DON’T(不应该做)

  1. 不要手动修改 target 目录

    • target 是自动生成的,手动修改会被覆盖
  2. 不要直接删除本地仓库

    • 除非确实需要,否则不要删除 ~/.m2/repository
  3. 不要在生产环境使用 SNAPSHOT 版本

    • SNAPSHOT 版本不稳定,可能随时变化
  4. 不要提交 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 实战》 - 许晓斌
  • 《Maven 权威指南》

在线工具


🎓 学习路径建议

第1天:基础概念

  • 理解什么是 Maven
  • 了解 Maven 仓库
  • 学习 pom.xml 基本结构

第2天:常用命令

  • 掌握 compile、clean、install
  • 学会在 IDEA 中使用 Maven
  • 练习添加依赖

第3天:实战练习

  • 创建多模块项目
  • 练习依赖管理
  • 解决依赖冲突

第4天:进阶技巧

  • 学习 Maven 生命周期
  • 使用 Maven 插件
  • 配置镜像加速

📞 需要帮助?

如果还有问题,可以:

  1. 查看 Maven 官方文档
  2. 搜索 Stack Overflow
  3. 查看项目中的 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 不是通用修复。

创建于 2025/1/1 更新于 2026/10/6
Digital Biome
Access

键盘导航

j / k / ↑ / ↓
选择对象
Enter / o
打开选择
/ 或 Ctrl+K
全站搜索
i / f / 1–4
筛选当前列表
g → h / l / p / t / a
首页 / 笔记 / 项目 / 工具 / About
r → 1–9
打开所选对象的关联
u
返回上一页
Esc
关闭浮层 / 取消命令;输入框内清空文本