Maven Wrapper 使用指南

Maven Wrapper (mvnw) 是一个让项目自包含 Maven 构建工具的机制，确保所有开发者使用相同的 Maven 版本。

什么是 Maven Wrapper？

Maven Wrapper 是由 mvnw（Unix/Linux/macOS）或 mvnw.cmd（Windows）脚本组成的项目自包含脚本，它包含：

Maven 分发脚本 - 自动下载并运行指定版本的 Maven
配置文件 - .mvn/wrapper/maven-wrapper.properties 定义 Maven 版本和源
项目独立性 - 开发者无需安装 Maven 即可构建项目

为什么使用 Maven Wrapper？

问题	不使用 Maven Wrapper	使用 Maven Wrapper
版本不一致	不同开发者有不同 Maven 版本	所有开发者自动使用相同版本
环境配置	需要手动安装 Maven	自动下载，无需手动配置
CI/CD 兼容性	服务器 Maven 版本可能不同	统一构建环境
新成员入门	需要先安装配置 Maven	克隆项目即可构建

项目中当前配置

本项目的 Maven Wrapper 配置：

复制代码

Maven 版本: 3.9.11
下载源: https://repo.maven.apache.org/maven2
配置文件: .mvn/wrapper/maven-wrapper.properties

使用方法

基本用法

使用 ./mvnw 替代 mvn 命令：

bash 复制代码

# 编译项目
./mvnw clean compile

# 运行应用
./mvnw spring-boot:run

# 运行测试
./mvnw test

# 打包
./mvnw clean package

首次使用

首次运行 ./mvnw 时，它会：

检查本地 Maven 缓存（~/.m2/wrapper/）
如果不存在，从配置的源下载 Maven
使用下载的 Maven 执行构建

示例输出：

复制代码

[INFO] Downloaded from https://repo.maven.apache.org/maven2/.../maven-3.9.11-bin.zip
[INFO] Unpacked maven...

Maven Wrapper 与环境变量

重要：Maven Wrapper 仍受环境变量影响

Maven Wrapper 虽然自包含 Maven，但它运行的 Java 版本仍由系统环境决定：

bash 复制代码

# 即使使用 ./mvnw，如果 Java 环境错误，仍会失败
./mvnw clean compile
# 错误：Maven 用 Java 21 运行，但项目需要 Java 8

正确的使用流程

步骤 1：设置正确的 Java 环境

bash 复制代码

# 设置 JAVA_HOME
export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)

# 设置 PATH（确保 Maven 进程用正确 Java 启动）
export PATH=$JAVA_HOME/bin:$PATH

步骤 2：使用 Maven Wrapper 构建

bash 复制代码

# 验证环境
java -version      # 应显示 Java 8
./mvnw -v        # 应显示 Java version 1.8.x

# 构建项目
./mvnw clean compile

验证示例：

bash 复制代码

$ export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) && \
  export PATH=$JAVA_HOME/bin:$PATH && \
  ./mvnw -v | grep "Java version"

# 输出：Java version: 1.8.0_462, vendor: Amazon.com Inc.
# 成功！

Maven Wrapper 文件说明

生成的文件结构

复制代码

项目根目录/
├── mvnw                    # Unix/Linux/macOS 执行脚本
├── mvnw.cmd                # Windows 批处理脚本
└── .mvn/                   # Maven Wrapper 配置目录
    └── wrapper/
        └── maven-wrapper.properties

关键配置文件：`.mvn/wrapper/maven-wrapper.properties`

复制代码

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

配置说明：

wrapperVersion - Wrapper 脚本版本
distributionType - 分发类型（only-script 表示仅脚本）
distributionUrl - Maven 下载源

Maven 缓存位置

下载的 Maven 存储在：

macOS/Linux : ~/.m2/wrapper/dists/
Windows : %USERPROFILE%\.m2\wrapper\dists\

高级用法

指定不同的 Maven 版本

临时使用不同 Maven 版本构建（不会修改项目配置）：

bash 复制代码

# 使用 Maven 3.8.1 构建（而非默认 3.9.11）
./mvnw -Dmaven.version=3.8.1 clean compile

跳过下载

