1. 概述
Gradle 是开发者常用的一个构建工具，尤其在 Android 项目中是默认选择。它帮助我们管理项目的整个构建生命周期。
本文将介绍 Gradle Wrapper（简称 Wrapper），一个能让我们更方便地分发和构建项目的小工具。
2. Gradle Wrapper 简介
要运行一个基于 Gradle 的项目，通常需要本地安装 Gradle。但如果项目使用的 Gradle 版本和本地安装的不一致，就容易出现兼容性问题。
Wrapper 就是为了解决这个问题而生的。它是一个脚本，可以使用项目中指定的 Gradle 版本来执行构建任务。如果该版本未安装，Wrapper 会自动下载并安装。
使用 Wrapper 的好处包括：
✅ 无需提前安装 Gradle，即可在任何机器上构建项目
✅ 固定 Gradle 版本，让 CI/CD 构建更稳定可靠
✅ 升级 Gradle 版本只需修改 Wrapper 配置即可，简单粗暴
接下来的示例中，我们会运行一些 Gradle 任务，这些任务需要 本地安装 Gradle。
2.1. 生成 Wrapper 文件
要使用 Wrapper，我们需要先生成一些配套文件。这些文件可以通过 Gradle 内置的 wrapper 任务来生成。注意，这些文件只需要生成一次即可。
在项目目录下执行以下命令：
$ gradle wrapper
命令执行后会生成如下文件：
这些文件的作用如下：
gradle-wrapper.jar：负责根据gradle-wrapper.properties文件下载指定版本的 Gradle 发行包gradle-wrapper.properties：包含 Wrapper 的运行时配置，最重要的是声明项目兼容的 Gradle 版本gradlew：Unix/Linux/macOS 下用于执行 Gradle 任务的脚本gradlew.bat：Windows 下的等效批处理脚本
默认情况下，wrapper 任务会使用当前机器上安装的 Gradle 版本来生成 Wrapper 文件。你也可以手动指定版本：
$ gradle wrapper --gradle-version 6.3
⚠️ 强烈建议将这些 Wrapper 文件提交到版本控制系统（如 GitHub），这样其他开发者就无需本地安装 Gradle 即可构建项目。
2.2. 使用 Wrapper 执行 Gradle 命令
使用 Wrapper 执行 Gradle 任务很简单，只需将命令中的 gradle 替换为 gradlew 即可。
例如，查看所有可用任务：
$ gradlew tasks
输出如下：
Help tasks
----------
buildEnvironment - Displays all buildscript dependencies declared in root project 'gradle-wrapper'.
components - Displays the components produced by root project 'gradle-wrapper'. [incubating]
dependencies - Displays all dependencies declared in root project 'gradle-wrapper'.
dependencyInsight - Displays the insight into a specific dependency in root project 'gradle-wrapper'.
dependentComponents - Displays the dependent components of components in root project 'gradle-wrapper'. [incubating]
help - Displays a help message.
model - Displays the configuration model of root project 'gradle-wrapper'. [incubating]
outgoingVariants - Displays the outgoing variants of root project 'gradle-wrapper'.
projects - Displays the sub-projects of root project 'gradle-wrapper'.
properties - Displays the properties of root project 'gradle-wrapper'.
tasks - Displays the tasks runnable from root project 'gradle-wrapper'.
可以看到，输出和直接使用 gradle tasks 是一样的。
3. 常见问题与踩坑
使用 Wrapper 时，可能会遇到一些常见问题，下面列举几个典型场景。
3.1. 全局 .gitignore 忽略所有 .jar 文件
有些公司或团队为了安全或规范，会在全局 .gitignore 中忽略所有 .jar 文件。这会导致 gradle-wrapper.jar 无法被提交到 Git 仓库中，进而导致其他开发者无法使用 Wrapper。
✅ 解决方法是强制提交该文件：
git add -f gradle/wrapper/gradle-wrapper.jar
如果是项目级 .gitignore 导致的问题，也可以通过修改忽略规则或强制提交解决。
3.2. 忘记提交 wrapper 文件夹
Wrapper 的关键文件都存放在项目中的 gradle/wrapper 目录下。如果在提交代码时遗漏了这个目录，其他人拉取代码后运行 gradlew 时就会报错。
✅ 所以，一定要把 gradle/wrapper 文件夹提交到版本控制系统中。
3.3. 误删 Wrapper 文件
Gradle 项目中还有一个 .gradle 文件夹，用于缓存构建信息。有时为了解决构建问题，我们会删除这个文件夹。但要注意，不要把 gradle 文件夹也一起删了，否则 Wrapper 就失效了。
✅ 如果不小心删了，可以通过以下方式解决：
- 从 Git 拉取最新代码恢复
- 重新运行
gradle wrapper生成相关文件
4. 总结
本文介绍了 Gradle Wrapper 的基本使用方法和常见问题。Wrapper 是一个非常实用的工具，能够简化项目构建环境的配置，提升开发和部署效率。
示例项目代码可以在 GitHub 上查看：gradle-wrapper 示例项目