Gradle 入门

官网资料：https://gradle.org/

中文官网资料：https://gradle.org.cn/

常见的项目构建工具

• Ant：2000 年 Apache 推出的纯 Java 编写构建工具，通过 xml 文件(build.xml)管理项目。

  优点：使用灵活，速度快(快于 gradle 和 maven)。

  缺点：Ant 没有强加任何编码约定的项目目录结构，开发人员需编写繁杂 XML 文件构建指令，对开发人也是一个挑战。

• Maven：2004 年 Apache 组织推出的再次使用 xml 文件(pom.xml)管理项目的构建工具。

  优点：遵循一套约定大于配置的项目目录结构，使用统一的 GAV 坐标进行依赖管理，侧重于包管理。

  缺点：项目构建过程僵化，配置文件编写不够灵活、不方便自定义组件，构建速度慢于 gradle。

• Gradle：2012 年 Google 推出的基于 Groovy 语言的全新项目构建工具，集合了 Ant 和 Maven 各自的优势。

  优点：集 Ant 脚本的灵活性+Maven 约定大于配置的项目目录优势，支持多种远程仓库和插件，侧重于大项目构建。

  缺点：学习成本高、资料少、脚本灵活、版本兼容性差等。

自动构建工具对比	Ant	Maven	Gradle
构建性能	最高	最低	居中
仓库	开发者自己处理	maven 仓库	支持多种远程仓库
依赖管理	ivy 管理	GAV 坐标管理	GNV 坐标管理
插件支持	实现方便	实现较难	实现方便
遵循特定目录结构	No	遵循	同 Maven
配置文件	xml 文件最为繁琐	xml 文件	代码脚本，便于写业务逻辑
侧重点	小型项目构建	项目包管理	大型项目构建
目前地位	使用较少	目前主流	未来趋势(spring 家族)

Whatever：无论哪种项目构建工具，都有自身的优势和劣势，所以选择一款最适合自己的就是最好的。

Gradle 安装

Gradle 安装说明

SpringBoot 官方文档明确指出，目前 SpringBoot 的 Gradle 插件需要 gradle8.14 版本及以上，所以我们这里选择 8.x 版本。

The Spring Boot Gradle Plugin provides Spring Boot support in Gradle. It allows you to package executable jar or war archives, run Spring Boot applications, and use the dependency management provided by spring-boot-dependencies. Spring Boot’s Gradle plugin requires Gradle 8.x (8.14 or later) or 9.x and can be used with Gradle’s configuration cache.

其中 SpringBoot 与 Gradle 存在版本兼容文件，Gradle 与 IDEA 也存在兼容问题，所以考虑到 java 程序员会使用 SpringBoot，所以要选择 8.14 版本及高于 8.14 版本的 Gradle，那么相应的 IDEA 版本也要升级，不能太老哦。

安装后配置环境变量。

PATH 添加 gradle 的 bin 目录
# GRADLE_USER_HOME 里面的目录结构和 Maven 不同，最好不共用！

The current Gradle release is 9.2.1. You can download binaries and view docs for all Gradle versions from the releases page.

• Prerequisites
• Additional resources
• Installing with a package manager
• Installing manually
• Upgrade with the Gradle Wrapper
• Older Releases
• Command-Line Completion

Prerequisites

Gradle runs on all major operating systems and requires only a Java JDK version 17 or higher to be installed. To check, run java -version:

