执行任何 Gradle 构建的推荐方式是使用 Gradle Wrapper。

gradle basic 2

wrapper 脚本会调用一个声明的 Gradle 版本，如果需要，会提前下载。

wrapper workflow

它在项目根目录中作为 gradlew 或 gradlew.bat 文件提供

root
├── gradlew     // THE WRAPPER
├── gradlew.bat // THE WRAPPER
└── ...

如果您的项目不包含这些文件，那它很可能不是一个 Gradle 项目——或者 wrapper 尚未设置。

wrapper 不是您从互联网下载的东西。您必须在安装了 Gradle 的机器上运行 gradle wrapper 来生成它。

wrapper 提供了以下好处

  1. 自动下载并使用特定的 Gradle 版本。

  2. 标准化项目使用一个给定的 Gradle 版本。

  3. 为不同的用户和环境（IDE、CI 服务器等）提供相同的 Gradle 版本。

  4. 使得无需手动安装 Gradle 即可运行 Gradle 构建变得容易。

使用 Gradle Wrapper

区分两种运行 Gradle 的方式很重要

  1. 使用系统安装的 Gradle 发行版 — 通过运行 gradle 命令。

  2. 使用 Gradle Wrapper — 通过运行 Gradle 项目中包含的 gradlew 或 gradlew.bat 脚本。

Gradle Wrapper 始终是执行构建的推荐方式，以确保构建的可靠、受控和标准化执行。

  1. 使用系统安装的 Gradle 发行版

    $ gradle build

  2. 使用 Gradle Wrapper

    • 在 Linux 或 OSX 机器上调用 Wrapper

      $ ./gradlew build

    • 在 Windows PowerShell 上调用 Wrapper

      $ gradlew.bat build

如果您想在不同的目录中运行命令，则必须提供 wrapper 的相对路径

$ ../gradlew build

以下控制台输出演示了在 Windows 机器上的命令提示符 (cmd) 中，针对基于 Java 的项目使用 wrapper 的情况

$ gradlew.bat build

Downloading https://services.gradle.org/distributions/gradle-5.0-all.zip
.....................................................................................
Unzipping C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-all\ac27o8rbd0ic8ih41or9l32mv\gradle-5.0-all.zip to C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-al\ac27o8rbd0ic8ih41or9l32mv
Set executable permissions for: C:\Documents and Settings\Claudia\.gradle\wrapper\dists\gradle-5.0-all\ac27o8rbd0ic8ih41or9l32mv\gradle-5.0\bin\gradle

BUILD SUCCESSFUL in 12s
1 actionable task: 1 executed

理解 wrapper 文件

以下文件是 Gradle Wrapper 的一部分

.
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar  (1)
│       └── gradle-wrapper.properties   (2)
├── gradlew (3)
└── gradlew.bat (4)
1 gradle-wrapper.jar: 这是一个小的 JAR 文件，包含 Gradle Wrapper 代码。它负责为项目下载和安装正确版本的 Gradle（如果尚未安装）。
2 gradle-wrapper.properties: 此文件包含 Gradle Wrapper 的配置属性，例如分发 URL（从哪里下载 Gradle）和分发类型（ZIP 或 TARBALL）。
3 gradlew: 这是一个 shell 脚本（基于 Unix 的系统），作为 gradle-wrapper.jar 的包装器。它用于在基于 Unix 的系统上执行 Gradle 任务，而无需手动安装 Gradle。
4 gradlew.bat: 这是一个批处理脚本（Windows），其用途与 gradlew 相同，但用于 Windows 系统。
您不应更改这些文件。

如果您想查看或更新项目的 Gradle 版本，请使用命令行

$ ./gradlew --version
$ ./gradlew wrapper --gradle-version 7.2
$ gradlew.bat --version
$ gradlew.bat wrapper --gradle-version 7.2
不要手动编辑 wrapper 文件。

您可以查阅 Gradle Wrapper 参考 以了解更多信息。

下一步： 了解 Gradle CLI >>