Gradle Wrapper

Gradle Wrapper（简称 gradlew）是官方推荐的 Gradle 使用方式。它将 Gradle 版本信息绑定到项目中，确保所有开发者、CI/CD 系统使用完全相同的 Gradle 版本构建项目。

为什么要用 Wrapper？

没有 Wrapper 的问题：

• 开发者 A 用 Gradle 7.6，开发者 B 用 Gradle 8.5 → 构建行为不一致
• 新同事加入需要手动安装正确版本的 Gradle
• CI 服务器需要单独配置 Gradle

使用 Wrapper 的好处：

• 版本锁定：所有人使用同一版本
• 自动下载：第一次使用时自动下载正确版本
• 无需全局安装：只需有 Java 即可运行

Wrapper 文件结构

project-root/
├── gradlew              ← Linux/macOS 执行脚本
├── gradlew.bat          ← Windows 执行脚本
└── gradle/
    └── wrapper/
        ├── gradle-wrapper.jar        ← Wrapper 启动器（JAR）
        └── gradle-wrapper.properties ← 版本配置文件

这些文件都应该提交到 Git 仓库！

gradle-wrapper.properties 详解

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

属性	说明
distributionBase	Gradle 下载目录的根路径（GRADLE_USER_HOME 即 ~/.gradle）
distributionPath	相对于 distributionBase 的子路径
distributionUrl	Gradle 发行版的下载 URL
zipStoreBase	ZIP 存储路径的根
zipStorePath	ZIP 存储的相对路径

版本类型

URL 后缀	说明	推荐场景
-bin.zip	仅包含 Gradle 运行时	生产使用（推荐）
-all.zip	包含源码和文档	开发时（IDE 可跳转源码）

# 推荐：仅 bin
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip

# 开发时：含源码（IntelliJ IDEA 可跳转 Gradle 源码）
distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-all.zip

生成 Wrapper

已有 Gradle 安装时

# 在项目根目录执行，生成 Wrapper 文件
gradle wrapper

# 指定版本
gradle wrapper --gradle-version 8.5

# 指定发行版类型
gradle wrapper --gradle-version 8.5 --distribution-type bin

升级 Wrapper 版本

# 方式一：命令行
./gradlew wrapper --gradle-version 8.6

# 方式二：直接修改 gradle-wrapper.properties 中的 distributionUrl

使用 Wrapper

所有 Gradle 命令都通过 ./gradlew（Linux/macOS）或 gradlew.bat（Windows）执行：

# Linux/macOS
./gradlew build
./gradlew clean
./gradlew test

# Windows
gradlew.bat build
gradlew build    # Windows 也可以省略 .bat

第一次运行会自动下载对应版本的 Gradle：

Downloading https://services.gradle.org/distributions/gradle-8.5-bin.zip
...........10%...........20%...........30%...........40%...........50%...........60%...........70%...........80%...........90%...........100%
Unzipping /Users/user/.gradle/wrapper/dists/gradle-8.5-bin/xxx/gradle-8.5-bin.zip
Set executable permissions for: /Users/user/.gradle/wrapper/dists/gradle-8.5-bin/xxx/gradle-8.5/bin/gradle

配置下载加速

国内下载 Gradle 发行版较慢，可以配置镜像：

# gradle-wrapper.properties
# 使用腾讯云镜像（示例，实际镜像地址以最新可用为准）
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.5-bin.zip

或者将 Gradle 发行版放到公司内部服务器：

distributionUrl=https\://内部服务器/gradle/gradle-8.5-bin.zip

验证 Wrapper（安全实践）

从公网拉取项目时，建议验证 Wrapper 的完整性：

# 查看 Wrapper JAR 的 SHA-256
sha256sum gradle/wrapper/gradle-wrapper.jar

官方提供的 SHA-256 校验值见：Gradle Security

从 Gradle 8.2 起，可以在 gradle-wrapper.properties 中指定校验和：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
distributionSha256Sum=9d926787066a081739e3eda4ece5c5b9e1a9a102b92a8f68b371f7d1a34f2b3a

常见问题

问题：下载 Gradle 超时

# 在 gradle-wrapper.properties 中指定国内镜像
distributionUrl=https\://maven.aliyun.com/nexus/content/repositories/gradle/gradle-8.5-bin.zip

问题：gradlew: Permission denied（Linux/macOS）

chmod +x gradlew

问题：SSL 证书错误

# 临时跳过 SSL 验证（不推荐在生产中使用）
./gradlew build -Dorg.gradle.internal.http.ssl.trustAll=true

下一步

• IDE 集成配置 - 配置 IntelliJ IDEA 使用 Wrapper
• Hello World - 用 Wrapper 创建第一个项目