$ java -version
openjdk version "21.0.8" 2025-07-15 LTS
OpenJDK Runtime Environment Temurin-21.0.8+9 (build 21.0.8+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.8+9 (build 21.0.8+9-LTS, mixed mode, sharing)

Additional resources

• On-demand and live online training is available for free to Gradle users.
• Self-paced tutorials are a good place to try Gradle with a variety of languages in addition to the docs.
• Gradle has a visual build inspection tool: Build Scan™.
• Finally, the Gradle Newsletter is a great way to keep UP-TO-DATE, with issues crafted monthly.

Installing with a package manager

SDKMAN! is a tool for managing parallel versions of multiple Software Development Kits on most Unix-based systems.

sdk install gradle 9.2.1

Homebrew is “the missing package manager for macOS”.

Other package managers are available, but the version of Gradle distributed by them is not controlled by Gradle, Inc. Linux package managers may distribute a modified version of Gradle that is incompatible or incomplete when compared to the official version (available from SDKMAN! or below).

› Additional helpful information

Installing manually

Step 1. Download the latest Gradle distribution

The current Gradle release is version 9.2.1, released on 17 Nov 2025. The distribution zip file comes in two flavors:

• Binary-only
• Complete, with docs and sources

If in doubt, choose the binary-only version and browse docs and sources online.

Need to work with an older version? See the releases page.

Step 2. Unpack the distribution

Linux & MacOS users

Unzip the distribution zip file in the directory of your choosing, e.g.:

$ mkdir /opt/gradle
$ unzip -d /opt/gradle gradle-9.2.1-bin.zip
$ ls /opt/gradle/gradle-9.2.1
LICENSE  NOTICE  bin  getting-started.html  init.d  lib  media

Microsoft Windows users

Create a new directory C:\Gradle with File Explorer.

Open a second File Explorer window and go to the directory where the Gradle distribution was downloaded. Double-click the ZIP archive to expose the content. Drag the content folder gradle-9.2.1 to your newly created C:\Gradle folder.

Alternatively you can unpack the Gradle distribution ZIP into C:\Gradle using an archiver tool of your choice.

Step 3. Configure your system environment

Linux & MacOS users

Configure your PATH environment variable to include the bin directory of the unzipped distribution, e.g.:

export PATH=$PATH:/opt/gradle/gradle-9.2.1/bin

Microsoft Windows users

In File Explorer right-click on the This PC (or Computer) icon, then click Properties -> Advanced System Settings -> Environmental Variables.

Under System Variables select Path, then click Edit. Add an entry for C:\Gradle\gradle-9.2.1\bin. Click OK to save.

Step 4. Verify your installation

Open a console (or a Windows command prompt) and run gradle -v to run gradle and display the version, e.g.:

$ gradle -v

------------------------------------------------------------
Gradle 9.2.1
------------------------------------------------------------

Gradle 项目目录结构

Gradle 项目默认目录结构和 Maven 项目的目录结构一致，都是基于约定大于配置【Convention Over Configuration】。其完整项目目录结构如下所示：

1. 只有 war 工程才有 webapp 目录，对于普通的 jar 工程并没有 webapp 目录
2. gradlew 与 gradlew.bat 执行的指定 wrapper 版本中的 gradle指令，不是本地安装的 gradle 指令

Gradle 创建第一个项目

借助于 spring 脚手架创建 gradle 第一个项目：https://start.spring.io

查看生成的 gradle 项目目录结构如下所示：

与上图对比会发现：总体的目录结构与上图说明的是一致的。

Gradle 中的常用指令

Gradle 常用命令说明

常用 gradle 指令	作用
gradle clean	清空 build 目录
gradle classes	编译业务代码和配置文件
gradle test	编译测试代码，生成测试报告
gradle build	构建项目
gradle build -x test	跳过测试构建

需要注意的是：gradle 的指令要在含有 build.gradle 的目录执行。

修改 Maven 下载源

Gradle 自带的 Maven 源地址是国外的，该 Maven 源在国内的访问速度是很慢的，除非使用了特别的手段。一般情况下，我们建议使用国内的第三方开放的 Maven 源或企业内部自建 Maven 源。

认识 init.d 文件夹

我们可以在 gradle 的 init.d 目录下创建以 gradle 结尾的文件，gradle 文件可以实现在 build 开始之前执行，所以你可以在这个文件配置一些你想预先加载的操作。

在 init.d 文件夹创建 init.gradle 文件

allprojects {
    repositories {
        mavenLocal()
        maven {
            url = 'https://maven.aliyun.com/repository/public/'
        }
        maven {
            url = 'https://maven.aliyun.com/repository/central'
        }
        mavenCentral()
    }

    buildscript {
        repositories {
            maven {
                name = "Alibaba"
                url = "https://maven.aliyun.com/repository/public"
            }
            maven {
                name = "M2"
                url = "https://plugins.gradle.org/m2/"
            }
        }
    }
}

拓展 1：启用 init.gradle 文件的方法有：

1. 在命令行指定文件，例如：gradle --init-script yourdir/init.gradle -q taskName，你可以多次输入此命令来指定多个 init 文件
2. 把 init.gradle 文件放到 USER_HOME/.gradle/ 目录下
3. 把以 .gradle 结尾的文件放到 USER_HOME/.gradle/init.d/ 目录下
4. 把以 .gradle 结尾的文件放到 GRADLE_HOME/init.d/ 目录下

如果存在上面的 4 种方式的 2 种以上，gradle 会按上面的 1-4 序号依次执行这些文件，如果给定目录下存在多个 init 脚本，晦暗拼音 a-z 顺序执行这些脚本，每个 init 脚本都存在一个对应的 gradle 实例，你在这个文件中调用的所有方法和属性，都会委托给这个 gradle 实例，每个 init 脚本都实现了 Script 接口。

拓展 2：仓库地址说明

mavenLocal()：指定使用 maven 本地仓库，而本地仓库在配置 maven 时 settings.xml 文件指定的仓库位置。如 E:/repository，gradle 查找 jar 包顺序如下：USER_HOME/.m2/settings.xml >> M2_HOME/conf/settings.xml >> USER_HOME/.m2/repository

maven { url 地址}：指定 maven 仓库，一般用私有仓库地址或其它的第三方库【比如阿里镜像仓库地址】。

mavenCentral()：这是 Maven 的中央仓库，无需配置，直接声明就可以使用。

jcenter()：JCenter 中央仓库，实际也是用 maven 搭建的，但相比 Maven 仓库更友好，通过 CDN 分发，并且支持 https 访问。在新版本中已经废弃了，替换为了mavenCentral()。

总之，gradle 可以通过指定仓库地址为本地 maven 仓库地址和远程仓库地址相结合的方式，避免每次都会去远程仓库下载依赖库。这种方式也有一定的问题，如果本地 maven 仓库有这个依赖，就会直接加载本地依赖，如果本地仓库没有该依赖，那么还是会从远程下载。但是下载的 jar 不是存储在本地 maven 仓库种，而是放在自己的缓存目录中，默认在 USER_HOME/.gradle/caches 目录，当然如果我们配置过 GRADLE_USER_HOME 环境变量，则会放在 GRADLE_USER_HOME/caches 目录，那么可不可以将 gradle 的 caches 指向 maven repository。我们说这是不行的，caches 下载文件不是按照 maven 仓库中存放的方式。

拓展 3：阿里云仓库地址请参考：https://developer.aliyun.com/mvn/guide

仓库名称	阿里云仓库地址	阿里云仓库地址(老版)	源地址
central	https://maven.aliyun.com/repository/central	https://maven.aliyun.com/nexus/content/repositories/central	https://repo1.maven.org/maven2/
public	https://maven.aliyun.com/repository/public	https://maven.aliyun.com/nexus/content/groups/public	central仓和jcenter仓的聚合仓
gradle-plugin	https://maven.aliyun.com/repository/gradle-plugin	https://maven.aliyun.com/nexus/content/repositories/gradle-plugin	https://plugins.gradle.org/m2/
apache snapshots	https://maven.aliyun.com/repository/apache-snapshots	https://maven.aliyun.com/nexus/content/repositories/apache-snapshots	https://repository.apache.org/snapshots/

Wrapper 包装器

Gradle Wrapper 实际上就是对 Gradle 的一层包装，用于解决实际开发中可能会遇到的不同的项目需要不同版本的 Gradle 问题。例如：把自己的代码共享给其他人使用，可能出现如下情况：

1. 对方电脑没有安装 gradle
2. 对方电脑安装过 gradle，但是版本太旧了

这时候，我们就可以考虑使用 Gradle Wrapper 了。这也是官方建议使用 Gradle Wrapper 的原因。实际上有了 Gradle Wrapper 之后，我们本地是可以不配置 Gradle 的，下载 Gradle 项目后，使用 gradle 项目自带的 wrapper 操作也是可以的。那如何使用 Gradle Wrapper 呢？

项目中的 gradlew、gradlew.cmd 脚本用的就是 wrapper 中规定的 gradle 版本。参见源码。

而我们上面提到的 gradle 指令用的是本地 gradle，所以 gradle 指令和 gradlew 指令所使用的 gradle 版本有可能是不一样的。

gradlew、gradlew.cmd 的使用方式与 gradle 使用方式完全一致，只不过把 gradle 指令换成了 gradlew 指令。

当然，我们也可在终端执行 gradlew 指令时，指定一些参数来控制 Wrapper 的生成，比如依赖的版本等，如下：

参数名	说明
--gradle-version	用于指定使用的Gradle版本
--gradle-distribution-url	用于指定下载Gradle发行版的url地址

具体操作如下所示：

gradle wrapper --gradle-version=4.4：升级 wrapper 版本号，只是修改 gradle.properties 中 wrapper 版本，未实际下载 gradle wrapper --gradle-version 5.2.1 --distribution-type all：关联源码用

GradleWrapper 的执行流程

1. 当我们第一次执行 ./gradlew build 命令的时候，gradlew 会读取 gradle-wrapper.properties 文件的配置信息
2. 准确的将指定版本的 gradle 下载并解压到指定的位置(GRADLE_USER_HOME 目录下的 wrapper/dists 目录中)
3. 并构建本地缓存(GRADLE_USER_HOME 目录下的 caches 目录中)，下次再使用相同版本的 gradle 就不用下载了
4. 之后执行的 ./gradlew 所有命令都是使用指定的 gradle 版本。如下图所示

gradle-wrapper.properties 文件解读：

字段名	说明
distributionBase	下载的 Gradle 压缩包解压后存储的主目录
distributionPath	相对于 distributionBase 的解压后的 Gradle 压缩包的路径
zipStoreBase	同 distributionBase，只不过是存放 zip 压缩包的
zipStorePath	同 distributionPath，只不过是存放 zip 压缩包的

注意：前面提到的GRADLE_USER_HOME 环境变量用于这里的 Gradle Wrapper 下载的特定版本的 gradle 存储目录。如果我们没有配置过 GRADLE_USER_HOME 环境变量，默认在当前用户目录下载。

那什么时候选择使用 gradle wrappr、什么时候选择使用本地 gradle？

下载别人的项目或者使用操作以前自己写的不同版本的 gradle 项目时，用 Gradle wrapper。

什么时候使用本地 gradle？新建一个项目时，使用 gradle 指令即可。