理解 Gradle Wrapper

原文地址

绝大多数使用 Gradle 的开发者都会使用 Gradle Wrapper。这是个很正确的选择，因为这使得该项目的开发人员不需要操心于 Gradle 的安装上。正因为 wrapper 无处不在，因此我们需要理解它可以做什么。

如果你还没使用 wrapper

如果你还没开始使用 wrapper，是时候尝试一下了。使用 wrapper 保证了团队中每一个开发者都使用同样版本的 Gradle，并能够使用 Gradle 进行项目的构建（即使他们的电脑上并没有安装 Gradle）。

想入门是十分容易的，首先安装 Gradle，然后进入项目目录，在命令行中执行 gradle warpper 命令，就大功告成了。你可以增加 --gradle-version X.Y 选项去指定你想使用的 Gradle 版本。

现在你可以通过 gradlew shell 脚本或 bat 文件在你的项目根目录中运行任何的 Gradle 任务。

Gradle Wrapper 是什么

Gradle Wrapper 由几个文件组成，这些文件在你的项目目录中。

gradlew : shell 脚本，Unix 用户可以通过它来执行 Gradle 任务。

• gradlew.bat bat 脚本，Windows 用户可以通过它执行 Gradle 任务
• gradle/wrapper/gradle-wrapper.jar wrapper 的可执行 JAR；wrapper 的代码所在。
• gradle/wrapper/gradle-wrapper.properties 一个属性文件，用来配置 wrapper

你应该将这些文件 commit 到版本管理器中。它们体积很小，且独立于操作系统，对于 wrapper 的使用是十分重要的。

Gradle Wrapper 做了什么

当你运行 Gradle Wrapper 时它做了以下几件事：

1. 解析给予 gradlew 的参数
2. 安装正确版本的 Gradle
3. 调用 Gradle 去执行指定的任务

注意 wrapper 仅接受两个可选参数：

• -q 或 --quiet 去阻止输出
• -g 或 --gradle-user-home 去指定一个和替换的 Gradle 的 home 目录。

Gradle 的安装阶段是唯一令人十分感兴趣的阶段。首先，它会检查你的 GRADLE_USER_HOME，查看在这个目录下是否有所需要的 Gradle。如果这里有，wrapper 就会去调用该 Gradle。如果没有，wrapper 会下载所需的 Gradle。

有一点需要注意，wrapper 会忽略任何安装在你系统上的 Gradle。wrapper 另外在自己的目录中下载 Gradle，并调用这些 Gradle。当 wrapper 执行任务时，它会使用所有的全局配置，如在Gradle home 目录中的 gradle.properties 文件。

哪些是 Gradle Wrapper 没有做的

Gradle Wrapper 并没有执行你的任务，它只是确认你有所需要的 Gradle 然后调用它。wrapper 是十分轻量的一层，用来消除开发人员自己管理 Gradle 的麻烦。

这意味着 wrapper 与 Gradle 本身是完全分离的。一个 2014 年的 wrapper 可以使用 Gradle 4.0 构建一个项目，一个今天才安装的 wrapper 可以使用 Gradle 2.0 构建一个项目。

如果你在构建中遇见了一个问题，wrapper 出错的可能性极小，因为它仅仅调用了 Gradle。

Wrapper 的配置

我在前面提到，在你的项目中，其中一个是 wrapper 的配置文件 gradle/wrapper/gradle-wrapper.properties 。

通常这个文件是这样的：

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

distributionBase + distributionPath 指定了 wrapper 保存下载的 Gradle 的路径。默认情况下 GRADLE_USER_HOME 是 ~/.gradle ，所以这个 wrapper 会保存 Gradle 在 ~/.gradle/wrapper/dists 。

zipStoreBase 和 zipStorePath 是很相似的。它们指定了 wrapper 保存下载的 Gradle 压缩包的位置。

distributionUrl 通常是你比较关心的，通过它你可以指定你需要的 Gradle 版本，和下载的地址。

升级

因为 wrapper 是独立于 Gradle 的。我们怎样去更新它呢？

wrapper 的文档中说：

如果你想切换你所使用的 Gradle 版本，你不需要重新执行 wrapper 任务，仅需要在 gradle-wrapper.properties 文件中进行配置。但如果你想从新版本的 wrapper 中受益，你需要重新生成 wrapper 文件。

你应该尽可能的使用新版本的 Gradle。你仅需要在 gradle-wrapper.properties 文件中更新 distributionUrl 即可。

通常情况下你不需要更新 Gradle Wrapper，但如果你需要，你可以在更新 Gradle 之后通过执行 gradle wrapper 任务来进行更新。你也可以通过执行 gradlew wrapper 来达到目的，这样能使用 wrapper 所调用的 Gradle 版本。升级 wrapper 没有什么问题，但不要期待有令人激动的新特性。自从 2014 年以来，升级 wrapper 完全没有意义。

安卓开发者需要注意，Gradle 的版本是独立于安卓插件、Android Studio 的版本。新版的插件或 Studio 可能要求新版的 Gradle，但你可以在旧版本的插件和 Studio 中使用新版的 Gradle。