Guide to the Gradle Wrapper – Gradle封装器指南

最后修改: 2020年 9月 24日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

Gradle is commonly used by developers to manage their project’s build lifecycle. It’s the default choice of build tool for all new Android projects.

Gradle通常被开发人员用来管理其项目的构建生命周期。它是所有新的Android项目默认选择的构建工具。

In this tutorial, we’ll learn about Gradle Wrapper, an accompanying utility that makes it easier to distribute projects.

在本教程中，我们将学习Gradle Wrapper，它是一个附带的工具，可以让我们更容易地分发项目。

2. Gradle Wrapper

2.Gradle封装器

To build a Gradle-based project, we need to have Gradle installed in our machine. However, if our installed version doesn’t match with the project’s version, we’ll probably face many incompatibility problems.

为了构建一个基于Gradle的项目，我们需要在我们的机器上安装Gradle。然而，如果我们安装的版本与项目的版本不一致，我们可能会面临许多不兼容的问题。

Gradle Wrapper, also called Wrapper in short, solves this problem. It’s a script that runs Gradle tasks with a declared version. If the declared version is not installed, Wrapper installs the required one.

Gradle Wrapper，也叫Wrapper，简而言之，解决了这个问题。它是一个运行Gradle任务的脚本，有一个声明的版本。如果申报的版本没有安装，Wrapper会安装所需的版本。

The main benefits of Wrapper are that we can:

Wrapper的主要好处是，我们可以。

  • Build a project with Wrapper on any machine without the need to install Gradle first
  • Have a fixed Gradle version. This yields reusable and more robust builds on CI pipelines
  • Upgrade to a new Gradle version easily by changing the Wrapper definition

In the next sections, we’ll be running Gradle tasks that require Gradle to be installed locally.

在接下来的章节中，我们将运行需要本地安装Gradle的Gradle任务。

2.1. Generating Wrapper Files

2.1.生成包装器文件

To use Wrapper, we need to generate some particular files. We’ll generate these files using the built-in Gradle task called wrapper. Note that we need to generate these files only once.

为了使用Wrapper，我们需要生成一些特定的文件。我们将使用内置的Gradle任务wrapper来生成这些文件。注意，我们只需要生成一次这些文件。

Now, let’s run the wrapper task in our project directory:

现在，让我们在我们的项目目录中运行wrapper任务。

$ gradle wrapper

Let’s see the output of this command:

让我们看看这个命令的输出。

Let’s have a look at what these files are:

让我们看一下这些文件是什么。

  • gradle-wrapper.jar contains code for downloading the Gradle distribution specified in the gradle-wrapper.properties file
  • gradle-wrapper.properties contains Wrapper runtime properties — most importantly, the version of the Gradle distribution that is compatible with the current project
  • gradlew is the script that executes Gradle tasks with the Wrapper
  • gradlew.bat is the gradlew equivalent batch script for Windows machines

By default, the wrapper task generates Wrapper files with the Gradle version currently installed on the machine. We can specify another version if needed:

默认情况下，wrapper任务生成的Wrapper文件是当前机器上安装的Gradle版本。如果需要，我们可以指定另一个版本。

$ gradle wrapper --gradle-version 6.3

We recommended checking the Wrapper files into the source control system like GitHub. This way we ensure that other developers can run the project without the need to install Gradle.

我们建议将Wrapper文件检查到 源代码控制系统，如GitHub。这样我们就能确保其他开发者无需安装Gradle就能运行该项目。

2.2. Running Gradle Commands with Wrapper

2.2.用Wrapper运行Gradle命令

We can run any Gradle task with the Wrapper by replacing gradle with gradlew.

我们可以通过将gradle替换为gradlew.来使用Wrapper运行任何Gradle任务。

To list the available tasks, we can use the gradlew tasks command:

要列出可用的任务，我们可以使用gradlew tasks命令。

$ gradlew tasks

Let’s have a look at the output:

让我们看一下输出结果。

Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in root project 'gradle-wrapper'.
components - Displays the components produced by root project 'gradle-wrapper'. [incubating]
dependencies - Displays all dependencies declared in root project 'gradle-wrapper'.
dependencyInsight - Displays the insight into a specific dependency in root project 'gradle-wrapper'.
dependentComponents - Displays the dependent components of components in root project 'gradle-wrapper'. [incubating]
help - Displays a help message.
model - Displays the configuration model of root project 'gradle-wrapper'. [incubating]
outgoingVariants - Displays the outgoing variants of root project 'gradle-wrapper'.
projects - Displays the sub-projects of root project 'gradle-wrapper'.
properties - Displays the properties of root project 'gradle-wrapper'.
tasks - Displays the tasks runnable from root project 'gradle-wrapper'.

