Ubuntu 22.04 安装 Gradle 9.8 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Gradle 9.8.2 并跑通首个 Java 工程。主线采用官方发行包（bin.zip + SHA-256 校验）方案，辅以 SDKMAN! 对照方案；覆盖 JDK 前置、安装、环境变量、多版本管理、工程初始化冒烟、Wrapper、卸载清理，全部命令与回显均在真实服务器实测通过。

一、环境信息

操作系统：Ubuntu 22.04.4 LTS（x86_64），内核 6.8.0-138-generic
JDK：OpenJDK 17.0.20.1（apt 官方仓库安装）；构建期工具链 JDK 21（Temurin 21.0.12.1_1，Gradle 自动下载，见 6.3 节说明）
Gradle：9.8.2（官方最新稳定版，https://services.gradle.org/versions/current 于 2026-10-20 实查）
安装位置：/opt/gradle-9.8.2，软链 /opt/gradle
Gradle 用户主目录：~/.gradle（自动生成，存放 Daemon 日志、依赖缓存、Wrapper 发行包）
实验工程：/opt/demo-app（Java 应用，Kotlin DSL）
发行包大小：151,620,138 字节（约 145MB），SHA-256 21bd5da2de49b642904077f38c0efdc7778e92b3ed0889392dca61b97e389607（官方 checksumUrl 公布值，本文实测比对一致）

二、前置条件

2.1 安装 JDK 17

Gradle 9.x 自身需要 JDK 17–24 运行。Ubuntu 22.04 的 apt 仓库自带 openjdk-17-jdk，直接安装：

sudo apt-get update
sudo apt-get install -y openjdk-17-jdk

实测安装完成后验证：

java -version

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

javac -version

实测回显：

javac 17.0.20.1

update-alternatives --list java

实测回显：

/usr/lib/jvm/java-17-openjdk-amd64/bin/java

💡 说明：OpenJDK 17 足够运行 Gradle 9.8.2 本身。若工程声明的工具链要求更高版本 JDK（如 Java 21），Gradle 会经 foojay resolver 插件自动下载对应 JDK 到 ~/.gradle/jdks/，无需手工安装（本文 6.3 节有实测）。

2.2 安装 unzip（发行包解压需要）

sudo apt-get install -y unzip
which unzip

实测回显：

/usr/bin/unzip

三、版本选型说明

2026-10-20 实查 Gradle 官方版本接口 https://services.gradle.org/versions/current（JSON 回显节选）：

{
  "version" : "9.8.2",
  "buildTime" : "20261019162926+0000",
  "downloadUrl" : "https://services.gradle.org/distributions/gradle-9.8.2-bin.zip",
  "checksumUrl" : "https://services.gradle.org/distributions/gradle-9.8.2-bin.zip.sha256",
  "checksum" : "21bd5da2de49b642904077f38c0efdc7778e92b3ed0889392dca61b97e389607",
  "released" : true,
  "final" : true
}

版本线状态（同日 releases.atom 旁证）：

版本线	最新版本	状态	建议
9.8.x	9.8.2（2026-10-19 构建）	当前稳定线	新装首选
8.14.x	8.14.6	上一功能线维护期	老工程兼容期使用
9.9.0	M1/M2 里程碑	未发布	不用于生产

bin 与 all 发行包的选择：-bin.zip 只含运行件（约 145MB），-all.zip 额外附源码与文档（约 240MB）；服务器安装用 bin 即可。如何选版本：新工程直接最新稳定版；已有工程以 gradle/wrapper/gradle-wrapper.properties 中 distributionUrl 声明的版本为准（Wrapper 机制见第七章）。

四、官方发行包安装方案（A：主线）

4.1 方案说明

从 Gradle 官方分发服务 services.gradle.org 下载 bin.zip，SHA-256 校验后解压到 /opt/gradle-9.8.2，建立 /opt/gradle 软链（便于多版本切换），配置 GRADLE_HOME 与 PATH。这是官方文档推荐的标准方式，版本自主可控，适合服务器常态安装。

