23、Gradle Wrapper：Wrapper的作用、生成与升级Wrapper、自定义Wrapper参数

聊到 Gradle Wrapper，我脑子里第一个蹦出来的场景就是：几年前有个新同事加入项目，拉下代码后执行 gradle build，结果报了一堆莫名其妙的错误。折腾了半天才发现，他本地装的是 Gradle 4.x，而我们项目用的是 6.x。这种「版本地狱」的问题，说白了就是团队协作中最常见的坑。

Gradle Wrapper 就是为了解决这个痛点而生的。它不是一个可有可无的辅助工具，而是 Gradle 项目标准化构建的基石。我个人习惯，不管多小的项目，第一件事就是生成 Wrapper。

Wrapper 到底是什么？

简单来说，Wrapper 是一套脚本和配置文件。它让你不需要在机器上预装 Gradle，也能执行构建。你想想看，这多方便？

一个标准的 Wrapper 包含以下文件：

项目根目录/
├── gradlew          # Unix/Linux/Mac 下的可执行脚本
├── gradlew.bat      # Windows 下的批处理脚本
└── gradle/
    └── wrapper/
        ├── gradle-wrapper.jar      # 负责下载和运行 Gradle 的小型 JAR
        └── gradle-wrapper.properties  # 核心配置文件

这里最核心的是 gradle-wrapper.properties 文件。它决定了「用哪个版本的 Gradle」以及「从哪里下载」。我见过不少团队把这个文件加到 .gitignore 里，结果就是每个人用的 Gradle 版本都不一样，构建结果千奇百怪。嗯，这里要注意：这个文件必须提交到版本控制。

生成 Wrapper 的两种方式

生成 Wrapper 其实很简单。如果你机器上已经装了 Gradle，直接运行：

gradle wrapper

这条命令会在项目根目录生成上面提到的所有文件。默认情况下，它会使用你当前机器上 Gradle 的版本作为目标版本。

但如果你机器上压根没装 Gradle 呢？别急，还有另一种方式。你可以从 Gradle 官网下载一个空项目的模板，或者从其他 Gradle 项目里复制 gradlew 和 gradle-wrapper.jar 过来。只要 gradle-wrapper.properties 配置正确，执行 ./gradlew 就会自动下载对应版本的 Gradle。

我曾经在一个 CI 环境里遇到过这种情况：服务器上不允许安装 Gradle，但允许执行脚本。用 Wrapper 就完美绕过了这个限制。

升级 Wrapper 的正确姿势

项目跑着跑着，Gradle 出新版本了。怎么升级？很多人直接去改 gradle-wrapper.properties 里的版本号。这样做虽然也能生效，但不够优雅。

官方推荐的做法是：

./gradlew wrapper --gradle-version 8.5

这条命令会做三件事：

• 更新 gradle-wrapper.properties 中的版本号
• 下载新版本的 gradle-wrapper.jar
• 重新生成 gradlew 和 gradlew.bat 脚本

为什么要重新生成脚本？因为新版本的 Gradle 可能会对 Wrapper 脚本本身做优化或修复。我见过有人只改了版本号，结果 Wrapper 脚本还是旧的，虽然也能用，但总感觉不踏实。

自定义 Wrapper 参数

Wrapper 的灵活性远不止于指定版本。通过 gradle-wrapper.properties，我们可以自定义很多行为。来看一个典型的配置文件：

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

我来逐个解释这些参数：

参数名	说明	我的建议
distributionBase	Gradle 分发版的存储根目录	保持默认 GRADLE_USER_HOME 即可
distributionPath	相对于 distributionBase 的子路径	保持默认 wrapper/dists
distributionUrl	Gradle 分发版的下载地址	这是最常改的参数，可以换成公司内网镜像
networkTimeout	下载超时时间（毫秒）	网络不好的环境可以调大，比如 30000
validateDistributionUrl	是否校验下载文件的 SHA-256 校验和	建议开启，防止下载被篡改
zipStoreBase	ZIP 文件解压后的存储根目录	通常和 distributionBase 保持一致
zipStorePath	ZIP 文件解压后的存储路径	通常和 distributionPath 保持一致

这里我想重点说说 distributionUrl。默认情况下，它指向 Gradle 官方的 CDN。但在一些内网环境或者访问国外资源慢的地区，这个下载可能会超时。我曾经在一个项目里，每次 CI 构建都要等 5 分钟下载 Gradle，后来把 URL 换成了公司内部的 Nexus 镜像，速度直接提升到 10 秒。

修改方式也很简单：

./gradlew wrapper --gradle-version 8.5 --gradle-distribution-url https://mirrors.company.com/gradle-8.5-bin.zip

或者直接编辑 gradle-wrapper.properties 文件。

Wrapper 的工作流程

为了让你更直观地理解 Wrapper 的运作机制，我画了一张流程图：

这个流程其实很清晰。你执行 ./gradlew 后，Wrapper 脚本会先检查本地有没有对应版本的 Gradle。有就直接用，没有就去下载。下载完成后解压到缓存目录，然后执行构建。整个过程对开发者来说是透明的。

一些实用技巧

最后分享几个我平时用 Wrapper 的小技巧：

• 指定下载镜像： 在内网环境，把 distributionUrl 改成公司镜像，能大幅提升构建速度。
• 锁定版本： 使用 --gradle-version 参数时，建议指定完整版本号，比如 8.5 而不是 8.x。避免意外升级。
• 验证完整性： 开启 validateDistributionUrl=true，防止下载到被篡改的 Gradle 包。
• 清理缓存： 如果遇到奇怪的构建问题，试试删除 ~/.gradle/wrapper/dists 目录下的内容，让 Wrapper 重新下载。

说实话，Wrapper 是 Gradle 生态里最被低估的功能之一。它解决了构建工具版本管理这个看似简单、实则麻烦的问题。我见过太多团队因为版本不一致导致「在我机器上能跑」的尴尬局面。用好 Wrapper，这个问题就迎刃而解了。