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 构建:
-
在 Linux 或 macOS 上:
-
使用
gradlew
脚本执行 Gradle 命令,例如:bash./gradlew build
-
./gradlew
命令会检查当前项目目录下是否有gradle/wrapper/gradle-wrapper.properties
文件,并根据其中的配置自动下载指定版本的 Gradle。
-
-
在 Windows 上:
-
使用
gradlew.cmd
脚本执行 Gradle 命令,例如:cmdgradlew 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 版本及其下载地址。例如:propertiesdistributionUrl=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 的优点
- 确保一致的构建环境:所有团队成员和 CI/CD 环境都会使用项目中指定的 Gradle 版本,避免了版本不一致带来的构建问题。
- 减少本地环境依赖:使用 Gradle Wrapper 后,开发人员不需要手动安装 Gradle。
- 跨平台兼容性:在 Windows、Linux 和 macOS 上都可以使用相同的命令构建项目。
五、常用命令示例
在项目中,你可以使用以下命令,通过 Gradle Wrapper 进行构建:
bash
# 构建项目
./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
的版本
-
打开
gradle-wrapper.properties
文件:gradle-wrapper.properties
文件位于gradle/wrapper/gradle-wrapper.properties
,其中指定了项目所使用的 Gradle 版本。文件示例内容如下:
propertiesdistributionUrl=https\://services.gradle.org/distributions/gradle-7.4.2-bin.zip
-
修改
distributionUrl
:找到
distributionUrl
属性,将它指向新的 Gradle 版本。例如,如果你要升级到 Gradle 8.0.2,可以修改distributionUrl
如下:propertiesdistributionUrl=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
你也可以通过命令行直接执行升级命令:
-
打开终端,导航到项目根目录。
-
执行以下命令以指定新的 Gradle 版本并自动更新
gradle-wrapper.properties
:bash./gradlew wrapper --gradle-version 8.0.2
- Windows 上 :运行
gradlew wrapper --gradle-version 8.0.2
- Mac/Linux 上 :运行
./gradlew wrapper --gradle-version 8.0.2
- Windows 上 :运行
-
此命令会自动修改
gradle-wrapper.properties
文件中的distributionUrl
,并下载指定版本的 Gradle 包装器。
三、升级 gradlew
自身脚本文件
Gradle Wrapper 脚本(gradlew
和 gradlew.cmd
)通常不需要频繁更新,因为它们是兼容的。然而,如果你的项目需要使用 Gradle 的最新特性,或者你遇到脚本兼容性问题,可以重新生成 Gradle Wrapper 脚本:
bash
./gradlew wrapper
这会根据当前项目中的 Gradle 版本重新生成 gradlew
和 gradlew.cmd
文件。
四、验证升级
完成升级后,可以运行以下命令来确认新的 Gradle 版本已经生效:
bash
./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 的缓存位置,可以通过以下方式修改:
-
设置环境变量 :
将环境变量
GRADLE_USER_HOME
指向你想要的目录。例如:bashexport GRADLE_USER_HOME=/path/to/your/custom/gradle-home
-
修改
gradle.properties
文件 :在
gradle.properties
文件中加入以下配置:propertiesorg.gradle.user.home=/path/to/your/custom/gradle-home
这样,Gradle 就会将所有分发包和依赖项下载到你指定的目录,而不是默认的 .gradle
文件夹中。