4.2 下载发行包（含真实排障实录）

第一步：直连官方地址：

cd /usr/local/src   # 任选一个工作目录存放下载包（本文用 /usr/local/src）
curl -sSL -o gradle-9.8.2-bin.zip https://services.gradle.org/distributions/gradle-9.8.2-bin.zip

实测受阻：services.gradle.org 返回 HTTP/1.1 307 Temporary Redirect，跳转目标为 GitHub 发行件：

Location: https://github.com/gradle/gradle-distributions/releases/download/v9.8.2/gradle-9.8.2-bin.zip

而本环境直连 GitHub 443 端口不稳定（实测出现 Failed to connect to github.com port 443 after 21056 ms: Connection refused，亦出现间歇连通——同环境 Java Wrapper 后续下载成功过，见第七章）。走 HTTP 代理重试同样多次出现 TLS 中断（error:0A000126:SSL routines::unexpected eof while reading）。

第二步：改用腾讯云镜像（同步官方发行包，最终以下载后 SHA-256 与官方 checksum 比对兜底）：

curl -sSI https://mirrors.cloud.tencent.com/gradle/gradle-9.8.2-bin.zip | head -5

实测回显：

HTTP/2 200
etag: "6ad6e9af-9098a2a"
server: nginx
content-type: application/zip

time curl -sSL --max-time 600 -o gradle-9.8.2-bin.zip https://mirrors.cloud.tencent.com/gradle/gradle-9.8.2-bin.zip

实测回显：

real    2m6.152s

⚠️ 排障实录：官方分发链路（307 → GitHub）在受限网络下"时通时断"，curl 报 Connection refused 或代理侧 TLS EOF；腾讯云镜像直连稳定（2 分 6 秒完成 145MB）。无论用哪个源，必须用官方公布的 SHA-256 做完整性校验（下一步），校验一致即等价于官方包。

4.3 SHA-256 完整性校验

sha256sum gradle-9.8.2-bin.zip

实测回显：

21bd5da2de49b642904077f38c0efdc7778e92b3ed0889392dca61b97e389607  gradle-9.8.2-bin.zip

与官方 checksumUrl（https://services.gradle.org/distributions/gradle-9.8.2-bin.zip.sha256）公布值逐字一致，校验通过。

4.4 解压与目录布局

sudo unzip -q gradle-9.8.2-bin.zip -d /opt/
sudo ln -sfn /opt/gradle-9.8.2 /opt/gradle
ls -ld /opt/gradle /opt/gradle-9.8.2

实测回显：

lrwxrwxrwx 1 root root 19 Oct 20 13:xx /opt/gradle -> /opt/gradle-9.8.2
drwxr-xr-x 8 root root 4096 Oct 20 13:xx /opt/gradle-9.8.2

ls /opt/gradle-9.8.2

实测回显：

bin  init.d  lib  LICENSE  NOTICE  README

目录解读：bin/gradle 为启动脚本，lib/ 为全部运行 jar，init.d/ 为全局初始化脚本目录（可放各工程共享的 init 脚本）。

4.5 配置环境变量

写入 profile 片段（全体登录用户生效）：

sudo tee /etc/profile.d/gradle.sh > /dev/null <<'EOF'
export GRADLE_HOME=/opt/gradle
export PATH=$GRADLE_HOME/bin:$PATH
EOF
sudo chmod 644 /etc/profile.d/gradle.sh
source /etc/profile.d/gradle.sh
which gradle

实测回显：

/opt/gradle/bin/gradle

4.6 验证安装

gradle --version

实测回显：

------------------------------------------------------------
Gradle 9.8.2
------------------------------------------------------------

Build time:    2026-10-19 16:29:26 UTC
Revision:      8de7bcf76e785507ad92f0741ab9235a430c95e6

