Maven 常用命令详解

前言

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

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

一、Maven 核心概念回顾

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

1. POM (Project Object Model): 位于 pom.xml 文件中，是 Maven 项目的配置中心，定义了项目信息、依赖、插件、构建配置等。
2. 生命周期 (Lifecycle): Maven 定义了三套独立的生命周期：default（构建项目）、clean（清理项目）、site（生成项目站点文档）。每个生命周期包含一系列按顺序执行的阶段（phase）。
3. 阶段 (Phase): 生命周期中的一个步骤。例如，default 生命周期包含 validate, compile, test, package, verify, install, deploy 等阶段。
4. 目标 (Goal): 插件（Plugin）的功能单元。一个阶段可以绑定一个或多个目标。
5. 仓库 (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 目录。
• 示例：

  mvn compile
  

mvn test-compile

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

  mvn test-compile
  

mvn test

• 作用： 运行项目的单元测试（使用 JUnit, TestNG 等框架）。
• 执行阶段： 执行到 test 阶段，包含之前的 compile 和 test-compile。
• 输出： 测试结果报告通常在 target/surefire-reports（或 target/failsafe-reports）目录下。
• 示例：

  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 目录。
• 示例：

  mvn package
  

mvn verify

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

  mvn verify
  

mvn install

• 作用： 将项目打包并安装到本地仓库（通常是 ~/.m2/repository），供本地其他项目作为依赖使用。
• 执行阶段： 执行到 install 阶段，包含 package 及之前的所有阶段。
• 输出： 包文件和 pom.xml 被复制到本地仓库的相应目录。
• 示例：

  mvn install
  

• 常用参数：
  • -Dmaven.test.skip=true：跳过测试，加快安装速度（适用于已测试过的代码）。

mvn deploy

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

  mvn deploy
  

2. 清理与构建命令

mvn clean

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

  mvn clean
  

mvn clean compile

• 组合命令： 先清理，再编译。
• 示例：

  mvn clean compile
  

mvn clean install

• 组合命令： 先清理，再完整构建并安装到本地仓库。这是开发中非常常用的命令。
• 示例：

  mvn clean install
  

mvn clean deploy

• 组合命令： 先清理，再完整构建并部署到远程仓库。
• 示例：

  mvn clean deploy
  

3. 依赖管理命令

mvn dependency:resolve

• 作用： 解析并显示项目直接声明的依赖项。
• 插件目标： dependency 插件的 resolve 目标。
• 示例：

  mvn dependency:resolve
  

mvn dependency:tree

• 作用： 以树状结构显示项目的完整依赖关系图，包括直接依赖和传递性依赖。这是解决依赖冲突的利器。
• 输出： 清晰地展示每个依赖的版本、范围（scope）以及可能的冲突（标记为 [omitted for conflict]）。
• 示例：

  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，移除不必要的依赖，明确声明必需的依赖。
• 示例：

  mvn dependency:analyze
  

mvn dependency:copy-dependencies

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

  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 项目）。
• 非交互式示例：

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

mvn compiler:compile

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

  mvn compiler:compile
  

mvn surefire:test

• 作用： 直接调用 maven-surefire-plugin 的 test 目标来运行单元测试。
• 示例：

  mvn surefire:test
  

mvn failsafe:integration-test

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

  mvn failsafe:integration-test
  

mvn site:site

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

  mvn site:site
  

5. 项目信息与帮助命令

mvn help:effective-pom

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

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

mvn help:effective-settings

• 作用： 显示最终生效的 settings.xml 配置，合并了用户 settings.xml 和全局 settings.xml。
• 示例：

  mvn help:effective-settings
  

mvn help:describe

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

  # 描述 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 版本、操作系统等信息。
• 示例：

  mvn --version
  

三、常用命令组合与技巧

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

四、最佳实践

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

结语

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