如果网络问题导致下载失败，可以：

手动下载 Maven 到 .m2/wrapper/dists/
或使用系统 Maven：mvn（如果已正确安装）

清理 Wrapper 缓存

bash 复制代码

# 清理下载的 Maven
rm -rf ~/.m2/wrapper/

# 下次运行时会重新下载

与 CI/CD 集成

GitHub Actions

yaml 复制代码

name: Build with Maven Wrapper

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 8
        uses: actions/setup-java@v3
        with:
          java-version: '8'
          distribution: 'temurin'

      - name: Build with Maven Wrapper
        run: ./mvnw clean package

**注意：**不需要 actions/setup-maven，因为 Maven Wrapper 自包含 Maven

GitLab CI

yaml 复制代码

build:
  image: maven:3.9.11-openjdk-8
  script:
    - mvn clean package
    # 或者使用项目自带的 Wrapper
    - ./mvnw clean package

常见问题

Q1: Maven Wrapper 下载失败

**问题：**网络问题或镜像配置导致下载 Maven 失败

解决方法：

配置 Maven 镜像（国内推荐）

bash 复制代码

# 设置 Maven 镜像
export MAVEN_OPTS="-Dmaven.repo.local=~/.m2/repository"

使用系统 Maven

bash 复制代码

# 如果本地已安装正确 Maven 版本
mvn clean compile  # 跳过 Wrapper

手动下载 Maven

bash 复制代码

# 下载到缓存目录
wget https://archive.apache.org/dist/maven/maven-3/3.9.11/binaries/apache-maven-3.9.11-bin.tar.gz
tar -xzf apache-maven-3.9.11-bin.tar.gz -C ~/.m2/wrapper/dists/

Q2: mvnw 没有执行权限

问题：

复制代码

bash: ./mvnw: Permission denied

解决方法：

bash 复制代码

# 添加执行权限
chmod +x mvnw

# 或者使用 bash 执行
bash mvnw clean compile

Q3: Windows 上 mvnw.cmd 找不到 Java

**问题：**Windows 环境变量 JAVA_HOME 未设置

解决方法：

cmd 复制代码

REM 设置 JAVA_HOME
set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_462

REM 运行
mvnw.cmd clean compile

Q4: 如何更新项目中的 Maven 版本？

方法 1：重新生成 Wrapper

bash 复制代码

# 先删除旧的
rm -rf .mvn mvnw mvnw.cmd

# 重新生成
mvn wrapper:wrapper

方法 2：手动编辑配置文件

bash 复制代码

# 编辑 .mvn/wrapper/maven-wrapper.properties
# 修改 distributionUrl 指向新版本

最佳实践

1.1. 将 mvnw 提交到版本控制

bash 复制代码

# 提交所有 Wrapper 相关的文件
git add mvnw mvnw.cmd .mvn/
git commit -m "Add Maven Wrapper"

# .mvn/ 目录需要被忽略其内部下载的内容
echo ".mvn/wrapper/dists/" >> .gitignore

2. 更新文档

在 README.md 中添加使用说明：

markdown 复制代码

## 构建项目

本项目使用 Maven Wrapper，无需预先安装 Maven。

```bash
# 设置 Java 8 环境（必需）
export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)
export PATH=$JAVA_HOME/bin:$PATH

# 使用 Maven Wrapper 构建
./mvnw clean install

复制代码

### 3. 统一构建方式

- 开发环境：使用 `./mvnw`
- CI/CD：使用 `./mvnw`
- 生产构建：使用 `./mvnw`

保持一致性，避免不同环境使用不同 Maven 版本。

---

## 快速参考

| 命令 | 说明 |
|------|------|
| `./mvnw -v` | 查看 Maven 版本和 Java 环境 |
| `./mvnw clean compile` | 清理并编译 |
| `./mvnw clean package` | 打包项目 |
| `./mvnw spring-boot:run` | 运行 Spring Boot 应用 |
| `./mvnw test` | 运行测试 |
| `./mvnw dependency:tree` | 查看依赖树 |

---

## 相关文档

- [Maven 官方文档 - Maven Wrapper](https://maven.apache.org/wrapper/)

Maven Wrapper 使用指南