一、起源

  • 手工创建工程需要自行补齐目录、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,或调整执行策略

五、总结

  1. archetype 统一工程骨架,核心参数是三组模板坐标与四个工程坐标。
  2. 自定义模板通过 create-from-project 生成,安装或发布后团队可直接复用。
  3. wrapper 把 Maven 版本写入版本库,使用 mvnw 代替 mvn 即可获得一致的构建工具版本。
  4. wrapper 只固定 Maven 版本,JDK 版本仍需在环境或 CI 镜像中统一。