Gradle 安装配置

Gradle 官方网站为 https://gradle.org，当前（2023-06-03）最新稳定版本为 v8.1.1。

安装 Gradle 前请先保证本地已经安装好了 Java8+ 的 JDK 或 JRE，可执行如下命令确认：

$ java -version
# 有输出相应的 java 版本信息就证明已预先安装了 Java。
如我安装的是 Java17：
openjdk version "17.0.2" 2022-01-18
OpenJDK Runtime Environment Temurin-17.0.2+8 (build 17.0.2+8)
OpenJDK 64-Bit Server VM Temurin-17.0.2+8 (build 17.0.2+8, mixed mode, sharing)

1. 下载 zip 安装包

Gradle 各个版本的官方下载地址为 https://services.gradle.org/distributions，Gradle 的安装包是各个平台通用的（Windows、macOS、Linux），稳定版的发布包有好几个，命名格式为：

gradle-{version}-all.zip - 运行时 + 文档 + 源码
gradle-{version}-bin.zip - 运行时
gradle-{version}-docs.zip - 文档
gradle-{version}-src.zip - 源代码

使用 gradle 开发只需安装 gradle-{version}-bin.zip，文档和源码在线查即可，如 gradle-8.1.1-bin.zip 的下载地址为 https://services.gradle.org/distributions/gradle-8.1.1-bin.zip。

2. 解压安装

将下载的 gradle-{version}-bin.zip 安装包解压，解压后目录结构如下：

/path-to/gradle-{version}/
  ├── bin/
  │   ├── gradle
  │   └── gradle.bat
  ├── init.d/
  │   └── readme.txt
  ├── lib/
  │   ├── plugins/
  │   │   └── *.jar
  │   ├── gradle-wrapper-shared-{version}.jar
  │   └── *.jar
  ├── LICENSE
  ├── NOTICE
  └── README

为了方便日后升级更新，在与 gradle-{version} 同级目录下创建一个目录 gradle 软连接到目录 gradle-{version}：

Windows: （以管理员身份执行 CMD）

> cd /path-to/gradle-8.1.1
> mklink /D gradle gradle-8.1.1
为 gradle <<===>> gradle-8.1.1 创建的符号链接

macOS 或 Linux:

$ cd /path-to/gradle-8.1.1
$ ln -s gradle-8.1.1 gradle
$ ls -l
... gradle -> gradle-8.1.1

下次升级 gradle，只需解压新版本到同级目录，然后删除软连接 gradle 并重新链接到新版本的目录即可。

3. 配置系统环境变量

将 Gradle 安装路径 /path-to/gradle/bin 添加到系统环境变量 PATH 内，这样就可以在命令行直接执行 gradel 命令。

Windows 环境打开系统属性窗口（如命令行执行 sysdm.cpl），切换到 "高级" 页签，然后点击 "环境变量(N)..." 按钮，然后将 /path-to/gradle/bin 添加到 Path 变量值的后面即可。

Linux 或 MacOS 环境建议修改 /etc/profile 文件添加如下一行：

export PATH=$PATH:/path-to/gradle/bin

其它环境变量：（非必须的，按需配置即可）

