Maven 入门指南

🌟 一、整体结构概览

这篇文章是一个新手向导 + 常见问题手册（Cookbook）：

对初学者：建议按顺序阅读。
对有经验者：可以直接跳到需要的部分查找解决方案。

前提是你已经安装好了 Maven。如果没有，请先去官网下载并安装。

🔍 二、核心章节详解

1. 什么是 Maven？

✅ 核心定义：

Maven 是一个项目管理和构建自动化工具，它的目标是通过标准化和模式化来简化 Java 项目的构建过程。

Maven 能管理什么？

功能	说明
构建（Builds）	编译、打包、测试等
文档（Documentation）	自动生成项目文档网站
报告（Reporting）	测试覆盖率、静态分析报告等
依赖管理（Dependencies）	自动下载 JAR 包及其传递依赖
版本控制（SCMs）	集成 Git/SVN 等
发布（Releases）	支持版本发布流程
分发（Distribution）	打包部署到远程仓库

📌 一句话总结 ：

Maven 不只是一个"编译工具"，而是一个完整的项目生命周期管理平台。

2. Maven 如何帮助你的开发流程？

使用约定优于配置（Convention Over Configuration）
- 比如源码放在 src/main/java，资源文件在 src/main/resources
- 无需手动指定路径
提高团队协作效率
减少重复劳动（自动下载依赖、统一构建脚本）

💡 举例：Ant 需要写很多 XML 来做同样的事；Maven 只需几行 POM 就能完成。

3. 如何设置 Maven？

大多数情况下默认配置就够用了。

如果遇到以下情况需要修改配置：

更改本地缓存目录（.m2/repository）
在公司 behind HTTP proxy（代理环境）

👉 配置文件位置：

bash 复制代码

~/.m2/settings.xml

参考官方文档：Guide to Configuring Maven

4. 创建第一个 Maven 项目

使用 Archetype（原型机制） 快速生成项目骨架：

bash 复制代码

mvn archetype:generate \
  -DgroupId=com.mycompany.app \
  -DartifactId=my-app \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.5 \
  -DinteractiveMode=false

参数解释：

参数	含义
`groupId`	组织 ID，通常是反向域名，如 `com.company.project`
`artifactId`	项目名，生成的 JAR 名称会基于这个
`version`	版本号，默认是 `1.0-SNAPSHOT`
`SNAPSHOT`	表示"快照版"------正在开发中的不稳定版本

生成后目录结构如下：

复制代码

my-app/
├── pom.xml
└── src/
    ├── main/java/          ← 主代码
    └── test/java/          ← 单元测试代码

这是 Maven 的标准目录布局（Standard Directory Layout）。

5. pom.xml 文件详解

POM = Project Object Model（项目对象模型），是 Maven 的核心。

xml 复制代码

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>jar</packaging>

  <name>My App</name>
  <url>http://example.com</url>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>17</maven.compiler.release>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-api</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

关键元素说明：

元素	作用
`<groupId>:<artifactId>:<version>`	三元组唯一标识一个构件（Artifact）
`<packaging>`	打包类型，默认为 `jar`，也可为 `war`, `pom` 等
`<dependencies>`	声明项目所依赖的第三方库
`<scope>`	依赖的作用范围（compile/test/runtime/provided/system/import）
`<properties>`	定义变量，用于复用或参数化

6. 常用命令操作

命令	作用
`mvn compile`	编译主代码 → 输出到 `target/classes`
`mvn test-compile`	编译测试代码
`mvn test`	运行单元测试（自动执行 `compile` 和 `test-compile`）
`mvn package`	打包成 JAR/WAR 文件 → `target/my-app-1.0-SNAPSHOT.jar`
`mvn install`	安装到本地仓库（`.m2/repository`），供其他项目引用
`mvn clean`	删除 `target/` 目录，清理构建产物
`mvn site`	生成项目文档站点（HTML 页面）

🎯 注意：

第一次运行时 Maven 会自动下载所需插件和依赖，后续速度更快。

7. 什么是 SNAPSHOT 版本？

1.0-SNAPSHOT：表示当前开发中版本，可能每天都在变。
1.0：正式发布版本，一旦发布就不能再修改。

🔧 发布流程示例：

复制代码

开发阶段：1.0-SNAPSHOT
↓ 发布
正式版本：1.0
↓ 开发继续
新开发版：1.1-SNAPSHOT

✅ Maven 在拉取 SNAPSHOT 版本时会检查是否有更新，确保获取最新代码。

8. 如何使用插件（Plugins）

几乎所有功能都由插件实现。例如：

示例：让 Maven 使用 Java 17 编译

xml 复制代码

<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>
      </configuration>
    </plugin>
  </plugins>
</build>

📌 插件会在对应的生命周期阶段自动执行（比如 compile 阶段调用编译器插件）。

9. 如何添加资源文件到 JAR？

遵循标准目录结构即可：

复制代码

src/
 └── main/
     └── resources/
         └── config.properties

这些资源会被直接复制进 JAR 包根目录。

例如：getClass().getResource("/config.properties") 可以读取该文件。

