执行任何 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 脚本。

始终推荐使用 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：这是一个包含 Gradle Wrapper 代码的小型 JAR 文件。它负责为项目下载并安装正确版本的 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 >>