Kotlin:        2.4.10
Groovy:        4.0.33
Ant:           Apache Ant(TM) version 1.10.17 compiled on April 6 2026
Launcher JVM:  17.0.20.1 (Ubuntu 17.0.20.1+1-1-22.04-Ubuntu)
Daemon JVM:    /usr/lib/jvm/java-17-openjdk-amd64 (no Daemon JVM specified, using current Java home)
OS:            Linux 6.8.0-138-generic amd64

验证要点：Revision 与官方版本接口 commitId 一致（8de7bcf76e785507...）；Launcher JVM 应为 2.1 节安装的 JDK 17。首次运行 Gradle 会在 ~/.gradle 下初始化用户主目录并打印欢迎横幅，属正常现象。

五、SDKMAN! 对照方案（B）

5.1 方案说明

SDKMAN! 是 JVM 生态常用的多版本命令行管理器，一条命令装/切任意版本 Gradle（sdk install gradle <版本>、sdk use gradle <版本>），适合本机需要频繁切换 Gradle 版本的开发者。注意其实测局限：候选清单同步有延迟——2026-10-20 实查 sdk list gradle 最新为 9.8.1（官方 9.8.2 已发布一天尚未收录）；且其下载经自家 broker 跳转 GitHub，本环境实测下载链路受阻（见 5.3 排障实录）。服务器上锁定单一版本时，方案 A（官方包）更直接。

5.2 安装 SDKMAN! 本体

export SDKMAN_DIR="$HOME/.sdkman"
curl -s "https://get.sdkman.io?rcupdate=false" | bash

实测回显（节选尾部）：

    source "/root/.sdkman/bin/sdkman-init.sh"

Then issue the following command:

    sdk help

Enjoy!!!

重新加载 shell 环境并验证：

source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk version

实测回显：

script: 5.23.2
native: 0.7.34 (linux x86_64)

5.3 查看候选版本（清单同步延迟实测）

sdk list gradle

实测回显（节选首部）：

================================================================================
Available Gradle Versions
================================================================================
     9.8.1               8.0.1               6.2                 3.4.1
     9.8.0               8.0                 6.1.1               3.4
     9.8.0-rc-3          7.6.6               6.1                 3.3
     9.7.1               7.6.5               6.0.1               3.2.1

清单最新为 9.8.1（官方最新 9.8.2 未同步）。

5.4 安装受阻排障实录与本地落位兜底

sdk install gradle 9.8.1

直连实测报错：

curl: (28) SSL connection timeout
mv: cannot stat '/root/.sdkman/tmp/gradle-9.8.1.bin': No such file or directory
Stop! gradle 9.8.1 is not available. Possible causes: ...

走代理（export https_proxy=http://192.168.1.62:7897 http_proxy=...）后重试两次，实测报错：

Stop! gradle 9.8.1 is not available. Internet unreachable.

定位：SDKMAN 下载经 api.sdkman.io broker 跳转 GitHub 发行件，与 4.2 节同源受阻；其内部 curl 重试机制在代理 TLS 中断场景也无法恢复。

兜底方案（本地发行包落位，实测可用）：把 4.2 节已校验的官方包（本文以 9.8.1 为例，腾讯云镜像同样可取 gradle-9.8.1-bin.zip，官方 SHA-256 dce76f55f8e251a3a1f130eb120f30b3d271de2b76c9b0729d316b5a1b6dc01f 校验一致）按 SDKMAN 目录结构落位：

mkdir -p "$SDKMAN_DIR/candidates/gradle"
unzip -oq gradle-9.8.1-bin.zip -d .        # 在下载目录解压出 gradle-9.8.1/
mv gradle-9.8.1 "$SDKMAN_DIR/candidates/gradle/9.8.1"
ln -sfn 9.8.1 "$SDKMAN_DIR/candidates/gradle/current"
source "$SDKMAN_DIR/bin/sdkman-init.sh"
sdk current gradle

实测回显：

