一、起源

  • IDE 的 Maven 按钮屏蔽了参数与阶段细节,出现"本地能打包、CI 不能打包"时,只能回到命令行复现。
  • CI 流水线、容器构建、发布脚本都直接调用 mvn,命令行的行为就是构建的最终行为。
  • 命令行参数数量多且含义相近,混淆 -o 与 -U、skipTests 与 maven.test.skip 会直接改变构建结果。

二、原理

2.1 阶段是累积执行的

  • 指定某个阶段时,Maven 会依次执行同一生命周期中该阶段之前的所有阶段。执行 mvn package 会先完成编译与测试,而不是只打包。
  • 三个生命周期互相独立:clean 只负责清理,default 负责构建,site 负责站点生成。mvn clean package 是依次执行两个生命周期。
  • 阶段本身不做事,实际动作由绑定在该阶段的插件目标完成,绑定关系见 Maven 生命周期与插件绑定。

2.2 参数分类

类别 参数 作用
生命周期 clean、compile、test、package、verify、install、deploy 指定执行到哪个阶段
模块选择 -pl、-am、-amd 只构建部分模块及其依赖或下游
仓库与更新 -o、-U 离线构建、强制更新快照与元数据
测试控制 -DskipTests、-Dmaven.test.skip=true、-DskipITs 跳过测试的不同层次
环境切换 -P、-D 激活 profile、覆盖属性
性能与日志 -T、-q、-B、-X、-e 并行、静默、批处理、调试、异常栈

三、实现

3.1 常用生命周期命令

命令 实际动作 产物去向
mvn clean 删除 target 无
mvn compile 编译主源码 target/classes
mvn test 编译并运行单元测试 target/test-classes、测试报告
mvn package 编译、测试、打包 target 下的 jar 或 war
mvn verify 在 package 之后执行集成测试与校验 测试报告、校验结果
mvn install 在 verify 之后安装到本地仓库 本地仓库
mvn deploy 在 install 之后推送到远程仓库 私服或远程仓库
  • package 不写入本地仓库,其他工程或独立构建无法解析到该构件。
  • install 与 deploy 都包含前面的全部阶段,跳过测试时需要使用测试开关,而不是省略阶段。
  • 只想执行某个插件目标而不走生命周期时,可直接调用,例如 mvn dependency:tree。

3.2 模块选择

# 只构建指定模块,同时构建它依赖的模块
mvn -pl example-web -am clean package

# 只构建指定模块,同时构建依赖它的下游模块
mvn -pl example-common -amd clean package
  • -pl 支持逗号分隔多个模块,路径相对于聚合 POM。
  • -am 向上补齐依赖模块,-amd 向下补齐依赖该模块的模块。
  • 多模块结构见 Maven 多模块工程:聚合与继承。

3.3 仓库与更新

参数 行为 适用场景
-o 强制离线,只使用本地仓库 网络受限、确认本地构件完整
-U 强制检查远程仓库的 SNAPSHOT 与元数据更新 二方库快照更新后本地仍是旧版本
-Dmaven.repo.local=路径 临时指定本地仓库 多套环境隔离、CI 缓存目录
  • -U 不会重新下载已存在的 Release 构件,Release 本身不可变。
  • -o 缺少构件时直接失败,不会回退到在线模式。

3.4 测试跳过开关

参数 是否编译测试代码 是否执行测试 适用场景
-DskipTests 是 否 需要保留测试编译结果,快速打包
-Dmaven.test.skip=true 否 否 测试代码无法编译或完全不需要
-DskipITs 是 跳过 failsafe 集成测试 只跳过集成测试
  • -DskipTests 只跳过执行,测试代码仍会编译;测试代码存在编译错误时依然构建失败。
  • -Dmaven.test.skip=true 同时跳过编译与执行,产物中不含测试类。
  • 集成测试的插件分工见 Maven 测试插件:surefire 与 failsafe。

3.5 profile 与属性

# 激活指定 profile
mvn -Pprod clean package

# 覆盖 POM 中的属性
mvn clean package -Dspring.boot.version=3.2.5

# 多 profile 同时激活
mvn -Pdev,build-native clean package
  • -P 只激活 POM 或 settings 中已定义的 profile,未定义的名称会被忽略并给出提示。
  • -D 设置的是用户属性,可覆盖 POM <properties> 中的同名项,但不能覆盖 ${project.version} 等模型属性。

3.6 并行与日志

参数 作用 注意事项
-T 4 或 -T 1C 多线程构建,1C 表示每核一个线程 插件需线程安全;有模块间隐式依赖时结果不稳定
-q 只输出错误信息 排障时不适用
-B 批处理模式,禁用交互与彩色输出 CI 环境建议始终带上
-X 调试输出,包含仓库请求与插件参数 输出量大,通常配合重定向到文件
-e 输出完整异常栈 定位插件内部异常

3.7 诊断命令

命令 用途
mvn help:effective-pom 查看父子 POM 合并后的最终配置
mvn help:effective-settings 查看合并后的 settings,确认镜像与认证
mvn help:evaluate -Dexpression=project.version -q -DforceStdout 输出单个表达式的结果
mvn dependency:tree 查看依赖树与冲突,判读方法见 Maven 依赖管理机制
mvn dependency:analyze 找出使用但未声明、声明但未使用的依赖
mvn help:describe -Dplugin=compiler 查看插件目标与参数

3.8 CI 常用组合

mvn -B -U -T 1C clean verify
  • -B 保证日志可读且不等待交互,-U 获取最新的 SNAPSHOT,-T 1C 提升多模块构建速度,verify 覆盖单元测试、集成测试与校验。
  • 发布到私服时替换为 deploy,并确保 settings 中已配置认证。
  • 部署到容器镜像时,可先 package 再调用打包插件,避免重复执行测试。

四、常见误区

  • 认为 mvn package 后其他工程可以直接引用:只有 install 才进入本地仓库。
  • 认为 -DskipTests 会跳过测试编译:测试代码仍参与编译,编译错误依旧阻断构建。
  • 认为 -o 是"优先离线":它是强制离线,缺件直接失败。
  • 认为 -U 可以更新 Release 构件:Release 不可变,更新的是 SNAPSHOT 与元数据。
  • 认为 -T 总是更快:插件未声明线程安全或模块间存在隐式依赖时,并行可能放大问题。

五、总结

  1. 指定阶段即执行该阶段之前的全部阶段,三个生命周期互相独立。
  2. package 只产出文件,install 写入本地仓库,deploy 推送远程仓库。
  3. -pl、-am、-amd 控制模块范围,-o、-U 控制仓库行为,跳过测试需区分三个开关。
  4. 排障优先使用 help:effective-pom、help:effective-settings、dependency:tree,必要时加 -X -e。