第一章：入门篇 — Maven 核心概念与基础使用

目标：理解 Maven 解决什么问题，掌握 POM、坐标、仓库和基础命令，能够从零创建并构建一个标准 Java 项目。

目录

1. Maven 是什么
2. 安装与配置
3. POM 文件解析
4. 坐标系统与版本语义
5. 仓库管理
6. 基础命令全流程
7. 实战 Demo：maven-hello-world
8. 常见问题与避坑
9. 专家面试题

1. Maven 是什么

Maven 是 Java 生态中最常用的项目构建与依赖管理工具。它把一个 Java 项目的构建信息集中写在pom.xml中，由 Maven 根据固定生命周期完成编译、测试、打包、安装、发布等工作。

Maven 核心价值

Maven 与 Ant、Gradle 对比

Maven 的优势是稳定、标准、生态广。企业 Java 后端项目、Spring Boot 项目、开源组件发布仍大量使用 Maven。

2. 安装与配置

环境要求

java-versionmvn-version

建议：

Maven 目录结构

apache-maven-3.9.x/ ├── bin/ # mvn、mvnDebug 命令 ├── boot/ # Maven 自启动依赖 ├── conf/settings.xml # 全局配置 └── lib/ # Maven 运行依赖

settings.xml 关键配置

settings.xml不是项目配置，而是“用户或机器级配置”。常见位置：

全局配置：${MAVEN_HOME}/conf/settings.xml 用户配置：~/.m2/settings.xml

常用配置示例：

<settings><localRepository>/Users/yourname/.m2/repository</localRepository><mirrors><mirror><id>aliyunmaven</id><mirrorOf>central</mirrorOf><name>Aliyun Maven Central Mirror</name><url>https://maven.aliyun.com/repository/central</url></mirror></mirrors><servers><server><id>company-releases</id><username>${env.MAVEN_REPO_USER}</username><password>${env.MAVEN_REPO_PASSWORD}</password></server></servers><profiles><profile><id>company</id><repositories><repository><id>company-public</id><url>https://repo.example.com/repository/maven-public/</url></repository></repositories></profile></profiles></settings>

重要原则：

3. POM 文件解析

POM 是 Project Object Model 的缩写，描述一个项目的身份、依赖、构建规则和发布方式。

最小 POM：

<projectxmlns="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>maven-hello-world</artifactId><version>1.0.0-SNAPSHOT</version><packaging>jar</packaging></project>

GAV 坐标

一个依赖的完整身份由groupId:artifactId:version决定。

packaging 类型

本项目中：

maven-demo packaging=pom maven-demo-bom packaging=pom maven-demo-api packaging=jar maven-demo-core packaging=jar maven-demo-plugin packaging=maven-plugin maven-demo-web packaging=jar

properties

properties用来集中定义版本和构建参数：

<properties><java.version>17</java.version><spring-boot.version>3.2.5</spring-boot.version><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></properties>

最佳实践：

1. 业务依赖版本集中定义，避免散落在每个模块。
2. Java 编译版本写在父 POM。
3. 不把账号密码写进properties。

4. 坐标系统与版本语义

SNAPSHOT vs RELEASE

SNAPSHOT 依赖会被 Maven 按更新策略检查远程仓库，RELEASE 版本默认认为不可变。因此生产系统应依赖 RELEASE，不应依赖 SNAPSHOT。

语义化版本

推荐格式：

主版本.次版本.修订版本 MAJOR.MINOR.PATCH

5. 仓库管理

Maven 仓库是依赖和构建产物的存储位置。

仓库类型

依赖解析顺序

本地仓库 ↓ 未命中 远程仓库 / 镜像 ↓ 下载 写入本地仓库

常见误区：

1. 删除本地仓库可以解决缓存损坏，但会导致依赖重新下载。
2. mirrorOf=*会镜像所有仓库，可能影响公司私服发布。
3. repositories放在 POM 中会影响所有成员，应该谨慎添加。

6. 基础命令全流程

示例：

cdmaven-demo mvn clean package

关键输出：

[INFO] Reactor Summary for maven-demo 1.0.0-SNAPSHOT: [INFO] maven-demo-bom ................................ SUCCESS [INFO] maven-demo-api ................................ SUCCESS [INFO] maven-demo-core ............................... SUCCESS [INFO] maven-demo-plugin ............................. SUCCESS [INFO] maven-demo-web ................................ SUCCESS

7. 实战 Demo：maven-hello-world

如果从零创建单模块项目，可按下面结构：

maven-hello-world/ ├── pom.xml └── src/ ├── main/java/com/example/App.java └── test/java/com/example/AppTest.java

pom.xml：

<projectxmlns="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>maven-hello-world</artifactId><version>1.0.0-SNAPSHOT</version><properties><maven.compiler.release>17</maven.compiler.release><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></properties></project>

App.java：

packagecom.example;publicclassApp{publicstaticvoidmain(String[]args){System.out.println("Hello Maven");}}

运行：

mvn clean packagejava-cptarget/maven-hello-world-1.0.0-SNAPSHOT.jar com.example.App

预期输出：

Hello Maven

本仓库的综合 Demo 位于maven-demo/，它是该单模块项目的企业化扩展版本。

8. 常见问题与避坑

9. 专家面试题

Q1：Maven 的“约定优于配置”体现在哪里？

