SDKMAN 安装与使用教程（v2）

SDKMAN 是在 macOS、Linux 上管理 JDK、Maven、Gradle 等开发工具多版本的命令行工具，用法类似 nvm（按项目切换运行时）。本教程以 管理 JDK 为主，并兼顾本仓库点选（gwsq）与开放平台（gwsq-open）常用的 JDK 8 场景。

1. 适用环境

macOS（Intel / Apple Silicon）
Linux（常见发行版）

Windows 需使用 WSL2 或 Git Bash 等类 Unix 环境；原生 Windows 更常用 Chocolatey / 手动安装 JDK。

2. 安装 SDKMAN

2.1 前置条件

已安装 curl
已安装 zip / unzip（多数系统自带）
安装脚本依赖 Bash ≥ 4
- macOS 自带的 /bin/bash 为 3.2：若执行文档里常见的 … | bash，实际会使用系统 Bash，SDKMAN 会提示 SDKMAN requires Bash 4 or higher 并以非零退出，不会产生可用的 ~/.sdkman/。
- Linux / WSL：多数发行版默认 Bash 已 ≥ 4，可直接使用 … | bash；不确定时先执行 bash --version。

2.2 一键安装（按系统选择）

macOS：用 Homebrew 的 Bash 跑安装脚本（推荐）

先安装新版 Bash（只需一次）：

bash

brew install bash

执行安装时不要使用 /bin/bash，应显式使用 Homebrew 的 Bash。Apple Silicon 路径示例：

bash

curl -s "https://get.sdkman.io" | /opt/homebrew/bin/bash

或写成与机器无关的形式：

bash

curl -s "https://get.sdkman.io" | "$(brew --prefix bash)/bin/bash"

Intel 机型上若 brew --prefix 指向 /usr/local，上式同样适用。

Linux / 其它已满足 Bash 4+ 的环境

bash

curl -s "https://get.sdkman.io" | bash

网络与代理（可选）

若出现 curl: (56) CONNECT tunnel failed, response 403 或类似错误，多为 HTTPS 代理拦截了 CONNECT。可在 系统自带终端中执行（避免 IDE 注入代理），或临时清空代理变量后再执行 2.2 中的安装命令，例如：

bash

env HTTPS_PROXY="" HTTP_PROXY="" ALL_PROXY="" http_proxy="" https_proxy="" all_proxy="" \
  curl -s "https://get.sdkman.io" | "$(brew --prefix bash)/bin/bash"

（若不在 macOS，请将管道后的解释器改为本机 Bash ≥ 4 的绝对路径。）

2.3 将 SDKMAN 写入 Zsh / Bash

安装脚本结束时会提示写入 profile。若 Zsh（macOS 默认）未自动写入，可手动追加 一段即可（勿重复粘贴多份）：

bash

grep -q 'sdkman-init.sh' "$HOME/.zshrc" || cat >> "$HOME/.zshrc" <<'EOF'

# SDKMAN
export SDKMAN_DIR="$HOME/.sdkman"
[[ -s "$HOME/.sdkman/bin/sdkman-init.sh" ]] && source "$HOME/.sdkman/bin/sdkman-init.sh"
EOF

Bash 用户则写入 ~/.bash_profile 或 ~/.bashrc（与系统习惯一致即可）。

说明：若 因 Bash 版本不足导致 2.2 失败，仅把上面几行写进 ~/.zshrc 也不会出现 sdk——须先 成功安装 并保证 ~/.sdkman/bin/sdkman-init.sh 存在。

2.4 使配置生效

bash

source "$HOME/.zshrc"
# 或
source "$HOME/.sdkman/bin/sdkman-init.sh"

2.5 验证

bash

test -s "$HOME/.sdkman/bin/sdkman-init.sh" && echo "SDKMAN init OK" || echo "请先成功完成 2.2"
sdk version

若找不到 sdk：先看 初始化脚本是否存在，再核对 .zshrc 是否只保留一份且无拼写错误、当前终端是否已 source。

3. 常用命令速查

命令	说明
`sdk list`	列出可安装的候选（如 `sdk list java`）
`sdk install java <identifier>`	安装指定 JDK
`sdk use java <identifier>`	当前终端会话使用该版本
`sdk default java <identifier>`	默认使用该版本（新终端生效）
`sdk current`	查看当前各 candidate 版本
`sdk uninstall java <identifier>`	卸载某已安装版本
`sdk upgrade`	升级 SDKMAN 自身（视版本提示而定）

说明：<identifier> 为 sdk list java 输出表中最右侧 Identifier 列，例如本文示例中的 8.0.472-amzn、17.0.19-amzn、21.0.11-amzn。版本号随 SDKMAN 远端更新而变化，装机前务必以本机 sdk list java 为准。

4. 安装与切换 JDK（本仓库推荐）

4.1 查看可选 JDK

bash

sdk list java

输出中：

installed（若出现）表示本机已通过 SDKMAN 安装该版本；
>>>（若出现）表示 当前会话正在使用的候选版本。

表中 Vendor / Version / Dist 为发行说明，必须以 Identifier 列为安装参数。

