构建与依赖 / 系统课时

使用 Maven Wrapper 固定构建环境

使用 Maven Wrapper 固定构建环境

Maven Wrapper 把“用哪个 Maven”写进项目并随代码提交,开发机和 CI 都从 mvnw 进入构建。下面以 Maven 3.9.9 为例生成 Wrapper、检查提交内容,并用可重复的命令验证版本是否真的被固定。

学习目标

  • 生成并提交 Maven Wrapper,固定 Maven 3.9.9。
  • 让本地与 CI 统一通过 Wrapper 执行 verify。
  • 能定位 Wrapper 下载失败、版本未切换和脚本权限问题。

生成 Wrapper 并锁定 Maven 版本

先在项目根目录用现有 Maven 运行一次 Wrapper 插件。下面命令适用于 Maven Wrapper Plugin 3.3.4;-N 表示只在当前项目执行,不递归进入子模块。

bash
mvn -N org.apache.maven.plugins:maven-wrapper-plugin:3.3.4:wrapper -Dmaven=3.9.9

预期输出的关键结果如下,下载日志会因本地缓存状态不同而变化。

text
[INFO] BUILD SUCCESS

生成后应至少看到 mvnw、mvnw.cmd 和 .mvn/wrapper/maven-wrapper.properties。Wrapper 3.x 的 only-script 模式通常不需要提交 maven-wrapper.jar;如果团队显式选择 bin 或 source 类型,生成文件会不同,应按实际模式整体提交。

检查版本来源与执行链

真正决定下载哪个 Maven 的是 .mvn/wrapper/maven-wrapper.properties 中的 distributionUrl。以 Maven 3.9.9 为例,关键配置应指向对应二进制发行包。

text
wrapperVersion=3.3.4
distributionType=only-script
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip

配置生效后,不管机器全局安装的是 Maven 3.8.x 还是 3.9.x,项目构建都应从 Wrapper 脚本读取该配置,再下载并启动 3.9.9。首次执行需要联网,后续通常会复用用户目录中的 Wrapper 缓存。

Maven Wrapper 固定构建环境的执行链

用 Wrapper 自检版本,不要再用系统里的 mvn -v。

bash
./mvnw -v

预期输出至少应包含固定版本;<PATH>、Java 版本和操作系统信息会随机器变化。

text
Apache Maven 3.9.9
Maven home: <PATH>
Java version: <ID>

Windows 可执行 mvnw.cmd -v,判断标准仍是首行显示 Apache Maven 3.9.9。

让 CI 只调用 Wrapper

CI 脚本中不要先安装一个“最新版 Maven”再运行 mvn,否则项目里的 Wrapper 形同虚设。Linux 构建节点可以直接把验证阶段写成:

bash
chmod +x mvnw
./mvnw -B -V verify

预期结果是在日志开头打印 Maven 与 Java 版本,并最终通过验证。

text
Apache Maven 3.9.9
[INFO] BUILD SUCCESS

-B 使用批处理模式,适合无交互 CI;-V 会在构建开始时显示 Maven 和 Java 版本,便于排查环境漂移。仓库中应提交 Wrapper 脚本与 .mvn/wrapper 配置,并确保 Unix 可执行位被 Git 记录。

处理三个常见失败

如果执行 ./mvnw 提示 Permission denied,先运行 chmod +x mvnw,再用 git update-index --chmod=+x mvnw 固化权限。两条命令成功时通常不输出内容,随后 ./mvnw -v 应能正常显示固定的 Maven 版本。

如果日志仍显示错误的 Maven 版本,先查看 .mvn/wrapper/maven-wrapper.properties 的 distributionUrl,再确认 CI 实际调用的是 ./mvnw 而不是 mvn。版本切换后再次运行 ./mvnw -v,首行必须与目标版本一致。

如果首次下载超时或被企业代理拦截,应让 Wrapper 访问组织允许的 Maven 仓库镜像,而不是删除 Wrapper。修改后用一台无本地 Maven 缓存的新环境执行 ./mvnw -B -V verify,能下载指定版本并得到 BUILD SUCCESS 才算真正完成环境固定。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Maven Wrapper 固定构建环境

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通