Maven 常用命令详解

前言

Apache Maven 是 Java 项目管理和构建自动化工具，它通过一个项目对象模型（POM, Project Object Model）来管理项目的构建、报告和文档。Maven 的核心优势在于其强大的依赖管理、标准化的项目结构以及丰富的插件生态系统。掌握 Maven 的常用命令是每个 Java 开发者必备的技能。

本篇博客将详细介绍 Maven 的核心命令，涵盖项目构建、依赖管理、生命周期操作、插件执行、项目信息查询等多个方面，并结合实际场景进行说明，帮助您高效地使用 Maven。

一、Maven 核心概念回顾

在深入命令之前，先快速回顾几个关键概念：

POM (Project Object Model): 位于 pom.xml 文件中，是 Maven 项目的配置中心，定义了项目信息、依赖、插件、构建配置等。
生命周期 (Lifecycle): Maven 定义了三套独立的生命周期：default（构建项目）、clean（清理项目）、site（生成项目站点文档）。每个生命周期包含一系列按顺序执行的阶段（phase）。
阶段 (Phase): 生命周期中的一个步骤。例如，default 生命周期包含 validate, compile, test, package, verify, install, deploy 等阶段。
目标 (Goal): 插件（Plugin）的功能单元。一个阶段可以绑定一个或多个目标。
仓库 (Repository): 存储构件（Artifacts）的地方。分为本地仓库（Local Repository）、中央仓库（Central Repository）和远程仓库（Remote Repository，如公司私服 Nexus/Artifactory）。

二、Maven 常用命令详解

1. 项目构建与生命周期命令

这些命令是 Maven 最基础也是最常用的，直接对应 default 生命周期的阶段。

`mvn compile`

作用： 编译主代码（src/main/java 目录下的 .java 文件）。
执行阶段： 执行到 compile 阶段为止，包含之前的所有阶段（如 validate, generate-sources, process-sources, generate-resources, process-resources）。
输出： 编译后的 .class 文件位于 target/classes 目录。
示例：
bash 复制代码
```
mvn compile
```

`mvn test-compile`

作用： 编译测试代码（src/test/java 目录下的 .java 文件）。
执行阶段： 执行到 test-compile 阶段。
输出： 编译后的测试 .class 文件位于 target/test-classes 目录。
说明： 此命令通常在运行测试前自动执行，但也可以单独运行。
示例：
bash 复制代码
```
mvn test-compile
```

`mvn test`

作用： 运行项目的单元测试（使用 JUnit, TestNG 等框架）。
执行阶段： 执行到 test 阶段，包含之前的 compile 和 test-compile。
输出： 测试结果报告通常在 target/surefire-reports（或 target/failsafe-reports）目录下。
示例：
bash 复制代码
```
mvn test
```
常用参数：
- -Dtest=TestClass：运行指定的测试类。
- -Dtest=TestClass#testMethod：运行指定测试类中的某个方法。
- -DskipTests：跳过测试执行（但不跳过编译）。
- -Dmaven.test.skip=true：跳过测试的编译和执行。

`mvn package`

作用： 将编译后的代码打包成可分发的格式，如 JAR、WAR 或 EAR。
执行阶段： 执行到 package 阶段，包含之前的 compile, test, verify 等。
输出： 生成的包文件（如 myapp-1.0.0.jar）位于 target 目录。
示例：
bash 复制代码
```
mvn package
```

`mvn verify`

作用： 对包进行检查，验证其有效性。这可能包括运行集成测试（如果配置了 maven-failsafe-plugin）、静态代码分析（如 Checkstyle, PMD, FindBugs）、代码覆盖率（如 JaCoCo）等。
执行阶段： 执行到 verify 阶段。
说明： 这个阶段通常用于在部署前确保包的质量。
示例：
bash 复制代码
```
mvn verify
```

`mvn install`

作用： 将项目打包并安装到本地仓库（通常是 ~/.m2/repository），供本地其他项目作为依赖使用。
执行阶段： 执行到 install 阶段，包含 package 及之前的所有阶段。
输出： 包文件和 pom.xml 被复制到本地仓库的相应目录。
示例：
bash 复制代码
```
mvn install
```
常用参数：
- -Dmaven.test.skip=true：跳过测试，加快安装速度（适用于已测试过的代码）。

`mvn deploy`

作用： 将项目最终的包（以及 pom.xml 等元数据）上传到配置的远程仓库（如公司私服或 Maven Central）。
执行阶段： 执行到 deploy 阶段。
前提： 必须在 pom.xml 中配置 <distributionManagement> 元素，并且通常需要在 settings.xml 中配置服务器认证信息（<server>）。
示例：
bash 复制代码
```
mvn deploy
```

