做Java开发绕不开构建工具，而在Maven之后，Gradle凭借更灵活的脚本能力和更好的增量构建性能，已经成为Spring Boot、Android等主流项目的默认选择。不过工具再好，也得先把环境搭起来。这篇文章就手把手带你完成Gradle的安装和环境配置，覆盖Windows、Linux和Mac三大平台，并顺便解决国内下载慢这个老大难问题。
安装前的准备：检查JDK环境
Gradle本身是运行在JVM之上的，所以在安装Gradle之前，必须先确认机器上已经装好了JDK。注意是JDK而不只是JRE，因为Gradle在编译项目时需要调用JDK提供的编译工具。版本方面，Gradle 8.x系列要求JDK 8及以上，如果你用的是比较新的Gradle版本（比如8.5以上），建议直接安装JDK 17，兼容性最好。
打开命令行窗口，执行下面的命令验证：
java -version javac -version
如果两个命令都能正常输出版本信息，说明JDK环境没问题。如果提示不是内部或外部命令，说明JAVA_HOME还没配置好，需要先回去把JDK的环境变量补上，否则后面Gradle运行时会直接报错。可以用echo %JAVA_HOME%（Windows）或echo $JAVA_HOME（Linux/Mac）确认环境变量是否已经指向JDK的安装目录。
Windows系统下手动安装Gradle
手动安装是最通用的方式，过程虽然步骤多一点，但能让你清楚每个环节在做什么。第一步是下载发行包，访问Gradle官方的releases页面（地址为 https://services.gradle.org/distributions/ ），选择一个完整的发行版压缩包，文件名类似gradle-8.7-bin.zip。如果只需要二进制文件，下载bin版本就够了；如果后续想阅读源码和文档，可以选择all版本。
考虑到官方服务器在国内访问较慢，也可以使用腾讯云提供的镜像地址，把域名部分替换即可，例如 https://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip，下载速度通常能跑满带宽。
下载完成后进入第二步：解压。建议把压缩包解压到一个不含中文和空格的路径下，比如D:\gradle-8.7。经验上讲，路径里带空格或中文字符有时会导致某些脚本解析异常，与其后面排查怪问题，不如一开始就养成好习惯。
第三步是配置环境变量，这一步是整个安装流程的核心。在Windows搜索栏输入环境变量，打开系统属性面板，点击环境变量按钮，然后在系统变量区域新建一个变量：
变量名：GRADLE_HOME 变量值：D:\gradle-8.7
接着找到名为Path的变量，点击编辑，新增一条记录：%GRADLE_HOME%\bin。注意这里用的是变量引用而不是写死完整路径，好处是以后升级Gradle时只需要修改GRADLE_HOME的值，Path不用动。
如果你更喜欢命令行操作，也可以用管理员权限的PowerShell一键完成：
# 设置 GRADLE_HOME 环境变量
[Environment]::SetEnvironmentVariable("GRADLE_HOME", "D:\gradle-8.7", "Machine")
# 追加到系统 Path
$path = [Environment]::GetEnvironmentVariable("Path", "Machine")
[Environment]::SetEnvironmentVariable("Path", "$path;%GRADLE_HOME%\bin", "Machine")
最后一步是验证。重新打开一个命令行窗口（环境变量修改后必须开新窗口才生效），执行：
gradle -v
看到输出中包含Gradle版本号、JVM版本和安装路径等信息，就说明安装成功了。如果提示命令不存在，优先检查Path里有没有加对路径，其次确认解压目录下是否真的存在bin目录且里面有gradle.bat文件。
Linux和Mac系统：SDKMAN一键安装
在类Unix系统上，除了手动下载解压并配置~/.bashrc之外，更推荐使用SDKMAN这款命令行工具来管理Gradle。它会自动处理下载、解压、环境变量和多版本切换，省心得多。
先安装SDKMAN：
curl -s "https://get.sdkman.io" | bash source "$HOME/.sdkman/bin/sdkman-init.sh"
然后一行命令安装Gradle：
sdk install gradle gradle -v
如果以后需要在多个Gradle版本之间切换，执行sdk list gradle查看可用版本，再用sdk use gradle 8.6临时切换，或者sdk default gradle 8.6设为默认版本。这种多版本管理能力在维护多个不同历史项目时特别实用。
Mac用户如果装了Homebrew，也可以直接brew install gradle，但要注意Homebrew仓库的版本更新可能滞后于官方发布，追求新版本的话还是SDKMAN或者手动安装更合适。
下载加速与仓库配置
环境装好只是第一步，真正让人头疼的是首次构建时依赖下载极慢的问题，因为默认仓库指向的是国外的Maven Central。解决办法是在用户目录下找到或新建init.gradle文件，完整路径通常是C:\Users\你的用户名\.gradle\init.gradle，写入如下配置：
allprojects {
repositories {
maven { url 'https://maven.aliyun.com/repository/public' }
maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
mavenCentral()
}
buildscript {
repositories {
maven { url 'https://maven.aliyun.com/repository/public' }
maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
mavenCentral()
}
}
}
这个配置对机器上所有Gradle项目全局生效，阿里云镜像同步了Maven Central和Gradle插件仓库的内容，国内访问速度非常快。上面同时配置了buildscript仓库，是因为老版本Gradle的插件依赖走的是独立的buildscript仓库，两个都配上可以避免遗漏。
另一个值得调整的配置是依赖缓存位置。Gradle默认把下载的依赖放在用户目录的.gradle文件夹下，如果C盘空间紧张，可以通过新增环境变量GRADLE_USER_HOME来指定新的存储位置，例如设置为D:\gradle-repo，这样所有缓存和wrapper发行包都会存到D盘。
常见问题排查
安装过程中最容易踩的几个坑这里集中说一下。第一个是执行gradle -v时报JAVA_HOME is not set，这明显是JDK环境变量缺失，回去补好JAVA_HOME即可。第二个是配置完环境变量后命令依然不识别，九成原因是没开新的命令行窗口，旧窗口读取的还是老的环境变量。
第三个坑是Gradle版本与JDK版本不匹配，比如用JDK 21去跑一个很老的Gradle 6.x，会直接抛出不支持的异常。遇到这类问题，对照Gradle官方的兼容性矩阵，保证Gradle版本支持的JDK上限覆盖你本机的JDK版本就行。第四个是IDE中Gradle版本与命令行不一致导致构建结果不同，建议在IDEA的设置里将Gradle分发方式指定为本地的Gradle安装目录，保持两端一致，排查问题时会少走很多弯路。
最后补充一点关于Gradle Wrapper的使用建议：实际项目协作时，仓库里通常自带gradlew脚本和wrapper配置，它会在构建时自动下载指定版本的Gradle，这样团队成员无需手动安装也能保证版本统一。本地手动安装的环境更多是用于学习和调试，理解了这一层，你对Gradle的整体工作方式也就更清楚了。
Gradle安装Gradle环境配置Java构建工具修改时间：2026-09-13 09:14:31