Current default gradle version 9.8.1

⚠️ 说明：落位法绕过了 sdk install 的下载步骤，版本号须与 sdk list gradle 中存在的一致（9.8.1 在清单中），sdk current/use/uninstall 等命令随之正常工作。代理环境稳定时直接 sdk install gradle 9.8.1 即可一步完成。

六、工程初始化与构建冒烟（0→1 实测）

6.1 gradle init 生成 Java 应用工程

mkdir -p /opt/demo-app && cd /opt/demo-app
gradle init --type java-application --dsl kotlin --test-framework junit-jupiter --package com.example.demo --project-name demo-app --no-split-project

实测回显：

Starting a Gradle Daemon, 2 stopped Daemons could not be reused, use --status for details

> Task :init
Learn more about Gradle by exploring our Samples at https://docs.gradle.org/9.8.2/samples/sample_building_java_applications.html

BUILD SUCCESSFUL in 2s
1 actionable task: 1 executed

生成的工程结构（find . -maxdepth 3 -not -path './.gradle*' | sort 实测节选）：

./app
./app/build.gradle.kts
./app/src/main/java/com/example/demo/App.java
./app/src/test/java/com/example/demo/AppTest.java
./build.gradle.kts  (不存在——根脚本为空时省略，逻辑全在 settings 与 app)
./gradle/libs.versions.toml
./gradle/wrapper/gradle-wrapper.jar
./gradle/wrapper/gradle-wrapper.properties
./gradle.properties
./gradlew
./settings.gradle.kts

⚠️ 排障实录：Gradle 9.8 的 gradle init 后可跟可选目录参数，但直接写 gradle init demo-app --type ... 时，工程虽会生成到 demo-app/ 目录，命令末尾却会把 demo-app 当作任务名再次执行而报 Task 'demo-app' not found（BUILD FAILED，工程文件已完整生成）。标准姿势：先 mkdir 并 cd 进目录，再执行不带位置参数的 gradle init。

init 生成的关键文件内容：

settings.gradle.kts：

plugins {
    // Apply the foojay-resolver plugin to allow automatic download of JDKs
    id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
}

rootProject.name = "demo-app"
include("app")

gradle.properties（9.x 新工程默认开启配置缓存）：

org.gradle.configuration-cache=true

app/build.gradle.kts 核心块（实测生成）：