GRADLE_USER_HOME - 当执行 gradle 任务，gradle 会自动下载项目依赖的 jar 文件，默认这些文件缓存在系统用户目录下，目录名为 $USER_HOME/.gradle，对于用户目录所在分区容量有限的情况下，就必须迁移到其它分区，迁移方法很简单，添加系统环境变量 GRADLE_USER_HOME，指向其它分区的特定目录即可。该目录的基本结构为：
```
├── caches                 # 1
│   ├── 4.8                # 1.1
│   ├── 4.9                # 1.1
│   ├── ⋮
│   ├── jars-3             # 1.2
│   └── modules-2          # 1.2
├── daemon                 # 2
│   ├── ⋮
│   ├── 4.8
│   └── 4.9
├── init.d                 # 3
│   └── my-setup.gradle
├── wrapper
│   └── dists              # 4
│       ├── ⋮
│       ├── gradle-4.8-bin
│       ├── gradle-4.9-all
│       └── gradle-4.9-bin
└── gradle.properties      # 5
```
- 1 - Gradle 全局缓存目录（所有非项目特定的东西都缓存在这个目录下）
- 1.1 - Gradle 特定版本的缓存（如用于支持增量构建）
- 1.2 - Gradle 共享缓存（如项目依赖的 jar 包）
- 2 - Gradle Daemon 的 Registry 和 logs
- 3 - Gradle 全局初始化脚本
- 4 - 通过 Gradle Wrapper 下载的安装包
- 5 - Gradle 全局属性配置
这些目录下缓存的内容，会由 Gradle 控制自动清除，清除规则请参考 Gradle 官方文档的说明。
通过设置环境变量 GRADLE_OPTS 控制 java 运行参数，详见这里。

4. 验证安装

> gradle -v
Welcome to Gradle 8.1.1!

Here are the highlights of this release:
 - Stable configuration cache
 - Experimental Kotlin DSL assignment syntax
 - Building with Java 20
For more details see https://docs.gradle.org/8.1.1/release-notes.html

------------------------------------------------------------
Gradle 8.1.1
------------------------------------------------------------
Build time:   2023-04-21 12:31:26 UTC
Revision:     1cf537a851c635c364a4214885f8b9798051175b

Kotlin:       1.8.10
Groovy:       3.0.15
Ant:          Apache Ant(TM) version 1.10.11 compiled on July 10 2021
JVM:          17.0.2 (Eclipse Adoptium 17.0.2+8)
OS:           Windows 11 10.0 amd64

看到上述输出的版本号信息就证明安装成功。

5. 更新 Gradle Wrapper

如果现存的某些项目是使用 Gradle Wrapper 来构建项目的，可以简单的使用下面的命令升级 gradle 到特定的版本：

$ ./gradlew wrapper --gradle-version=8.1.1 --distribution-type=bin

执行上述命令后，下次通过 gradlew 或 gradlew.bat 执行 gradle task 时，Gradle 就会自动下载特定的 gradle 版本进行更新：

$ ./gradlew tasks
Downloading https://services.gradle.org/distributions/gradle-8.1.1-bin.zip

6. 配置镜像加速

gradle 下载的依赖包，默认国内一般下载速度很慢，故需要全局配置一下 gradle，使其默认从其它高速的镜像源下载依赖包，告别龟速。

配置方法为在 $GRADLE_USER_HOME 目录下创建 init.gradle 文件，添加如下内容：

// 自定义默认的 maven 仓库列表
def CUSTOM_REPOSITORIES = {
  // 内网的 nexus 服务，如 http://192.168.0.x:8081/repository/maven-public
  maven { url "$内网Nexus服务地址" }

  // 阿里镜像： central 和 jcenter 的聚合仓库 http://jcenter.bintray.com 和 https://repo1.maven.org/maven2
  //maven { url "https://maven.aliyun.com/repository/public" }
  // 阿里镜像： google 仓库 https://maven.google.com/
  //maven { url "https://maven.aliyun.com/repository/google" }
  // 阿里镜像： gradle-plugin 仓库 https://plugins.gradle.org/m2/
  //maven { url "https://maven.aliyun.com/repository/gradle-plugin" }

  // 原始的非镜像
  //google()
  //jcenter()
  //central()
}

allprojects {
  // 配置项目依赖的下载源
  repositories CUSTOM_REPOSITORIES

  // 配置 gradle 插件依赖的下载源
  buildscript.repositories CUSTOM_REPOSITORIES
}

相关仓库地址按需配置即可，上述只是提供一个配置模板，将速度最快的配置在最前面即可。

参考

Gradle docs / Installing Gradle
Gradle docs / The Directories and Files Gradle Uses - 解析 Gradle 全局缓存目录结构及特定项目的目录结构
Gradle docs / Initialization Scripts