10. 如何过滤资源文件？（动态替换变量）

常用于不同环境中注入配置值（如数据库地址、版本号等）。

步骤：

在 resources 文件中使用 ${xxx} 占位符：

properties 复制代码

app.name=${project.name}
app.version=${project.version}
message=${my.filter.value}

启用资源过滤：

xml 复制代码

<build>
  <resources>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>true</filtering>
    </resource>
  </resources>
</build>

变量来源：

类型	示例
POM 属性	`${project.name}`, `${project.version}`
自定义属性	`<properties><my.filter.value>hello</my.filter.value></properties>`
外部 `.properties` 文件	`<filters><filter>src/main/filters/filter.properties</filter></filters>`
系统属性	`-Dcommand.line.prop=value` → `${command.line.prop}`

运行 mvn process-resources 触发过滤。

11. 如何引入外部依赖？

只需在 <dependencies> 中声明：

xml 复制代码

<dependency>
  <groupId>log4j</groupId>
  <artifactId>log4j</artifactId>
  <version>1.2.17</version>
  <scope>compile</scope>
</dependency>

scope 说明：

scope	用途
`compile`（默认）	主代码和测试都可用
`test`	仅测试可用（如 JUnit）
`provided`	编译时需要，运行时容器提供（如 Servlet API）
`runtime`	编译不需要，运行时需要（如 JDBC 驱动）

📦 依赖查找方式：

访问 https://repo.maven.apache.org/maven2/
或使用搜索引擎：https://search.maven.org

Maven 会自动下载依赖及其传递依赖（Transitive Dependencies）到本地仓库。

12. 如何部署 JAR 到远程仓库？

适用于公司私有仓库（如 Nexus、Artifactory）。

步骤：

在 pom.xml 中配置分发地址：

xml 复制代码

<distributionManagement>
  <repository>
    <id>internal-repo</id>
    <url>https://your-company-nexus.com/repository/maven-releases/</url>
  </repository>
</distributionManagement>

在 ~/.m2/settings.xml 中配置用户名密码：

xml 复制代码

<servers>
  <server>
    <id>internal-repo</id>
    <username>deploy-user</username>
    <password>your-secret-password</password>
  </server>
</servers>

执行部署命令：
bash 复制代码
```
mvn deploy
```

🔒 安全提示：建议对密码进行加密（见 Maven Password Encryption）

13. 如何生成文档？

使用 Site 插件快速生成 HTML 文档网站：

bash 复制代码

mvn site

也可以用 archetype 生成文档项目模板：

bash 复制代码

mvn archetype:generate \
  -DarchetypeGroupId=org.apache.maven.archetypes \
  -DarchetypeArtifactId=maven-archetype-site

文档可包含：

项目信息
测试报告
Checkstyle 结果
JaCoCo 覆盖率等

14. 如何构建其他类型的项目？

Web 应用（WAR）

bash 复制代码

mvn archetype:generate \
  -DarchetypeArtifactId=maven-archetype-webapp

POM 中 <packaging>war</packaging>，运行 mvn package 得到 .war 文件。

多模块项目（Multi-module）

场景：一个 Web 工程依赖一个 Core 工具类 JAR。

目录结构：

复制代码

parent-project/
├── pom.xml           ← 父 POM
├── my-app/           ← 子模块1（JAR）
│   └── pom.xml
└── my-webapp/        ← 子模块2（WAR）
    └── pom.xml

父 POM (pom.xml)：

xml 复制代码

<packaging>pom</packaging>
<modules>
  <module>my-app</module>
  <module>my-webapp</module>
</modules>

子模块 POM 添加 <parent>：

xml 复制代码

<parent>
  <groupId>com.mycompany.app</groupId>
  <artifactId>parent-project</artifactId>
  <version>1.0-SNAPSHOT</version>
</parent>

然后在 my-webapp 中引用 my-app：

xml 复制代码

<dependency>
  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <version>1.0-SNAPSHOT</version>
</dependency>

运行 mvn install 会自动构建所有模块，并正确处理依赖顺序。

✅ 三、总结：Maven 的优势

优势	说明
✅ 约定优于配置	减少配置文件复杂度
✅ 强大的依赖管理	自动解决依赖冲突和传递依赖
✅ 统一生命周期	`clean`, `compile`, `test`, `package`, `install`, `deploy`
✅ 插件丰富	几乎所有构建任务都有对应插件
✅ 易于集成 CI/CD	Jenkins、GitLab CI 等天然支持
✅ 支持多模块项目	大型项目组织更清晰

📚 四、学习建议

动手实践：按照文档一步步创建项目、编译、打包。
查阅官方文档 ：
使用 IDE 支持：IntelliJ IDEA / Eclipse 都内置 Maven 支持。
掌握常用命令 ：mvn clean compile test package install deploy

如果你有任何具体问题，比如：

"怎么用 Maven 构建 Spring Boot 项目？"
"如何排除某个传递依赖？"
"Maven 生命周期有哪些阶段？"

欢迎继续提问！我可以给你更深入的解答。