一、起源
- 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 集成测试 | 只跳过集成测试 |
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 总是更快:插件未声明线程安全或模块间存在隐式依赖时,并行可能放大问题。
五、总结
- 指定阶段即执行该阶段之前的全部阶段,三个生命周期互相独立。
package 只产出文件,install 写入本地仓库,deploy 推送远程仓库。
-pl、-am、-amd 控制模块范围,-o、-U 控制仓库行为,跳过测试需区分三个开关。
- 排障优先使用
help:effective-pom、help:effective-settings、dependency:tree,必要时加 -X -e。