Windows 安装

本文介绍在 Windows 系统上安装 Gradle 的两种方式：手动安装和使用 Scoop 包管理器安装。

前置要求

Gradle 需要 Java 8 或更高版本。首先确认 Java 已安装：

java -version
# 输出示例：
# java version "17.0.9" 2023-10-17 LTS

如果未安装 Java，推荐安装 Eclipse Temurin 或 Microsoft OpenJDK。

方式一：手动安装（官方推荐）

1. 下载 Gradle

访问 Gradle 发布页面 下载最新版本。

推荐下载 binary-only（-bin.zip） 版本（不含源码和文档，体积更小）：

gradle-8.5-bin.zip

2. 解压到安装目录

将下载的 ZIP 文件解压到合适的目录，例如：

C:\Gradle\gradle-8.5\

解压后的目录结构：

C:\Gradle\gradle-8.5\
├── bin\
│   ├── gradle      ← Linux/macOS 脚本
│   └── gradle.bat  ← Windows 脚本
├── lib\
│   └── ...
└── ...

3. 配置环境变量

方法一：图形界面

1. 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
2. 在「系统变量」中，新建变量：
   • 变量名：GRADLE_HOME
   • 变量值：C:\Gradle\gradle-8.5
3. 编辑 Path 变量，添加：%GRADLE_HOME%\bin

方法二：PowerShell 命令

# 以管理员身份运行 PowerShell
[Environment]::SetEnvironmentVariable("GRADLE_HOME", "C:\Gradle\gradle-8.5", "Machine")
$currentPath = [Environment]::GetEnvironmentVariable("Path", "Machine")
[Environment]::SetEnvironmentVariable("Path", "$currentPath;C:\Gradle\gradle-8.5\bin", "Machine")

4. 验证安装

重新打开 PowerShell：

gradle -v

# 输出示例：
# ------------------------------------------------------------
# Gradle 8.5
# ------------------------------------------------------------
# Build time:   2023-11-29 14:08:57 UTC
# Revision:     28aca86a7180baa17117e0e5ba01d8ea9feca598
# Kotlin:       1.9.20
# Groovy:       3.0.17
# Ant:          Apache Ant(TM) version 1.10.13
# JVM:          17.0.9 (Eclipse Adoptium 17.0.9+9)
# OS:           Windows 10 10.0 amd64

方式二：使用 Scoop 安装（推荐）

Scoop 是 Windows 下的命令行包管理器，可以更方便地安装和管理软件。

1. 安装 Scoop

# 以普通用户身份运行 PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

2. 安装 Gradle

scoop install gradle

3. 更新 Gradle

scoop update gradle

方式三：使用 SDKMAN（需要 Git Bash 或 WSL）

在 Windows 上使用 WSL（Windows Subsystem for Linux）时，推荐使用 SDKMAN。详见 SDKMAN 安装。

配置 Gradle 用户目录

Gradle 默认将缓存、Wrapper 下载等存放在 C:\Users\你的用户名\.gradle\。

如需更改（例如 C 盘空间不足）：

# 设置环境变量
[Environment]::SetEnvironmentVariable("GRADLE_USER_HOME", "D:\.gradle", "User")

配置镜像加速

国内下载 Gradle 依赖较慢，推荐配置阿里云镜像。

在 C:\Users\你的用户名\.gradle\ 目录下创建 init.gradle 文件：

// C:\Users\你的用户名\.gradle\init.gradle
allprojects {
    repositories {
        def ALIYUN_REPOSITORY_URL = 'https://maven.aliyun.com/repository/public'
        def ALIYUN_JCENTER_URL = 'https://maven.aliyun.com/repository/jcenter'
        all { ArtifactRepository repo ->
            if (repo instanceof MavenArtifactRepository) {
                def url = repo.url.toString()
                if (url.startsWith('https://repo1.maven.org/maven2')) {
                    project.logger.lifecycle "Repository ${repo.url} replaced by $ALIYUN_REPOSITORY_URL."
                    remove repo
                }
            }
        }
        maven { url ALIYUN_REPOSITORY_URL }
        maven { url ALIYUN_JCENTER_URL }
    }
}

或者在项目的 build.gradle.kts 中配置：

repositories {
    maven { url = uri("https://maven.aliyun.com/repository/public") }
    mavenCentral()
}

IDE 集成

安装完 Gradle 后，配置 IDE 支持：

IntelliJ IDEA：

1. File → Settings → Build, Execution, Deployment → Build Tools → Gradle
2. 选择 Gradle JVM（推荐与项目 JDK 一致）
3. 选择 Use Gradle from：Specified location 并指向安装目录

Eclipse（Buildship 插件）：

1. 安装 Buildship 插件
2. Window → Preferences → Gradle → 配置安装路径

详细配置见 IDE 集成配置。

常见问题

问题：gradle: command not found

原因：环境变量未生效

解决：

1. 关闭并重新打开 PowerShell/CMD
2. 检查环境变量是否正确设置：echo %GRADLE_HOME%

问题：构建时下载依赖超时

原因：网络访问 Maven Central 较慢

解决：配置阿里云镜像（见上方配置镜像加速）

问题：JAVA_HOME is not set

原因：Gradle 找不到 Java

解决：

# 设置 JAVA_HOME
[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-17.0.9.9-hotspot", "Machine")

下一步

• macOS 安装 - macOS 安装指南
• Gradle Wrapper - 推荐使用 Wrapper 管理版本
• Hello World - 创建第一个 Gradle 项目