4.2 示例：同时安装 JDK 8、17、21（Amazon Corretto，macOS ARM 64）

以下 Identifier 节选自已截取的 sdk list java（Available Java Versions for macOS ARM 64bit · Corretto），仅作示意；你在自己机器安装时请以 当前列表里同主版本对应的 Identifier 为准（小版本号会迭代，如 21.0.12-amzn 等）。

bash

sdk install java 8.0.472-amzn
sdk install java 17.0.19-amzn
sdk install java 21.0.11-amzn

安装过程中若提示是否设为 default，可统一选 n，再用 4.4 手动指定全局默认。

若你希望使用 Temurin（tem）、Microsoft（ms）等其他发行版，在 sdk list java 中筛选对应 Vendor，使用其 Identifier 即可，命令格式相同：sdk install java <identifier>。

4.3 当前终端临时切换（`sdk use`）

只对 当前这一窗口 / 会话 生效，关闭终端后即恢复 4.4 设定的 default。

bash

sdk use java 8.0.472-amzn      # JDK 8
sdk use java 17.0.19-amzn       # JDK 17
sdk use java 21.0.11-amzn      # JDK 21
java -version

同一终端切换多次时，最后一次 sdk use 生效。

4.4 设置全局默认（`sdk default`）

新开终端、未手动 sdk use 时使用该版本：

bash

sdk default java 21.0.11-amzn   # 示例：日常默认 JDK 21

之后在新终端验证（已正确 source sdkman-init.sh / .zshrc）：

bash

java -version

JDK 8 安装成功后，java -version 仍会显示形如 1.8.0_xxx，属正常现象。

4.5 查看已安装与当前在用

bash

sdk list java          # 已安装行前会有 installed；当前会话可能标记 >>>
sdk current java       # 仅看 java 这一条 candidate 的版本
sdk current           # 查看所有已通过 SDKMAN 托管的候选当前版本

4.6 卸载指定 JDK（`sdk uninstall`）

按 Identifier 卸载（与安装时完全一致），不会卸载系统中非 SDKMAN 安装的 JDK：

bash

sdk uninstall java 8.0.472-amzn
sdk uninstall java 17.0.19-amzn
sdk uninstall java 21.0.11-amzn

注意：

正在 sdk default 或当前会话 sdk use 使用的版本：若卸载，请先 sdk default java <另一个已安装版本> 或在本终端 sdk use 到其它版本，再卸载。
删除后目录一般由 SDKMAN 维护；若要自行核对磁盘占用，可查目录 ~/.sdkman/candidates/java/。

4.7 与开放平台 `gwsq-open` 及老工程 `gwsq` 的关系

gwsq-open 的 pom 一般为 Java 8：编译该平台前建议使用 sdk use java <你的JDK8 Identifier>。不要用 JDK 17+ 在未做升级改造的情况下编译 Spring Boot 1.5 的老 gwsq 工程。需要 JDK 11 时同样在 sdk list java 中选取 11.x 的 Identifier 安装后 sdk use 即可。

5. 按项目自动切换（可选）

5.1 项目根目录 `.sdkmanrc`

在仓库根目录（或子工程根目录）新建文件 .sdkmanrc，内容示例：

text

java=8.0.472-amzn

5.2 开启进入目录自动切换

编辑 SDKMAN 配置：

bash

nano "$HOME/.sdkman/etc/config"

将 sdkman_auto_env=true（若不存在则增加一行）。

进入含有 .sdkmanrc 的目录时，SDKMAN 可自动执行等价于 sdk use 的切换（具体行为以当前 SDKMAN 版本说明为准）。

5.3 手动应用当前目录配置

bash

sdk env

若提示未安装对应版本，执行：

bash

sdk env install

6. 安装 Maven / Gradle（可选）

bash

sdk install maven 3.9.6
sdk install gradle 8.5
sdk use maven 3.9.6
mvn -version

可与 JDK 搭配，保证 不同项目 使用不同构建工具版本。

7. 常见问题排查

7.1 `java -version` 仍显示 Homebrew 或其它 JDK

确认已执行：source "$HOME/.sdkman/bin/sdkman-init.sh"
确认已：sdk default java <identifier> 或 sdk use ...
执行 which java：若仍指向 /usr/bin/java（macOS 可能是 java_home 包装），可检查：

bash

/usr/libexec/java_home -V

以 SDKMAN 安装的 JDK 路径 是否在列表中为准；必要时在 IDE 中单独指定 Project SDK 为 ~/.sdkman/candidates/java/...。

7.2 macOS：`SDKMAN requires Bash 4 or higher` / 安装退出码 1

说明安装脚本跑在了 Bash 3.2 上。按 2.2 节 macOS 使用 brew install bash 后，用 "$(brew --prefix bash)/bin/bash" 重新执行安装；不要依赖 curl … | bash 里的默认 bash（在 macOS 上通常是 /bin/bash）。

7.3 `zsh: command not found: sdk`

常见原因：安装未完成（~/.sdkman/bin/sdkman-init.sh 不存在），却已在 .zshrc 写了 source。处理步骤：

