gradlew.cmd的使用

gradlew 和 gradlew.cmd 是 Gradle Wrapper（Gradle 包装器）的一部分，用来帮助项目实现跨平台的 Gradle 构建。它们的作用是使项目不依赖于本地安装的 Gradle 版本，而是通过项目中指定的 Gradle 版本来构建，确保团队成员和 CI/CD 环境中使用一致的 Gradle 版本。

一、gradlew 和 gradlew.cmd 的关系

• gradlew 是一个 Unix 可执行脚本文件，适用于 Linux 和 macOS 系统。
• gradlew.cmd 是一个 Windows 可执行的批处理文件，适用于 Windows 系统。

这两个文件的功能是相同的，只是在不同平台上使用各自的脚本来运行 Gradle 包装器，以便自动下载并使用项目中指定的 Gradle 版本。

二、gradlew 和 gradlew.cmd 的使用

在不同的操作系统上使用对应的文件来运行 Gradle 构建：

1. 在 Linux 或 macOS 上：

   • 使用 gradlew 脚本执行 Gradle 命令，例如：

     ./gradlew build

   • ./gradlew 命令会检查当前项目目录下是否有 gradle/wrapper/gradle-wrapper.properties 文件，并根据其中的配置自动下载指定版本的 Gradle。

2. 在 Windows 上：

   • 使用 gradlew.cmd 脚本执行 Gradle 命令，例如：

     gradlew build

   • gradlew.cmd 会检查并下载项目中指定的 Gradle 版本，然后执行构建。

三、Gradle Wrapper 的文件结构

在项目根目录中，使用 gradle wrapper 命令初始化 Gradle Wrapper 后会生成以下文件：

my-gradle-project/
├── gradlew                  # Unix 可执行脚本
├── gradlew.cmd              # Windows 批处理脚本
└── gradle/
    └── wrapper/
        ├── gradle-wrapper.jar            # Gradle Wrapper 的核心 JAR 文件
        └── gradle-wrapper.properties      # Gradle Wrapper 配置文件

• gradle-wrapper.properties 文件中指定了项目所需的 Gradle 版本及其下载地址。例如：

  distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip

• gradle-wrapper.jar 是 Gradle Wrapper 的核心，用来下载和执行指定版本的 Gradle。

Gradle Build 流程

    A[Gradle Build] --> B[Download distribution]
    B --> C[Server]
    B --> D[Store and unpack distribution]
    D --> E[Gradle User Home]
    E --> F[Use distribution]

• Gradle Build：起点，表示 Gradle 开始构建。
• Download distribution：Gradle 下载所需的分发包。
• Server：下载分发包的来源，可以是 Gradle 官方服务器或镜像。
• Store and unpack distribution：Gradle 将分发包存储并解压到用户本地。
• Gradle User Home：Gradle 本地存储位置，用来存放和管理依赖。
• Use distribution：使用解压后的 Gradle 分发包来执行构建任务。

四、Gradle Wrapper 的优点

1. 确保一致的构建环境：所有团队成员和 CI/CD 环境都会使用项目中指定的 Gradle 版本，避免了版本不一致带来的构建问题。
2. 减少本地环境依赖：使用 Gradle Wrapper 后，开发人员不需要手动安装 Gradle。
3. 跨平台兼容性：在 Windows、Linux 和 macOS 上都可以使用相同的命令构建项目。

五、常用命令示例

在项目中，你可以使用以下命令，通过 Gradle Wrapper 进行构建：

# 构建项目
./gradlew build       # Linux/macOS
gradlew build         # Windows

# 清理项目
./gradlew clean       # Linux/macOS
gradlew clean         # Windows

# 运行测试
./gradlew test        # Linux/macOS
gradlew test          # Windows

# 刷新依赖
./gradlew build --refresh-dependencies # Linux/macOS
gradlew build --refresh-dependencies   # Windows

gradlew 和 gradlew.cmd 是 Gradle Wrapper 提供的不同平台的执行脚本。它们帮助项目在不同操作系统上使用相同的 Gradle 版本进行构建，确保了构建环境的一致性和项目的跨平台兼容性。

