什么是 Gradle Wrapper？如何生成和使用它？ - 面试题

Gradle Wrapper 是 Gradle 的一个重要特性，它允许项目使用特定版本的 Gradle 进行构建，而无需在开发者的机器上预先安装 Gradle。以下是 Gradle Wrapper 的详细说明：

Gradle Wrapper 简介

Gradle Wrapper 是一个脚本和一组 JAR 文件，用于下载和运行特定版本的 Gradle。它确保所有开发者和 CI/CD 系统使用相同版本的 Gradle 进行构建。

Wrapper 文件结构

shell
project/
├── gradle/
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
└── build.gradle

文件说明

gradlew：Unix/Linux/macOS 上的可执行脚本
gradlew.bat：Windows 上的批处理脚本
gradle/wrapper/gradle-wrapper.jar：Wrapper JAR 文件
gradle/wrapper/gradle-wrapper.properties：Wrapper 配置文件

生成 Wrapper

使用 Gradle 命令生成

bash
# 生成 Wrapper（使用当前 Gradle 版本）
gradle wrapper

# 指定 Gradle 版本
gradle wrapper --gradle-version 8.0

# 使用发布版本
gradle wrapper --gradle-distribution-url https://services.gradle.org/distributions/gradle-8.0-bin.zip

在 build.gradle 中配置

groovy
// build.gradle
wrapper {
    gradleVersion = '8.0'
    distributionType = Wrapper.DistributionType.BIN
    distributionPath = wrapperPath
    archivePath = wrapperPath
}

Wrapper 配置

gradle-wrapper.properties

properties
# Gradle 分发下载 URL
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip

# 分发基础 URL（可选）
distributionBase=GRADLE_USER_HOME

# 分发路径（可选）
distributionPath=wrapper/dists

# Zip 缓存基础 URL（可选）
zipStoreBase=GRADLE_USER_HOME

# Zip 缓存路径（可选）
zipStorePath=wrapper/dists

分发类型

Gradle Wrapper 提供三种分发类型：

bin：仅包含二进制文件，体积小，下载快

properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip

all：包含二进制文件和源代码，体积大，适合需要查看源代码的情况
```
properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-all.zip
```

only：仅包含源代码（不常用）

properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-src.zip

使用 Wrapper

基本使用

bash
# 使用 Wrapper 执行 Gradle 任务
./gradlew build

# Windows 上使用
gradlew.bat build

# 查看可用任务
./gradlew tasks

# 清理项目
./gradlew clean

指定 JVM 选项

bash
# 设置 JVM 内存
./gradlew build -Dorg.gradle.jvmargs="-Xmx2048m -XX:MaxMetaspaceSize=512m"

# 使用特定的 Java 版本
JAVA_HOME=/path/to/java17 ./gradlew build

传递项目属性

bash
# 传递项目属性
./gradlew build -Pprofile=production

# 传递系统属性
./gradlew build -Dspring.profiles.active=production

自定义 Wrapper

自定义分发位置

groovy
// build.gradle
wrapper {
    gradleVersion = '8.0'
    distributionType = Wrapper.DistributionType.BIN
    
    // 使用自定义仓库
    distributionUrl = 'https://my-company.com/gradle/gradle-8.0-bin.zip'
}

使用本地 Gradle 分发

groovy
// gradle-wrapper.properties
distributionUrl=file\:///path/to/local/gradle-8.0-bin.zip

配置网络代理

bash
# 设置代理
./gradlew build -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080

# 在 gradle.properties 中配置
# gradle.properties
systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080

版本管理

更新 Wrapper 版本

bash
# 更新到最新版本
./gradlew wrapper --gradle-version=8.1

# 更新到特定版本
./gradlew wrapper --gradle-version=8.0.2

# 更新到发行候选版本
./gradlew wrapper --gradle-version=8.2-rc-1

检查当前版本

bash
# 查看 Wrapper 使用的 Gradle 版本
./gradlew --version

# 查看 Wrapper 配置
cat gradle/wrapper/gradle-wrapper.properties

最佳实践

1. 提交 Wrapper 文件到版本控制

bash
# 提交以下文件到 Git
git add gradlew gradlew.bat
git add gradle/wrapper/gradle-wrapper.jar
git add gradle/wrapper/gradle-wrapper.properties

# 不要提交下载的 Gradle 分发
echo "gradle/wrapper/dists/" >> .gitignore

2. 使用固定版本

groovy
// build.gradle
wrapper {
    gradleVersion = '8.0'  // 使用固定版本
    distributionType = Wrapper.DistributionType.BIN
}

3. 在 CI/CD 中使用 Wrapper

yaml
# GitHub Actions 示例
- name: Build with Gradle
  run: ./gradlew build

# Jenkins Pipeline 示例
sh './gradlew build'

# GitLab CI 示例
script:
  - ./gradlew build

4. 优化下载速度

groovy
// 使用国内镜像
wrapper {
    gradleVersion = '8.0'
    distributionUrl = 'https://mirrors.cloud.tencent.com/gradle/gradle-8.0-bin.zip'
}

故障排除

1. Wrapper 脚本没有执行权限

bash
# 添加执行权限
chmod +x gradlew

2. 下载失败

bash
# 手动下载 Gradle 分发
wget https://services.gradle.org/distributions/gradle-8.0-bin.zip

# 放到正确的目录
mkdir -p ~/.gradle/wrapper/dists/gradle-8.0-bin
cp gradle-8.0-bin.zip ~/.gradle/wrapper/dists/gradle-8.0-bin/

3. 版本冲突

bash
# 清理本地缓存
rm -rf ~/.gradle/wrapper/dists/

# 重新下载
./gradlew build

4. 网络问题

bash
# 使用离线模式
./gradlew build --offline

# 配置代理
./gradlew build -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080

安全考虑

1. 验证 Wrapper JAR

bash
# 验证 Wrapper JAR 的校验和
shasum gradle/wrapper/gradle-wrapper.jar

2. 使用 HTTPS

properties
# gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip

3. 限制网络访问

groovy
// 在企业环境中，可以限制 Wrapper 只能从内部仓库下载
wrapper {
    distributionUrl = 'https://internal-repo.example.com/gradle/gradle-8.0-bin.zip'
}

高级用法

1. 多项目中的 Wrapper

bash
# 在根项目生成 Wrapper
./gradlew wrapper

# 所有子项目都可以使用同一个 Wrapper
./gradlew :module1:build
./gradlew :module2:build

2. 自定义 Wrapper 脚本

bash
# 修改 gradlew 脚本以添加自定义逻辑
# 例如：设置环境变量、检查 Java 版本等

3. 使用 Gradle 版本目录

groovy
// gradle/libs.versions.toml
[versions]
gradle = "8.0"

// 在 build.gradle 中使用
wrapper {
    gradleVersion = libs.versions.gradle.get()
}