一、起源
- 手工创建工程需要自行补齐目录、POM、编译配置,容易遗漏编码设置与 JDK 版本,团队内每个新工程都要重复一次。
- 本地安装的 Maven 版本各不相同,同一份代码在不同机器上可能因默认插件版本差异得到不同结果。
- archetype 解决"工程骨架一致",wrapper 解决"构建工具版本一致"。
二、原理
2.1 archetype 的模板机制
- archetype 是一个特殊的构件,内部存放工程骨架:目录结构、POM 模板、示例代码与
archetype-metadata.xml。
- 生成时以模板为基础,把传入的参数替换到模板文件中,输出一个新工程。
archetype-metadata.xml 声明必须传入的属性、文件集与模块结构,是模板能否正确生成的关键文件。
- 官方提供
maven-archetype-quickstart、maven-archetype-webapp 等基础模板,团队可基于现有工程生成自定义模板。
2.2 wrapper 的作用
- Maven Wrapper 在工程内保存一份 Maven 版本声明与启动脚本,执行
./mvnw 时按声明下载对应版本的 Maven 并运行。
- 使用者无需预装对应版本的 Maven,CI 也不需要额外配置,构建工具版本随代码一起纳入版本控制。
- wrapper 只固定 Maven 版本,不固定 JDK 版本;JDK 仍需通过环境变量或 CI 镜像保证一致。
2.3 两者的适用场景
| 手段 | 解决的问题 | 使用时机 |
| archetype | 目录与配置骨架统一 | 新工程创建阶段 |
| wrapper | 构建工具版本统一 | 工程创建后立即加入,长期保留 |
三、实现
3.1 使用 archetype 生成工程
mvn archetype:generate \
-DarchetypeGroupId=org.apache.maven.archetypes \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DarchetypeVersion=1.4 \
-DgroupId=com.example \
-DartifactId=demo \
-Dversion=1.0.0-SNAPSHOT \
-Dpackage=com.example.demo \
-DinteractiveMode=false
-DarchetypeGroupId、-DarchetypeArtifactId、-DarchetypeVersion 三项定位模板构件。
-DgroupId、-DartifactId、-Dversion、-Dpackage 是新工程的坐标与包名。
-DinteractiveMode=false 表示非交互执行,缺少必填参数时直接报错,适合脚本与 CI。
- 生成后进入目录执行
mvn clean package 验证骨架可用,环境检查见 Maven 入门:定位、环境与项目结构。
3.2 自定义 archetype
# 在现有工程目录下生成模板
mvn archetype:create-from-project
# 安装模板到本地仓库
cd target/generated-sources/archetype
mvn install
- 生成后模板的坐标由原工程的
groupId、artifactId 派生,可在 target/generated-sources/archetype/pom.xml 中确认。
- 模板中的模块名、包名等可变部分会被替换为占位符,使用前应检查
archetype-metadata.xml 中的 requiredProperties 是否完整。
- 发布到私服后团队成员可直接按坐标使用,无需每人保存一份模板目录。
3.3 生成 Maven Wrapper
# 在工程根目录执行,指定 Maven 版本
mvn -N wrapper:wrapper -Dmaven=3.9.9
生成的文件:
| 文件 | 作用 |
mvnw | Linux 与 macOS 启动脚本 |
mvnw.cmd | Windows 启动脚本 |
.mvn/wrapper/maven-wrapper.properties | 声明 Maven 版本与下载地址 |
.mvn/wrapper/maven-wrapper.jar | 引导下载与启动的组件 |
- 生成后应提交以上文件,
.mvn/wrapper 目录不要加入忽略规则。
- 首次执行时会下载对应版本的 Maven 到用户目录缓存,后续复用。
3.4 在 CI 中使用
./mvnw -B -U clean verify
- 使用 wrapper 后,CI 镜像只需提供 JDK,不需要预装指定版本的 Maven。
- Windows 环境使用
mvnw.cmd,脚本调用方式与 mvn 一致,参数含义见 Maven 常用命令与构建参数。
- 内网环境无法访问默认下载地址时,可在
maven-wrapper.properties 中改为内部镜像地址。
四、常见问题
| 现象 | 常见原因 | 处理方式 |
| 模板下载很慢或失败 | 中央仓库访问受限,未配置镜像 | 配置镜像,方法见 Maven settings.xml 配置详解 |
| 生成失败并提示缺少属性 | archetype-metadata.xml 声明了必填属性但未传入 | 补齐 -D 参数,或改交互模式逐项输入 |
| 生成后的 POM 坐标不对 | 模板中的 requiredProperties 与实际参数不匹配 | 检查模板元数据,重新安装模板 |
./mvnw 无执行权限 | Linux 或 macOS 下文件权限丢失 | 执行 chmod +x mvnw 后提交权限变更 |
| wrapper 下载失败 | 内网无法访问声明中的 distributionUrl | 改为内部镜像地址,或改用手动安装的 Maven |
mvnw.cmd 被执行策略拦截 | Windows PowerShell 脚本策略限制 | 使用 cmd /c mvnw.cmd,或调整执行策略 |
五、总结
- archetype 统一工程骨架,核心参数是三组模板坐标与四个工程坐标。
- 自定义模板通过
create-from-project 生成,安装或发布后团队可直接复用。
- wrapper 把 Maven 版本写入版本库,使用
mvnw 代替 mvn 即可获得一致的构建工具版本。
- wrapper 只固定 Maven 版本,JDK 版本仍需在环境或 CI 镜像中统一。