---

在项目中使用 Gradle Wrapper（gradlew）的一个主要优势是可以方便地指定并升级 Gradle 版本。升级 gradlew 的版本一般分为修改配置和运行升级命令两步完成。以下是详细步骤：

一、升级 gradlew 的版本

1. 打开 gradle-wrapper.properties 文件：

   gradle-wrapper.properties 文件位于 gradle/wrapper/gradle-wrapper.properties，其中指定了项目所使用的 Gradle 版本。

   文件示例内容如下：

   distributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-bin.zip

2. 修改 distributionUrl：

   找到 distributionUrl 属性，将它指向新的 Gradle 版本。例如，如果你要升级到 Gradle 8.0.2，可以修改 distributionUrl 如下：

   distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.2-bin.zip

   • https://services.gradle.org/distributions/ 是 Gradle 官方的下载地址。
   • gradle-8.0.2-bin.zip 指的是版本 8.0.2 的二进制包，通常使用 -bin 版本即可，-all 包含了源代码和文档，一般不需要。

二、通过命令行升级 Gradle Wrapper

你也可以通过命令行直接执行升级命令：

1. 打开终端，导航到项目根目录。

2. 执行以下命令以指定新的 Gradle 版本并自动更新 gradle-wrapper.properties：

   ./gradlew wrapper --gradle-version 8.0.2

   • Windows 上 ：运行 gradlew wrapper --gradle-version 8.0.2
   • Mac/Linux 上 ：运行 ./gradlew wrapper --gradle-version 8.0.2

3. 此命令会自动修改 gradle-wrapper.properties 文件中的 distributionUrl，并下载指定版本的 Gradle 包装器。

三、升级 gradlew 自身脚本文件

Gradle Wrapper 脚本（gradlew 和 gradlew.cmd）通常不需要频繁更新，因为它们是兼容的。然而，如果你的项目需要使用 Gradle 的最新特性，或者你遇到脚本兼容性问题，可以重新生成 Gradle Wrapper 脚本：

./gradlew wrapper

这会根据当前项目中的 Gradle 版本重新生成 gradlew 和 gradlew.cmd 文件。

四、验证升级

完成升级后，可以运行以下命令来确认新的 Gradle 版本已经生效：

./gradlew --version

输出结果中会显示当前 Gradle 版本，确认是否是刚升级到的版本。

在升级 gradlew（Gradle Wrapper）之后，Gradle 会将指定版本的分发包下载并存放在用户主目录下的 Gradle 缓存目录中。这一位置通常称为 Gradle User Home，默认路径如下：

Gradle 下载并存储分发包的位置

• Windows ：C:\Users\YourUsername\.gradle\wrapper\dists
• macOS / Linux ：/home/YourUsername/.gradle/wrapper/dists 或 /Users/YourUsername/.gradle/wrapper/dists

下载后的文件结构

在 .gradle/wrapper/dists 目录下，每个 Gradle 版本都会有一个单独的子文件夹，结构如下：

.gradle/
└── wrapper/
    └── dists/
        └── gradle-8.0.2-bin/
            └── some-hash-folder/
                └── gradle-8.0.2

其中：

• gradle-8.0.2-bin/ ：文件夹名称包含了具体的 Gradle 版本信息，例如 gradle-8.0.2-bin。
• some-hash-folder：是一个根据下载源地址生成的哈希文件夹，用于区分不同的分发包或源地址。
• gradle-8.0.2：解压后的 Gradle 二进制文件，包含用于构建的所有必要文件。

如何更改 Gradle User Home 位置

如果需要自定义 Gradle 的缓存位置，可以通过以下方式修改：

1. 设置环境变量 ：

   将环境变量 GRADLE_USER_HOME 指向你想要的目录。例如：

   export GRADLE_USER_HOME=/path/to/your/custom/gradle-home

2. 修改 gradle.properties 文件 ：

   在 gradle.properties 文件中加入以下配置：

   org.gradle.user.home=/path/to/your/custom/gradle-home

这样，Gradle 就会将所有分发包和依赖项下载到你指定的目录，而不是默认的 .gradle 文件夹中。