昨天的Spring Boot项目用一条命令就能编译、测试和打包。今天把这条命令拆开:Maven依据pom.xml组织构建,并由插件执行具体工作。理解这层分工,才能看懂“IDE里能运行,命令行却失败”究竟是哪一步出了问题。
本文用Maven3.9.9、JDK21和一个完整的小项目讲清坐标、目录、依赖、生命周期、插件与排错。我们让测试真正守住打包入口,再观察产物里到底有什么。
一、先认识项目的三个坐标
一个制品通常用groupId、artifactId、version识别。例如demo:build-lab:1.0.0中,demo是组织命名空间,build-lab是制品名,1.0.0是版本。默认packaging是jar;它决定默认绑定哪些构建任务。
POM并非只是一张下载清单。它同时描述项目身份、依赖和构建配置。dependencies供项目代码使用,build/plugins参与构建过程。JUnit是测试依赖;编译器插件负责调用编译器,Surefire插件运行单元测试,JAR插件打包。
二、建立一个可验证的最小项目
目录如下,测试文件名称以Test结尾,能被本例Surefire默认规则发现:
1build-lab/ 2├─ pom.xml 3└─ src/ 4 ├─ main/java/demo/App.java 5 └─ test/java/demo/AppTest.java 6
完整pom.xml:
1<project xmlns="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"> 2 <modelVersion>4.0.0</modelVersion> 3 <groupId>demo</groupId><artifactId>build-lab</artifactId><version>1.0.0</version> 4 <properties> 5 <maven.compiler.release>21</maven.compiler.release> 6 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> 7 </properties> 8 <dependencies> 9 <dependency> 10 <groupId>org.junit.jupiter</groupId><artifactId>junit-jupiter</artifactId> 11 <version>5.11.4</version><scope>test</scope> 12 </dependency> 13 </dependencies> 14 <build><plugins> 15 <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.13.0</version></plugin> 16 <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.2</version></plugin> 17 <plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-jar-plugin</artifactId><version>3.4.2</version> 18 <configuration><archive><manifest><mainClass>demo.App</mainClass></manifest></archive></configuration> 19 </plugin> 20 </plugins></build> 21</project> 22
release设为21,要求编译环境支持该目标,并约束使用的Java平台API。它不负责替你安装JDK。先运行mvn -v,检查Maven实际使用的Java版本与Java home;IDE项目SDK和终端JAVA_HOME可能不同。
显式固定插件版本,使团队采用相同的插件行为。JUnit只在测试阶段需要,所以配置test作用域。主程序不依赖它,运行时也不需要携带它。
App.java:
1package demo; 2 3public class App { 4 public static String label(String title) { 5 if (title == null || title.isBlank()) { 6 throw new IllegalArgumentException("title is blank"); 7 } 8 return "TODO: " + title.strip(); 9 } 10 public static void main(String[] args) { 11 System.out.println(label(args.length == 0 ? "learn Maven" : args[0])); 12 } 13} 14
AppTest.java:
1package demo; 2 3import org.junit.jupiter.api.Test; 4import static org.junit.jupiter.api.Assertions.*; 5 6class AppTest { 7 @Test void trimsTitle() { 8 assertEquals("TODO: learn Maven", App.label(" learn Maven ")); 9 } 10 @Test void rejectsBlank() { 11 assertThrows(IllegalArgumentException.class, () -> App.label(" ")); 12 } 13 @Test void rejectsNull() { 14 assertThrows(IllegalArgumentException.class, () -> App.label(null)); 15 } 16} 17
测试覆盖正常标题、空白和null三条路径。这个例子虽小,失败条件却明确:如果以后删除输入检查,测试应当阻止构建继续成功。
三、阶段与目标如何配合
运行mvn verify时,Maven沿default生命周期执行到verify;不是只执行一个叫verify的动作。主要阶段可以这样读:
| 阶段 | 关心的结果 |
|---|---|
| compile | 主源码编译成功 |
| test | 单元测试通过 |
| package | 生成JAR等制品 |
| verify | 执行已绑定的后续质量检查 |
| install | 把制品放入本地仓库,供其他本地项目引用 |
| deploy | 将制品发布到远程制品仓库 |
阶段规定顺序,插件目标负责动作。 例如compiler:compile执行编译,surefire:test执行测试。直接调用插件目标不等于自动执行它之前的全部生命周期阶段。verify是否执行集成测试或静态检查,取决于项目是否配置了对应插件和绑定,阶段名称本身不会自动生成这些检查。生命周期说明
clean属于另一条生命周期。mvn clean verify先清理再构建;单独mvn verify不会自动清空旧产物。日常增量构建可以不clean,排除遗留文件或做交付验收时使用clean更直接。