As we can see, the output is the same as we would get when running this task with the gradle command.

我们可以看到，输出结果与我们用gradle命令运行这个任务时得到的结果相同。

3. Common Issues

3.常见的问题

Now, let’s look at some common issues that we may face when working with Wrapper.

现在，让我们看看我们在使用Wrapper时可能面临的一些常见问题。

3.1. Global .gitignore That Ignores All Jar Files

3.1.忽略所有Jar文件的全局.gitignore

Some organizations do not allow developers to check jar files into their source control system. Typically, such projects have a rule in the global .gitignore file to ignore all jar files. Therefore, the gradle-wrapper.jar file is not checked into the git repository. For this reason, Wrapper tasks fail to run on other machines. In such cases, we need to add the gradle-wrapper.jar file to git forcefully:

一些组织不允许开发者将jar文件检查到他们的源码控制系统中。通常，这样的项目在全局.gitignore文件中有一条规则，即忽略所有jar文件。因此，gradle-wrapper.jar文件不会被检查到git仓库中。由于这个原因，Wrapper任务在其他机器上运行失败。在这种情况下，我们需要将gradle-wrapper.jar文件强行加入git。

git add -f gradle/wrapper/gradle-wrapper.jar

Similarly, we may have a project-specific .gitignore file that ignores jar files. We can fix it either by relaxing the .gitignore rule or by adding the wrapper jar file forcefully, as shown above.

同样地，我们可能有一个项目专用的.gitignore文件，它忽略了jar文件。我们可以通过放宽.gitignore规则或强行添加包装jar文件来解决这个问题，如上所示。

3.2. Missing Wrapper Folder

3.2.缺少包裹文件夹

When checking in a Wrapper-based project, we may forget to include the wrapper folder that exists inside the gradle folder. But as we have seen above, the wrapper folder contains two critical files: gradle-wrapper.jar and gradle-wrapper.properties.

在检查一个基于Wrapper的项目时，我们可能会忘记包括存在于gradle文件夹内的wrapper文件夹。但正如我们在上面看到的，wrapper文件夹包含两个关键文件。gradle-wrapper.jar和gradle-wrapper.properties.。

Without these files, we’ll get errors when running Gradle tasks with the Wrapper. Therefore, we must check the wrapper folder into the source control system.

没有这些文件，我们在用Wrapper运行Gradle任务时就会出现错误。因此，我们必须将wrapper文件夹检查到源代码控制系统中。

3.3. Removed Wrapper Files

3.3.删除了包装文件

Gradle-based projects contain a .gradle folder that stores cache to speed up Gradle tasks. Sometimes, we need to clear the cache in order to troubleshoot Gradle build issues. Usually, we remove the entire .gradle folder. But we may mistake the Wrapper gradle folder with the .gradle folder and remove it, too. After that, we’ll definitely face problems when trying to run Gradle tasks with the Wrapper.

基于Gradle的项目包含一个.gradle文件夹，它存储了缓存以加速Gradle任务。有时，我们需要清除缓存，以解决Gradle构建问题。通常情况下，我们会删除整个.gradle文件夹。但我们可能会把Wrapper gradle文件夹与.gradle文件夹搞错，把它也删除。在那之后，当我们试图用Wrapper运行Gradle任务时，肯定会遇到问题。

We can solve this problem by pulling the latest changes from the source. Alternatively, we can regenerate the Wrapper files.

我们可以通过从源代码中提取最新的修改来解决这个问题。或者，我们可以重新生成Wrapper文件。

4. Conclusion

4.总结

In this tutorial, we learned about Gradle Wrapper and its basic usage. We also learned about some common problems we may face when working with Gradle Wrapper.

在本教程中，我们了解了Gradle Wrapper和它的基本用法。我们还了解了在使用Gradle Wrapper时可能面临的一些常见问题。

As usual, we can check the project with generated Gradle Wrapper files over on GitHub.

像往常一样，我们可以通过生成的Gradle封装文件在GitHub上检查该项目。