plugins {
    application
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation(libs.junit.jupiter)
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
    implementation(libs.guava)
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

application {
    mainClass = "com.example.demo.App"
}

6.2 首次构建

gradle build

实测回显：

Calculating task graph as no cached configuration is available for tasks: build
> Task :app:processResources NO-SOURCE
> Task :app:processTestResources NO-SOURCE
> Task :app:compileJava
> Task :app:classes
> Task :app:jar
> Task :app:startScripts
> Task :app:compileTestJava
> Task :app:testClasses
> Task :app:distTar
> Task :app:distZip
> Task :app:assemble
> Task :app:test
> Task :app:check
> Task :app:build

BUILD SUCCESSFUL in 1s
7 actionable tasks: 7 executed
Configuration cache entry stored.

再次执行 gradle build 观察增量构建效果，实测回显：

BUILD SUCCESSFUL in 433ms
7 actionable tasks: 7 up-to-date
Configuration cache entry reused.

解读：首次构建 7 个任务全部执行（依赖从 Maven Central 下载，Gradle 控制台默认不逐条打印下载行，需要时用 --info 查看）；二次构建全部 up-to-date（增量构建判定跳过），仅 433ms。执行 gradle clean 后再 gradle build 会重新执行全部任务（实测 7 executed）。

6.3 运行应用与工具链说明

gradle run

实测回显（节选）：

> Task :app:run
Hello World!

BUILD SUCCESSFUL in 399ms
2 actionable tasks: 1 executed, 1 up-to-date

关于工具链（Toolchain）：init 生成的工程声明了 JavaLanguageVersion.of(21)，而本机只装了 JDK 17——构建仍成功，因为 settings 里的 foojay-resolver 插件按声明自动下载了 Temurin JDK 21 到 ~/.gradle/jdks/（实测目录内容）：

ls ~/.gradle/jdks/

实测回显：

eclipse_adoptium-21-amd64-linux.2
OpenJDK21U-jdk_x64_linux_hotspot_21-any-vendor-21.0.12.1_1.tar.gz

该下载约 198MB，走 Adoptium 官方渠道；受限网络下首次构建会在此步耗时（或失败，可将 app/build.gradle.kts 的 toolchain 版本改回 17 立即规避）。这也是 JVM 组件内存纪律的入口：Daemon 与编译 Worker 的堆上限在 gradle.properties 的 org.gradle.jvmargs 中控制（如 -Xms128m -Xmx512m，生效验证见《Gradle 9.8 配置参数详解》 5.1 节的 jps -v 实测）。

七、Wrapper：版本一致性的标配机制

7.1 Wrapper 的作用

gradle wrapper 在工程内生成启动脚本 gradlew 与配套文件，任何机器上执行 ./gradlew 都会按声明版本自动下载并使用正确的 Gradle，团队与 CI 无需预装。gradle init 生成的工程已自带 Wrapper（见 6.1 文件清单）。

7.2 手动（重新）生成

cd /opt/demo-app
gradle wrapper --gradle-version 9.8.2

实测回显：

> Task :wrapper UP-TO-DATE

BUILD SUCCESSFUL in 374ms
1 actionable task: 1 up-to-date

ls -l gradlew gradle/wrapper/
cat gradle/wrapper/gradle-wrapper.properties

实测回显：

-rwxr-xr-x 1 root root 8656 Oct 20 13:xx gradlew

gradle/wrapper/:
total 52
-rw-r--r-- 1 root root 48749 Oct 20 13:xx gradle-wrapper.jar
-rw-r--r-- 1 root root   281 Oct 20 13:xx gradle-wrapper.properties
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-9.8.2-bin.zip
networkTimeout=10000
retries=0
retryBackOffMs=500
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

属性逐项说明：distributionUrl 指向官方发行包（改镜像即改此处，如把域名换成 mirrors.cloud.tencent.com/gradle）；networkTimeout=10000 网络超时 10 秒；retries=0 重试次数；validateDistributionUrl=true 校验 URL 可达性。

7.3 用 gradlew 构建与首次下载实测

./gradlew --version

实测回显（与 gradle --version 一致）：

------------------------------------------------------------
Gradle 9.8.2
------------------------------------------------------------

Build time:    2026-10-19 16:29:26 UTC
Revision:      8de7bcf76e785507ad92f0741ab9235a430c95e6
...

首次执行时 Wrapper 把发行包下载到 ~/.gradle/wrapper/dists/gradle-9.8.2-bin/<hash>/，解压完成后以 .ok 标记文件声明就绪（实测该目录内容：gradle-9.8.2/、gradle-9.8.2-bin.zip.ok、gradle-9.8.2-bin.zip.lck；zip 包下载解压后自动清理以省磁盘）。排障实录：本环境 curl 直连官方发行包常被 307 跳转 GitHub 后拒连，但 Wrapper 的 Java 下载器在同环境实测成功——说明该链路是"间歇可达"，生产内网建议直接把 distributionUrl 指到内网镜像或已有发行包的 HTTP 路径，彻底消除不确定性。

八、升级与多版本管理

软链切换（方案 A 路径）：安装新版本到独立目录后重指软链，/opt/gradle 始终指向当前生效版本：

sudo unzip -q gradle-9.8.3-bin.zip -d /opt/
sudo ln -sfn /opt/gradle-9.8.3 /opt/gradle
gradle --version   # 版本即切为新值

SDKMAN! 切换（方案 B 路径）：sdk install gradle 9.8.1 && sdk use gradle 9.8.1（当前 shell）或 sdk default gradle 9.8.1（持久默认）；sdk current gradle 查看当前版本。
工程级锁定（推荐的项目实践）：各工程以 gradle/wrapper/gradle-wrapper.properties 的 distributionUrl 锁版本，升级=改这一行并提交；执行 ./gradlew wrapper --gradle-version <新版本> 可自动更新该文件。

九、常见问题（FAQ）

Q1：gradle: command not found？ /etc/profile.d/gradle.sh 未加载：source /etc/profile.d/gradle.sh；或新开登录 shell。用 echo $GRADLE_HOME 与 which gradle 自查。

Q2：下载官方包卡住/报 Connection refused？ 官方分发链路 307 跳转 GitHub，受限网络不稳定（本文 4.2 实录）。方案：改用同步镜像（如腾讯云 mirrors.cloud.tencent.com/gradle/）下载后务必用官方 SHA-256 校验；或走 HTTP 代理（curl -x http://<proxy>:<port>）。

Q3：sdk install 报 "Internet unreachable"？ SDKMAN 下载经 broker 跳 GitHub，本文 5.4 实测两路均断。用"本地包落位 candidates 目录"兜底（5.4 节完整步骤）。

Q4：首次构建在下载 JDK 21？ init 新工程默认 toolchain 21 + foojay 自动下载（6.3 节实测）。不想多下 JDK：把 app/build.gradle.kts 的 toolchain 改成本机已装版本（17），或接受自动下载（~/.gradle/jdks/，一次性）。

Q5：构建时报 Could not resolve all files/依赖下载失败？ 多为仓库连通性问题。内网代理按 systemProp.http(s).proxyHost/Port 写入 gradle.properties（详见《Gradle 9.8 配置参数详解》 5.6 节），或把仓库指向内网 Nexus/Artifactory。

Q6：Daemon 占内存/想临时不用 Daemon？ 单次构建加 --no-daemon；或工程 gradle.properties 写 org.gradle.daemon=false；常驻 Daemon 的堆上限由 org.gradle.jvmargs 控制（默认 -Xms256m -Xmx512m -XX:MaxMetaspaceSize=384m，jps -v 实测见配置篇 5.1）。

十、卸载与清理

gradle --stop                          # 停止全部兼容 Daemon
sudo rm -f /etc/profile.d/gradle.sh    # 移除环境变量片段
sudo rm -f /opt/gradle                 # 移除软链
sudo rm -rf /opt/gradle-9.8.2          # 移除安装目录（多版本时逐个删）
rm -rf ~/.gradle                       # 移除用户级缓存/日志/Wrapper 发行包（约数百 MB～数 GB）
rm -rf /opt/demo-app                   # 移除实验工程

SDKMAN! 方案的清理（若用过）：

sdk uninstall gradle 9.8.1
rm -rf ~/.sdkman

apt 安装的 JDK 若为 Gradle 专用可一并卸载：sudo apt-get purge -y openjdk-17-jdk openjdk-17-jre && sudo apt-get autoremove -y（若机器另有 Java 应用依赖 JDK 则保留）。

十一、参考链接

Gradle 官方安装文档（UNIX 安装）：https://docs.gradle.org/current/userguide/installation.html
官方版本接口：https://services.gradle.org/versions/current
发行包目录（含 SHA-256）：https://services.gradle.org/distributions/
Gradle Wrapper 文档：https://docs.gradle.org/current/userguide/gradle_wrapper.html
Java Toolchains 与 foojay resolver：https://docs.gradle.org/current/userguide/toolchains.html
SDKMAN! 官网：https://sdkman.io
腾讯云 Gradle 镜像：https://mirrors.cloud.tencent.com/gradle/
本系列篇目：《Gradle 9.8.2 介绍与选型指南》、《Gradle 9.8 配置参数详解》、《Gradle 9.8 常用 CLI 命令详解》