答：Maven 规定了标准目录结构、默认生命周期、默认插件绑定和默认产物位置。例如主代码默认在src/main/java，测试代码默认在src/test/java，mvn package默认会编译、测试并打包。这样团队不需要为每个项目重复定义构建脚本。它的代价是灵活性低于 Gradle，但换来更强的一致性。

Q2：为什么 Maven 坐标要有 groupId、artifactId、version 三个字段？

答：artifactId只能描述模块名，无法区分不同组织的同名模块；version用于区分同一模块的不同发布版本。三者组合后才能在仓库中唯一定位一个产物。实际依赖解析还会叠加packaging/type和classifier，但 GAV 是最核心的身份。

Q3：mvn install和mvn deploy的区别是什么？

答：install把当前项目产物安装到本机~/.m2/repository，供本机其他项目依赖；deploy把产物发布到远程仓库，供团队或 CI 使用。开发本地联调用install，正式共享版本用deploy。

Q4：为什么生产不建议依赖 SNAPSHOT？

答：SNAPSHOT 是可变版本，同一个1.0.0-SNAPSHOT在不同时间可能对应不同内容，导致构建不可复现。生产发布应依赖不可变 RELEASE 版本，并配合制品仓库权限禁止覆盖。

10. 入门篇扩展核查：必须补齐的基础知识

10.1 Maven 不是“下载 jar 的工具”

很多初学者把 Maven 理解成“自动下载 jar 包”。这个理解只覆盖了 Maven 的依赖管理能力，没有覆盖它的构建模型。

Maven 实际包含四层能力：

所以 Maven 的学习顺序不能只停留在<dependency>。如果不知道生命周期和插件，就无法解释为什么mvn package会先编译、测试再打包；如果不知道仓库和发布，就无法解释公司内部 SDK 如何被其他项目依赖。

10.2 Super POM 与 Effective POM

每个 Maven 项目都会隐式继承 Super POM。Super POM 提供了一组基础默认值，例如中央仓库、默认构建目录、默认插件绑定等。

查看当前项目最终 POM：

cdmaven-demo mvn help:effective-pom

建议重点观察：

<repositories> <pluginRepositories> <build> <plugins> <dependencyManagement> <profiles>

排查经验：

1. 你在当前 POM 找不到的插件配置，可能来自父 POM 或 Super POM。
2. 你以为没激活的 Profile，可能被 settings 或默认激活规则打开。
3. 依赖版本不符合预期时，先看 Effective POM，再看依赖树。

10.3 Maven 标准目录为什么重要

Maven 通过标准目录实现“约定优于配置”。

验证：

cdmaven-demo mvn-plmaven-demo-core clean packagefindmaven-demo-core/target-maxdepth3-typef

你会看到：

target/classes/build-info.properties target/maven-demo-core-1.0.0-SNAPSHOT.jar target/surefire-reports/...

10.4 archetype 创建项目

Maven archetype 是项目模板机制，适合快速创建标准项目。

mvn archetype:generate\-DgroupId=com.example\-DartifactId=maven-hello-world\-DarchetypeArtifactId=maven-archetype-quickstart\-DinteractiveMode=false

创建后建议立即检查：

cdmaven-hello-world mvntestmvn package

注意：archetype 生成的模板可能比较旧，例如 JUnit 版本、Java 编译版本不符合现代项目要求。生成后要升级maven-compiler-plugin、JUnit 和编码配置。

10.5 本地仓库路径如何映射

依赖坐标：

org.apache.commons:commons-lang3:3.14.0

本地仓库路径：

~/.m2/repository/org/apache/commons/commons-lang3/3.14.0/

文件通常包括：

commons-lang3-3.14.0.jar commons-lang3-3.14.0.pom _remote.repositories *.sha1

如果依赖损坏，可以只删除对应版本目录，而不是删除整个~/.m2/repository。

10.6 Maven 离线模式

离线模式只使用本地仓库，不访问远程仓库：

mvn-opackage

适用场景：

1. CI 缓存已预热。
2. 内网环境暂时不能访问外部仓库。
3. 验证项目是否具备可复现构建能力。

如果缺依赖，离线模式会失败。可以先执行：

mvn dependency:go-offline

10.7 IDE 导入 Maven 项目的核查点

在 IntelliJ IDEA 中导入 Maven 项目后，应检查：

命令行能构建但 IDE 报错，优先比较 IDEA Maven 设置和mvn -version。

10.8 入门阶段实操任务

10.9 入门篇新增面试题

Q5：Super POM 的作用是什么？

答：Super POM 是所有 Maven 项目隐式继承的基础 POM，提供默认仓库、默认构建目录、默认插件配置等。它让一个最小 POM 也能执行标准生命周期。排查真实构建行为时，应通过 Effective POM 查看 Super POM、父 POM、当前 POM 和 Profile 合并后的结果。

Q6：为什么不建议把本地 jar 用 system scope 引入？

答：systemscope 依赖不可传递，依赖路径通常写死在本机文件系统中，CI 和其他开发者机器上很容易失败。正确做法是把 jar 发布到 Nexus/Artifactory，或者至少使用mvn install:install-file安装到本地仓库并记录来源。

Q7：Maven 本地仓库可以直接删除吗？

答：可以，但不建议作为第一选择。删除整个仓库会导致所有依赖重新下载，耗时且可能受网络影响。更合理的方式是删除损坏依赖的具体版本目录，或者使用mvn -U强制更新 SNAPSHOT。