四、运行、检查产物,再故意让测试失败
在pom.xml所在目录执行:
1mvn -v 2mvn clean verify 3java -jar target/build-lab-1.0.0.jar 4jar tf target/build-lab-1.0.0.jar 5
本次实际验收:3个测试全部通过,JAR启动输出TODO: learn Maven;故意改错断言后构建失败且未生成JAR,恢复后重新构建成功。JAR目录中包含App.class,不包含测试类和JUnit。
本例构建通过后,测试报告在target/surefire-reports,主类在target/classes,JAR在target/build-lab-1.0.0.jar。我们配置Main-Class清单,因此可以用java -jar启动。
普通JAR插件不会自动把所有第三方依赖打进JAR。这里主程序只用JDK,所以能独立运行。若加入运行时库,需要明确classpath、分发依赖,或选择适合项目的打包插件;Spring Boot可执行包也有自己的打包方式。
将测试期望临时改为错误字符串,再执行mvn clean verify:测试阶段失败,命令返回非零退出码,后续打包不会执行。恢复期望后再次构建。通过一次可控失败,可以确认CI执行的确实是测试,而非只编译源码或跳过测试。
不要把跳过测试当作修复。 -DskipTests通常跳过测试执行但仍编译测试代码;maven.test.skip会被相关插件用于跳过测试编译和执行。交付流水线应保留真实验收步骤。
五、依赖怎样进入classpath
| 作用域 | 主要用途 |
|---|---|
| compile | 默认值,主编译与运行都需要 |
| provided | 编译需要,运行环境提供 |
| runtime | 主编译不需要,运行需要 |
| test | 测试编译和执行需要 |
传递依赖把依赖的依赖带进解析图,实际传播还受作用域、optional和exclusions影响。同一个库出现多个版本时,Maven通常选择依赖路径更近的定义;同深度时先声明者优先。不要把“声明过一个新版本”理解为依赖图里所有关联库都自动升级。依赖机制
用依赖树找来源,比直接往pom.xml反复加版本更有效:
1mvn dependency:tree 2mvn help:effective-pom 3
dependencyManagement集中管理依赖版本和相关属性,本身不等于引入依赖。子项目仍在dependencies声明需要的库。pluginManagement也用于管理插件配置,是否执行仍要看插件实际声明和生命周期绑定;不要把管理区当作执行清单。
六、仓库、重复构建与排错顺序
本地仓库存放已下载依赖和本地install产物,远程仓库提供可下载制品。install成功只说明当前机器的其他项目可以解析这个版本;让同事和CI使用,应通过团队远程制品仓库发布,不能依靠复制个人仓库目录。
项目配置提交到版本库,仓库凭据放在受控的settings.xml或CI凭据系统中。固定依赖与插件版本、使用Maven Wrapper统一Maven版本,再统一JDK环境,才能减少“同一份代码,不同机器构建不同”的情况。SNAPSHOT内容可以变化,缓存与更新策略也会影响解析结果。
遇到失败按日志定位:先看mvn -v确认环境,再看第一个失败插件;编译错误查源码与release,测试错误查surefire-reports,解析失败查坐标、网络和仓库配置。只有明确是某个缓存制品损坏,才针对它处理;删除整个本地仓库会造成大量无关重新下载。
七、🧠 思维导图
Maven构建
POM与坐标
生命周期
依赖
验收
项目与插件配置
compile test package verify
install与deploy
作用域与版本仲裁
测试失败阻止打包
依赖树与有效POM
八、总结
总结要点
POM把构建要求写成共享约定。 坐标说明项目是谁,依赖说明代码需要什么,插件说明构建如何执行。
生命周期让步骤有序衔接。 选择需要到达的阶段,让测试与检查成为产物生成的前置条件,再用一次失败实验验证它们真的生效。
排错要看实际环境和解析结果。 mvn -v、依赖树、有效POM和测试报告,比反复点IDE重试更能解释问题。
下一篇继续工具篇,使用Gradle重建同一个小项目,对比任务图、依赖配置与Wrapper。
👉 如果你觉得这篇文章对你有所帮助,欢迎点赞、收藏、分享!😊
《Java工具篇之Maven:从pom.xml到测试通过的JAR》 是转载文章,点击查看原文。