文章目录
- 1. Gradle Wrapper的概念和作用
- 2. Gradle Wrapper文件结构
- 1. VERSION:
- 2. TYPE: (分发类型 bin vs all)
- 3. 实际开发中应用
- 4. Gradle Wrapper 最佳实践
- 1. 始终使用 Wrapper：
- 2. 将 Wrapper 文件提交到版本控制：
- 3. 定期更新 Gradle 版本：
- 4. 验证 Wrapper 更改：
- 5. 使用兼容的版本：
在每个Gradle项目中都存在一个Gradle Wrapper，这是Gradle构建系统中一个基础但是非常重要的组件。我们来聊一聊它的作用和重要性。
1. Gradle Wrapper的概念和作用
Gradle Wrapper（简称"Wrapper"）是一个脚本，它的主要目的是确保所有开发者和构建环境使用完全相同版本的 Gradle，而无需手动安装 Gradle。它的核心优势如下：
- 版本一致性：确保所有人（开发者、CI 服务器等）使用完全相同的 Gradle 版本构建项目
- 无需预装 Gradle：新开发者或 CI 环境不需要预先安装 Gradle
- 自动化下载：首次构建时自动下载指定版本的 Gradle
- 版本控制：Wrapper 配置文件可以提交到版本控制系统，确保项目历史构建的一致性
2. Gradle Wrapper文件结构
在典型的 Android Studio 项目中，您会看到以下 Wrapper 相关文件：
project/├── gradle/│ └── wrapper/│ ├── gradle-wrapper.jar│ └── gradle-wrapper.properties├── gradlew (Unix shell script)└── gradlew.bat (Windows batch file)
我们来依次聊聊各文件的作用：
gradle-wrapper.jar：
这是一个小型 Java 可执行文件, 负责下载和安装指定版本的 Gradle，并处理验证下载的Gradle分发包
wrapper.properties
包含 Wrapper 配置的属性文件. 最重要的是
distributionUrl属性，指定使用的 Gradle 版本
gradlew / gradlew.bat
这些是启动脚本，分别用于 Unix 和 Windows 系统, 当运行
./gradlew build或gradlew.bat build时，实际上是通过这些脚本启动构建
对于gradle-wrapper.properties，我们可以详细聊一聊，这个文件一般情况下会包含如下内容：
#Thu Jul 28 20:36:56 CST 2022
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
zipStorePath=wrapper/dists
zipStoreBase=GRADLE_USER_HOME
distributionUrl=https\://services.gradle.org/distributions/gradle-7.0.2-all.zip
那么各属性的含义如下：
distributionBase 和 distributionPath：
组合起来指定下载的 Gradle 分发包存储位置, 通常是
GRADLE_USER_HOME/wrapper/dists,GRADLE_USER_HOME默认是用户主目录下的.gradle文件夹
zipStoreBase 和 zipStorePath：
指定解压后的 Gradle 存储位置,通常与分发包位置相同
distributionUrl:
这是最关键的属性，指定要下载和使用的 Gradle 版本和类型，格式通常为：
https://services.gradle.org/distributions/gradle-[VERSION]-[TYPE].zip
对于distributionUrl，我们可以深入讨论一下：
https://services.gradle.org/distributions/gradle-[VERSION]-[TYPE].zip
1. VERSION:
例如 gradle-7.4-bin.zip 中的 7.4 是 Gradle 的版本号。选择正确的 Gradle 版本对项目至关重要，因为:
- 不同版本的 Gradle 可能有不同的功能和性能
- Android Gradle 插件版本与 Gradle 版本之间有兼容性要求
- 较新版本通常有性能改进和 bug 修复
2. TYPE: (分发类型 bin vs all)
URL 中通常会有 -bin 或 -all 后缀：
- bin: 只包含运行 Gradle 所需的二进制文件和核心脚本. 它下载大小较小，不包含文档和源代码， 适合大多数日常开发和 CI 环境
- all: 包含完整的 Gradle 分发包. 包括文档、示例和源代码, 下载大小更大, 适合需要离线文档或源代码的场景
多数情况下，选择 -bin 版本就足够了，除非有特殊需求。
3. 实际开发中应用
当我们首次克隆一个使用 Gradle Wrapper 的项目并运行 ./gradlew 命令时，会发生以下事情：
- Wrapper 脚本检查是否已安装指定版本的 Gradle
- 如果未安装，使用
gradle-wrapper.jar下载指定的 Gradle 分发包- 下载、验证并解压 Gradle
- 使用下载的 Gradle 版本执行构建
当我们想要更新项目使用的Gradle版本时，有两种方法：
- 手动编辑 gradle-wrapper.properties, 然后点击 sync
# 将 distributionUrl 中的版本号从 7.4 更改为 7.5
distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip
- 使用Gradle任务（推荐）：
# 更新到特定版本
./gradlew wrapper --gradle-version=7.5# 更新到特定版本并使用完整分发包
./gradlew wrapper --gradle-version=7.5 --distribution-type=all
使用任务更新的好处是它会同时更新 gradle-wrapper.properties 和 gradle-wrapper.jar。
那么如何在AS中更新Gradle版本呢？我们可以通过如下步骤更新：
- 打开
File > Project Structure- 选择
Project选项卡- 在
Gradle Version下拉菜单中选择新版本- 点击
Apply或OK
对于distributionUrl，由于指定了从网络下载的文件，有几点安全考虑:
- 使用 HTTPS：确保 URL 使用 HTTPS 协议（默认已配置）
- 来源验证：Wrapper 会验证下载的 ZIP 文件校验和
- 可信源：只从官方 Gradle 分发服务器下载（
services.gradle.org）- 企业环境：一些企业可能会将 Gradle 分发包镜像到内部服务器
对于企业环境的Gradle Wrapper，一般有如下几种配置：
- 使用内部镜像，可以将
distributionUrl指向内部镜像：
distributionUrl=https\://internal-mirror.company.com/gradle/gradle-7.4-bin.zip
- 预下载的 Gradle，对于完全隔离的环境，可以将 Gradle 分发包预先下载到版本控制系统中，并使用本地路径：
distributionUrl=file\:///path/to/project/gradle/wrapper/dists/gradle-7.4-bin.zip
4. Gradle Wrapper 最佳实践
1. 始终使用 Wrapper：
- 在所有项目中使用 Gradle Wrapper
- 避免依赖开发者机器上全局安装的 Gradle
2. 将 Wrapper 文件提交到版本控制：
- 提交所有 Wrapper 文件（包括 JAR）到版本控制系统
- 这确保了构建的一致性和可复现性
3. 定期更新 Gradle 版本：
- 跟踪 Gradle 和 Android Gradle 插件的更新
- 测试新版本是否与项目兼容后再更新
4. 验证 Wrapper 更改：
- 当收到修改
distributionUrl的 Pull Request 时要特别注意 - 确保更改使用了官方 Gradle 分发或受信任的源
5. 使用兼容的版本：
- 确保 Gradle 版本与 Android Gradle 插件版本兼容
- 查阅官方兼容性矩阵：https://developer.android.com/studio/releases/gradle-plugin#updating-gradle