2. 清理与构建命令

`mvn clean`

作用： 删除 target 目录及其内容，清理之前构建生成的所有文件（编译结果、测试报告、打包文件等）。
生命周期： 对应 clean 生命周期。
执行阶段： 执行 clean 阶段。
重要性： 在进行干净的构建或解决构建缓存问题时非常有用。
示例：
bash 复制代码
```
mvn clean
```

`mvn clean compile`

组合命令： 先清理，再编译。
示例：
bash 复制代码
```
mvn clean compile
```

`mvn clean install`

组合命令： 先清理，再完整构建并安装到本地仓库。这是开发中非常常用的命令。
示例：
bash 复制代码
```
mvn clean install
```

`mvn clean deploy`

组合命令： 先清理，再完整构建并部署到远程仓库。
示例：
bash 复制代码
```
mvn clean deploy
```

3. 依赖管理命令

`mvn dependency:resolve`

作用： 解析并显示项目直接声明的依赖项。
插件目标： dependency 插件的 resolve 目标。
示例：
bash 复制代码
```
mvn dependency:resolve
```

`mvn dependency:tree`

作用： 以树状结构显示项目的完整依赖关系图，包括直接依赖和传递性依赖。这是解决依赖冲突的利器。
输出： 清晰地展示每个依赖的版本、范围（scope）以及可能的冲突（标记为 [omitted for conflict]）。
示例：
bash 复制代码
```
mvn dependency:tree
```
常用参数：
- -Dverbose：显示更详细的信息，包括被排除的依赖和冲突。
- -Dincludes=groupId:artifactId：只显示包含特定 groupId 和/或 artifactId 的依赖。
- -Dexcludes=groupId:artifactId：排除显示特定的依赖。
- -DoutputFile=filename.txt：将输出重定向到文件。

`mvn dependency:analyze`

作用： 分析项目的依赖使用情况，报告：
- Unused declared dependencies: 在 pom.xml 中声明但代码中未实际使用的依赖。
- Used undeclared dependencies: 代码中使用了但未在 pom.xml 中声明的依赖（通常来自传递性依赖）。
目的： 帮助优化 pom.xml，移除不必要的依赖，明确声明必需的依赖。
示例：
bash 复制代码
```
mvn dependency:analyze
```

`mvn dependency:copy-dependencies`

作用： 将项目的所有依赖（包括传递性依赖）复制到指定目录。
用途： 创建一个包含所有依赖的 lib 目录，便于打包或分发。

示例：

bash 复制代码

mvn dependency:copy-dependencies
# 默认复制到 target/dependency

常用参数：
- -DoutputDirectory=lib：指定输出目录（如 lib）。
- -DincludeScope=compile：只复制特定范围的依赖（如 compile, runtime, test 等）。

4. 插件执行命令

Maven 的功能主要通过插件实现。可以使用 mvn plugin:goal 的格式直接调用插件的目标。

`mvn archetype:generate`

作用： 使用 maven-archetype-plugin 插件生成新项目的骨架（Scaffolding）。
交互式： 运行此命令会提示选择 archetype（项目模板），如 maven-archetype-quickstart（标准 Java 项目）。

非交互式示例：

bash 复制代码

mvn archetype:generate -DgroupId=com.example -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

`mvn compiler:compile`

作用： 直接调用 maven-compiler-plugin 的 compile 目标。通常与生命周期命令 mvn compile 效果相同，但更直接。
示例：
bash 复制代码
```
mvn compiler:compile
```

`mvn surefire:test`

作用： 直接调用 maven-surefire-plugin 的 test 目标来运行单元测试。
示例：
bash 复制代码
```
mvn surefire:test
```

`mvn failsafe:integration-test`