执行：test -s "$HOME/.sdkman/bin/sdkman-init.sh" || echo "需先成功安装 SDKMAN"
若不存在：按 2.2 节重新安装。
确认 .zshrc 中只有一组 SDKMAN_DIR + sdkman-init.sh。
source ~/.zshrc 后再执行 sdk version。

7.4 `curl` 报错 `CONNECT tunnel failed, response 403`

多为 HTTPS 代理环境问题。处理方式见 2.2 节「网络与代理」（清空代理或使用系统终端）。

7.5 CI / 非交互环境

可使用环境变量 SDKMAN_DIR 与 sdk install；部分场景需 yes | sdk install ... 或查阅 SDKMAN 文档中的 non-interactive 说明。

7.6 卸载 SDKMAN

删除目录并清理 ~/.zshrc 中与 SDKMAN 相关的行：

bash

rm -rf "$HOME/.sdkman"
# 手动编辑 ~/.zshrc 删除 export SDKMAN_DIR 与 source sdkman-init.sh

8. 与本仓库其它文档的关系

仓库内 docs/项目与JDK使用指南.md 中有针对 本项目的 JDK 建议 与 SDKMAN 简要说明。
本文档路径：docs/faq/sdkman.md，侧重 SDKMAN 通用安装与日常命令（含 macOS Bash 版本、代理说明，以及 JDK 8/17/21 安装与切换示例），可作为独立操作手册。

9. 官方参考

官网：https://sdkman.io
用法说明以官网文档与 sdk help 输出为准。

v2 · 含 macOS Bash 4+ / 代理与 sdk 排查；第 4 节增补 JDK 8、17、21 安装及 use、default、current、uninstall 示例（Identifier 以 sdk list java 为准）。不含公司内网镜像。

SDKMAN 安装与使用教程（v2） ​

1. 适用环境 ​

2. 安装 SDKMAN ​

2.1 前置条件 ​

2.2 一键安装（按系统选择） ​

macOS：用 Homebrew 的 Bash 跑安装脚本（推荐） ​

Linux / 其它已满足 Bash 4+ 的环境 ​

网络与代理（可选） ​

2.3 将 SDKMAN 写入 Zsh / Bash ​

2.4 使配置生效 ​

2.5 验证 ​

3. 常用命令速查 ​

4. 安装与切换 JDK（本仓库推荐） ​

4.1 查看可选 JDK ​

4.2 示例：同时安装 JDK 8、17、21（Amazon Corretto，macOS ARM 64） ​

4.3 当前终端临时切换（sdk use） ​

4.4 设置全局默认（sdk default） ​

4.5 查看已安装与当前在用 ​

4.6 卸载指定 JDK（sdk uninstall） ​

4.7 与开放平台 gwsq-open 及老工程 gwsq 的关系 ​

5. 按项目自动切换（可选） ​

5.1 项目根目录 .sdkmanrc ​

5.2 开启进入目录自动切换 ​

5.3 手动应用当前目录配置 ​

6. 安装 Maven / Gradle（可选） ​

7. 常见问题排查 ​

7.1 java -version 仍显示 Homebrew 或其它 JDK ​

7.2 macOS：SDKMAN requires Bash 4 or higher / 安装退出码 1 ​

7.3 zsh: command not found: sdk ​

7.4 curl 报错 CONNECT tunnel failed, response 403 ​

7.5 CI / 非交互环境 ​

7.6 卸载 SDKMAN ​

8. 与本仓库其它文档的关系 ​

9. 官方参考 ​

SDKMAN 安装与使用教程（v2）

1. 适用环境

2. 安装 SDKMAN

2.1 前置条件

2.2 一键安装（按系统选择）

macOS：用 Homebrew 的 Bash 跑安装脚本（推荐）

Linux / 其它已满足 Bash 4+ 的环境

网络与代理（可选）

2.3 将 SDKMAN 写入 Zsh / Bash

2.4 使配置生效

2.5 验证

3. 常用命令速查

4. 安装与切换 JDK（本仓库推荐）

4.1 查看可选 JDK

4.2 示例：同时安装 JDK 8、17、21（Amazon Corretto，macOS ARM 64）

4.3 当前终端临时切换（`sdk use`）

4.4 设置全局默认（`sdk default`）

4.5 查看已安装与当前在用

4.6 卸载指定 JDK（`sdk uninstall`）

4.7 与开放平台 `gwsq-open` 及老工程 `gwsq` 的关系

5. 按项目自动切换（可选）

5.1 项目根目录 `.sdkmanrc`

5.2 开启进入目录自动切换

5.3 手动应用当前目录配置

6. 安装 Maven / Gradle（可选）

7. 常见问题排查

7.1 `java -version` 仍显示 Homebrew 或其它 JDK

7.2 macOS：`SDKMAN requires Bash 4 or higher` / 安装退出码 1

7.3 `zsh: command not found: sdk`

7.4 `curl` 报错 `CONNECT tunnel failed, response 403`

7.5 CI / 非交互环境

7.6 卸载 SDKMAN

8. 与本仓库其它文档的关系

9. 官方参考