使用 Maven Wrapper 构建项目

不知道你有没有发现，如果使用 https://start.spring.io/ 或者使用 IDEA 创建一个 Spring Boot 项目，生成的文件列表中或有 mvnw 和 mvnw.cmd 两个命令文件。如果细心的同学查看隐藏目录，还会发现一个 .mvn 文件夹，那么这几个文件是干嘛的呢？这篇文章介绍它的相关知识。

├── .gitignore
├── .mvn -> 关注
│   └── wrapper
│       ├── maven-wrapper.jar -> 关注
│       └── maven-wrapper.properties -> 关注
├── HELP.md
├── mvnw    -> linux 命令文件
├── mvnw.cmd	-> windows 命令文件
├── pom.xml
└── src
    ├── main
    │   ├── java/com/wdbyte/com/springbootdemo/SpringbootdemoApplication.java
    │   └── resources
    │       ├── application.properties
    │       ├── static
    │       └── templates
    └── test/java/com/wdbyte/com/springbootdemo/SpringbootdemoApplicationTests.java

Maven Wrapper 是什么

上面提到的 mvnw 命令，它的全称是 Maven Wrapper，这是 Maven 提供的一个非常有用的工具，它会自动下载指定版本的 Maven 用于项目构建，而且开发者自由配置 Maven 版本，以此提供一致的构建体验。

mvnw 的命令使用体验和 mvn 完全一致，只需要把 mvn 命令换成 mvnw ，你可以在有 mvnw 文件的 Spring Boot 项目中进行测试。

$ ./mvnw --version
Apache Maven 3.9.5 (57804ffe001d7215b5e7bcb531cf83df38f93546)
Maven home: /Users/darcy/.m2/wrapper/dists/apache-maven-3.9.5-bin/32db9c34/apache-maven-3.9.5
Java version: 21, vendor: Oracle Corporation, runtime: /Users/darcy/develop/jdk-21.jdk/Contents/Home
Default locale: zh_CN_#Hans, platform encoding: UTF-8
OS name: "mac os x", version: "14.0", arch: "x86_64", family: "mac"

注：windows 环境请使用 mvnw.cmd

Maven Wrapper 官网：https://maven.apache.org/wrapper/

Maven Wrapper 使用场景

设想一下，如果所在的团队同时维护多个项目，不同的项目使用的 JDK 版本不相同，使用的 Maven 版本也不相同，那么为了支持多项目开发，为了构建运行效果一致，你可能需要在本地管理多个 Maven 版本，这会非常繁琐，而 Maven Wrapper 可以轻松的解决这个问题。

Maven Wrapper 的引入解决了下面几个问题：

版本一致性：通过在 mvnw 配置中指定 Maven 版本，确保所有开发人员和持续集成环境使用相同的 Maven 版本。
简化设置：新团队成员或 CI 环境不需要预先安装 Maven，直接运行 mvnw 命令就如安装了 mvn 一样，从而简化了项目的初始设置和配置。
跨平台：Wrapper 是跨平台的，无论是在 Windows 还是在 Unix-like 系统上，都可以以相同的方式执行。

使用 Maven Wrapper 的好处简单的说，可以是 “如果想要使用不同的 Maven 版本进行项目构建，只需在项目中存放一个脚本文件，而不是在本地安装不同的 Maven 版本”。

Maven Wrapper 使用方式

自动生成

如果本地机器已经安装了 Maven ，那么可以在指定项目中通过命令生成 mvnw 命令。

要在现有项目中引入 Maven Wrapper，需要执行如下命令：

mvn -N wrapper:wrapper

也可以指定 maven 版本。

mvn -N wrapper:wrapper -Dmaven=3.9.5

选项 -N 参数表示非递归，因此 Maven Wrapper 只会在项目的当前目录生成，如果项目中有子模块，那么则不会作用到子模块中。

下面我在一个空的 Spring Boot 项目中进行测试。

一个没有 mvnw 的 Spring Boot 项目：

$ ls -l -a
total 16
-rw-r--r--@   1 darcy  staff   395  4 16 21:44 .gitignore
-rw-r--r--@   1 darcy  staff  1249  4 16 21:44 pom.xml
drwxr-xr-x@   4 darcy  staff   128  4 16 21:44 src
drwxr-xr-x   11 darcy  staff   352  4 16 21:50 target