作用： 调用 maven-failsafe-plugin 的 integration-test 目标来运行集成测试（通常在 src/test/java 的 **/IT*.java 或 **/*IT.java 文件中）。
说明： failsafe 插件设计为即使集成测试失败，构建过程也不会中断，直到 verify 阶段才检查结果。
示例：
bash 复制代码
```
mvn failsafe:integration-test
```

`mvn site:site`

作用： 生成项目的站点文档（Site Documentation），包括项目信息、报告（如测试覆盖率、静态分析）、依赖列表等。
输出： 位于 target/site 目录，可直接用浏览器打开 index.html 查看。
示例：
bash 复制代码
```
mvn site:site
```

5. 项目信息与帮助命令

`mvn help:effective-pom`

作用： 显示项目最终生效的 POM。它将项目的 pom.xml、父 POM、超级 POM 以及 settings.xml 中的配置合并后展示。
用途： 理解 Maven 实际使用的配置，特别是当使用了继承和配置文件时。

示例：

bash 复制代码

mvn help:effective-pom
# 输出可能很长，可重定向到文件
mvn help:effective-pom > effective-pom.xml

`mvn help:effective-settings`

作用： 显示最终生效的 settings.xml 配置，合并了用户 settings.xml 和全局 settings.xml。
示例：
bash 复制代码
```
mvn help:effective-settings
```

`mvn help:describe`

作用： 描述一个插件、生命周期或目标的详细信息。

示例：

bash 复制代码

# 描述 compiler 插件
mvn help:describe -Dplugin=compiler
# 描述 clean 生命周期
mvn help:describe -DgroupId=org.apache.maven.plugins -DartifactId=maven-clean-plugin -Ddetail
# 描述 dependency:tree 目标
mvn help:describe -Dplugin=org.apache.maven.plugins:maven-dependency-plugin -Dgoal=tree

`mvn --version` 或 `mvn -v`

作用： 显示 Maven 版本、Java 版本、操作系统等信息。
示例：
bash 复制代码
```
mvn --version
```

三、常用命令组合与技巧

跳过测试： mvn clean install -Dmaven.test.skip=true
离线构建： mvn clean install -o (或 --offline)，强制 Maven 使用本地仓库，不尝试连接网络下载依赖。
更新快照依赖： mvn clean install -U (或 --update-snapshots)，强制检查远程仓库的快照版本更新。
指定 JDK 版本： 通常在 pom.xml 的 maven-compiler-plugin 中配置，也可通过环境变量 JAVA_HOME 或命令行参数 -Dmaven.compiler.source=11 -Dmaven.compiler.target=11 临时设置。
使用特定 settings.xml： mvn clean install -s /path/to/custom-settings.xml
启用调试输出： mvn clean install -X (或 --debug)，提供非常详细的日志信息，用于诊断问题。
抑制警告输出： mvn clean install -q (或 --quiet)，只输出错误信息。

四、最佳实践

使用 clean： 在进行重要构建（如部署）前，务必使用 mvn clean 或 mvn clean install，确保构建环境干净。
合理使用跳过测试： mvn test.skip 适合快速构建，但不应在 CI/CD 流水线或发布前使用。
定期分析依赖： 使用 mvn dependency:analyze 保持 pom.xml 的整洁。
理解依赖树： 当遇到类找不到（ClassNotFoundException）或方法找不到（NoSuchMethodError）等错误时，首先使用 mvn dependency:tree 检查依赖冲突。
利用有效 POM： 使用 mvn help:effective-pom 理解复杂项目的实际配置。
配置合理的生命周期绑定： 根据项目需求，在 pom.xml 中配置插件，将目标绑定到合适的生命周期阶段。

结语

Maven 的命令体系围绕其生命周期和插件机制构建。熟练掌握这些常用命令，不仅能高效地完成日常开发任务，更能深入理解 Maven 的工作原理，有效解决构建过程中遇到的各种问题。建议在实际项目中多加练习，结合官方文档（Maven Documentation）深入探索。希望本篇博客能成为您使用 Maven 的实用指南。

Maven 常用命令详解

前言

一、Maven 核心概念回顾

二、Maven 常用命令详解

1. 项目构建与生命周期命令

mvn compile

mvn test-compile

mvn test

mvn package

mvn verify

mvn install

mvn deploy

2. 清理与构建命令

mvn clean

mvn clean compile

mvn clean install

mvn clean deploy

3. 依赖管理命令

mvn dependency:resolve

mvn dependency:tree

mvn dependency:analyze

mvn dependency:copy-dependencies

4. 插件执行命令

mvn archetype:generate

mvn compiler:compile

mvn surefire:test

mvn failsafe:integration-test

mvn site:site

5. 项目信息与帮助命令

mvn help:effective-pom

mvn help:effective-settings

mvn help:describe

mvn --version 或 mvn -v

三、常用命令组合与技巧

四、最佳实践

结语

`mvn compile`

`mvn test-compile`

`mvn test`

`mvn package`

`mvn verify`

`mvn install`

`mvn deploy`

`mvn clean`

`mvn clean compile`

`mvn clean install`

`mvn clean deploy`

`mvn dependency:resolve`

`mvn dependency:tree`

`mvn dependency:analyze`

`mvn dependency:copy-dependencies`

`mvn archetype:generate`

`mvn compiler:compile`

`mvn surefire:test`

`mvn failsafe:integration-test`

`mvn site:site`

`mvn help:effective-pom`

`mvn help:effective-settings`

`mvn help:describe`

`mvn --version` 或 `mvn -v`