使用 mvn -N wrapper:wrapper 生成 mvnw。

$ mvn wrapper:wrapper
[INFO] Scanning for projects...
... 省略日志
[INFO] -------------------< com.wdbyte.com:springbootdemo >--------------------
[INFO] Building springbootdemo 0.0.1-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-wrapper-plugin:3.2.0:wrapper (default-cli) @ springbootdemo ---
....省略日志
[INFO] Unpacked bin type wrapper distribution org.apache.maven.wrapper:maven-wrapper-distribution:zip:bin:3.2.0
[INFO] Configuring .mvn/wrapper/maven-wrapper.properties to use Maven 3.6.3 and download from http://mvnrepo.alibaba-inc.com/mvn/repository
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  20.518 s
[INFO] Finished at: 2024-04-16T22:36:16+08:00
[INFO] ------------------------------------------------------------------------

查看目录已经生成。

$ ls -l -a
-rw-r--r--@   1 darcy  staff    395  4 16 21:44 .gitignore
drwxr-xr-x    3 darcy  staff     96  3  8  2023 .mvn
-rwxr-xr-x    1 darcy  staff  11289  3  8  2023 mvnw
-rw-r--r--    1 darcy  staff   7796  3  8  2023 mvnw.cmd
-rw-r--r--@   1 darcy  staff   1249  4 16 21:44 pom.xml
drwxr-xr-x@   4 darcy  staff    128  4 16 21:44 src
drwxr-xr-x   11 darcy  staff    352  4 16 21:50 target
# 查看版本
$ ./mvnw --version
Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
Maven home: /Users/darcy/.m2/wrapper/dists/apache-maven-3.6.3-bin/c7849ca4/apache-maven-3.6.3
Java version: 21, vendor: Oracle Corporation, runtime: /Users/darcy/develop/jdk-21.jdk/Contents/Home
Default locale: zh_CN_#Hans, platform encoding: UTF-8
OS name: "mac os x", version: "14.0", arch: "x86_64", family: "mac"

生成的文件说明：

mvnw 和 mvnw.cmd 脚本，分别用于 Unix/Linux 和 Windows 环境。
.mvn/wrapper/mavenwrapper.jar 是 Maven Wrapper 运行时所需的 Jar 文件。

.mvn/wrapper/maven-wrapper.properties 是配置文件，可以配置 Maven 版本。

然后就可以使用 mvnw 代替 mvn 构建或运行项目了。

./mvnw spring-boot:run

手动复制

通过将上面生成的文件和文件夹复制到一个新项目中，就可以拷贝一份 Maven Wrapper 。

需要拷贝的文件如下：

./
├── .mvn
│   └── wrapper
│       ├── maven-wrapper.jar
│       └── maven-wrapper.properties
├── mvnw
├── mvnw.cmd

手动配置

直接修改 maven-wrapper.properties 中的内容可以修改 Maven 版本，如修改 Maven 版本为 3.9.5，只需要修改 distributionUrl 的值为指定版本的下载地址。

$ cat .mvn/wrapper/maven-wrapper.properties
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.5/apache-maven-3.9.5-bin.zip
wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.2.0/maven-wrapper-3.2.0.jar

Maven Wrapper 总结

Maven Wrapper 是一个非常好用的工具，虽然它不是项目的一部分，但是如果把它放到项目中，不仅简化了项目的构建环境配置过程，还为项目构建减少了潜在的问题。如果你还没有在你的项目中使用 Maven Wrapper，不妨考虑尝试一下。将 Maven Wrapper 集成到项目中是一个不错的方式，这样可以跟随项目源码一起管理，可以让所有使用该项目的同学都能得到相同的构建结果。

集成步骤通常如下：

在项目根目录执行前面提到的命令添加 Maven Wrapper。
提交生成的 mvnw, mvnw.cmd 和 .mvn/ 目录到版本控制系统。
更新项目文档，指导团队成员使用 ./mvnw 替代 mvn。

参考

https://maven.apache.org/wrapper/