学术入门1. 为什么Java开发者迟早要面对多环境问题
先讲个我自己的真实经历。几年前我在一家业务系统维护团队干活，线上跑着基于JDK 8的Spring Boot老服务，同时新项目组已经在用JDK 17。最崩溃的一天是这样的：早上打开终端先export JAVA_HOME切到JDK 8去修一个线上bug，中午又有同事喊我帮忙看新项目的编译报错，我又得手忙脚乱地把环境变量改回JDK 17。同一个终端里来回切换环境变量，不但容易忘，而且经常出现“明明切了环境但Maven还是用的旧JDK”这种玄学问题。更尴尬的是，有一次我忘了切换，直接把基于JDK 8编译的旧项目用JDK 17跑起来，结果启动报了一堆“非法反射访问”警告，线上配置全乱了。
这个痛点我相信很多Java开发都有体会。Java版本迭代到现在，JDK 8、11、17、21并存是常态，再加上Groovy、Scala、Kotlin、Maven、Gradle这些工具链也各有版本要求，如果你还在用“手动改系统环境变量”这种远古方式，那你迟早会被多环境搞疯。本文要讲的sdkman，就是解决这套问题的标准方案。
sdkman全称是Software Development Kit Manager，看名字就知道，它是专门管理软件开发工具包的命令行工具。对Java生态来说，它的核心能力就是：在同一台机器上安装、切换、管理多个版本的JDK、JRE、Maven、Gradle、Spring Boot CLI等工具，并且做到“按目录自动切换”“按项目锁定版本”。这篇文章我会从为什么要用、怎么装、怎么用、怎么避坑四个维度完整讲一遍，内容覆盖我这几年在Linux和macOS上实际用sdkman的全部经验，Windows用户也可以用WSL或Git Bash跑，后面会讲。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 方案选型与核心设计思路：为什么偏偏选sdkman
2.1 主流多JDK管理方案对比
先看市面上几种常见方案，我的结论不是sdkman完美无缺，而是在绝大多数场景下它最省心。
第一是手动管理环境变量。这种方式的问题不只是麻烦，而且特别容易出错。你需要在/etc/profile或~/.bashrc里写JAVA_HOME、PATH的export，切换版本时要么改软链接/usr/lib/jvm/default要么手动改文件。一旦项目多了、版本多了，你根本记不住当前终端用的是哪个JDK。还有个隐形坑：很多IDE会缓存JDK路径，你改了系统环境变量但IDE里还跑着旧版本，排查起来能浪费半天。
第二是用包管理器装JDK再手动切换。macOS的Homebrew、Ubuntu的apt都能装多个版本的OpenJDK，但这套方案只解决“安装”不解决“切换”。你要么用update-alternatives（Linux自带但只对Debian系好用），要么自己维护软链接，体验依然很原始。而且Homebrew的openjdk还是一个keg-only的包，装完还需要手动写PATH，这个折腾劲儿我印象太深了。
第三是用IDE内置的SDK管理。IntelliJ IDEA确实能下载多个JDK并且按模块指定，但那是IDE层面的能力，命令行里的Maven、Gradle构建工具并不认这套配置。你写代码时IDE用的JDK对，一跑构建就变成系统默认版本，这种“IDE和命令行不一致”的问题在团队协作中特别常见。
第四是容器化方案。Docker里跑JDK构建确实能彻底隔离环境，让每个项目一个容器，但那是重方案。日常开发中你不可能为了跑一个Java类就开容器，而且容器内的JDK版本管理和宿主机又是两套逻辑。
sdkman的核心优势在于它把“安装、切换、配置、升级”做成了一套完整的命令行体系，底层通过修改PATH和JAVA_HOME的方式实现版本切换，既轻量又和现有工具链天然兼容。它不是虚拟机，不会消耗额外资源；不是IDE插件，命令行里也能用；不是重容器，没有性能损耗。它就是一个Shell脚本工具，做到“所见即所得”，你在终端里设的版本，IDE、Maven、Gradle都能感知到。
2.2 sdkman的真实工作方式
要理解sdkman为什么好用，得先搞懂它的设计。sdkman本质上是一个Shell脚本框架，它使用~/.sdkman目录存放所有安装的SDK。每个SDK版本都是一个独立的子目录，例如~/.sdkman/candidates/java/8.0.392-tem、~/.sdkman/candidates/java/17.0.9-tem。
切换版本时，sdkman做的事情就是把名为current的符号链接指向你选择的版本目录，然后把~/.sdkman/candidates/java/current/bin加到PATH的最前面，同时设置JAVA_HOME指向current目录。这种“软链接+环境变量注入”的设计是它轻量的根本原因，你不需要动任何系统级文件，改的只是当前用户目录下的链接，卸载时直接把~/.sdkman删掉就彻底干净。
再配合sdkman的Shell集成（后面第四节细讲），它可以在你进入某个目录时自动执行java use，把当前目录的JDK版本切到你指定的版本。这就是“按项目锁版本”的实现原理，本质上就是Shell的chpwd钩子在起作用。理解了这层设计，你后续排查问题就会很顺畅，因为你知道它改的只是环境变量和软链接，如果发现JDK没生效，第一反应就应该是“PATH里是不是有其他更靠前的JDK路径”。
3. 环境准备与安装部署全流程
3.1 安装前置依赖
sdkman本身是一个Shell脚本集，它对系统环境的要求极其简单：一个能跑Bash、安装了curl和unzip的类Unix环境。macOS自带这些基础工具，Ubuntu、CentOS需要确认一下，如果没有就装一下。
Ubuntu/Debian执行：
bash复制sudo apt update && sudo apt install curl unzip zip -y
CentOS/RHEL执行：
bash复制sudo yum install curl unzip zip -y
macOS如果用了Homebrew，这些依赖一般也是自带的，不用特别操心。Windows下建议直接用WSL2（Windows Subsystem for Linux）安装Ubuntu，然后在WSL里跑sdkman，体验和Linux完全一致。理论上Git Bash也能跑sdkman，但我在Git Bash里实测过，有些Shell集成的功能在Git Bash下不如原生Linux终端好用，如果你主力机是Windows，我更推荐WSL路线。
3.2 一条命令安装sdkman
官方推荐的安装命令非常简洁：
bash复制curl -s "https://get.sdkman.io" | bash
这条命令会把sdkman源码克隆到~/.sdkman目录，然后在你的Shell配置文件中追加初始化脚本。安装完成后需要重新打开终端或者在当前终端执行：
bash复制source "$HOME/.sdkman/bin/sdkman-init.sh"
验证是否安装成功：
bash复制sdk version
能输出版本号就说明装好了。这个“克隆源码”的安装方式让我一开始有点不适应，因为我习惯了三方工具都放/opt或者/usr/local，但sdkman的作者故意设计成装到用户主目录，目的是让多用户服务器上每个用户各自管理自己的SDK，不需要root权限，也不会影响其他用户。这个设计对开发者本机来说也非常干净。
3.3 安装路径与目录结构说明
sdkman装好后，它的目录结构大致是这个样子：
text复制~/.sdkman/
├── bin/
├── candidates/
│ ├── java/
│ ├── maven/
│ ├── gradle/
│ └── ...
├── etc/
│ └── config
├── src/
├── var/
│ └── ...
└── tmp/
其中candidates是SDK的存放目录，每个SDK对应一个子目录；etc/config是全局配置文件，你可以在这里控制sdkman的行为，比如是否自动更新、是否启用自动切换功能；var目录存的是sdkman自己的元数据和缓存。理解了目录结构后，你就能手动排查一些问题，比如某个SDK没出现在candidates里，说明安装时就没写进去。
顺便提一句，sdkman的升级也极其简单：
bash复制sdk selfupdate
它会自动拉取新版本脚本并重新初始化。我通常在每个月月初或者遇到官方新版本通知时升级一次，升级过程大概十几秒，不会影响已安装的JDK版本。
4. 核心用法与多版本日常管理
4.1 查看所有可安装的JDK发行版
这是sdkman最让人舒服的地方。你不需要去各个JDK发行版官网翻下载页面，直接在命令行里查看所有可选的发行版和版本：
bash复制sdk list java
执行后会输出一大屏内容，包含不同厂商的JDK版本：Temurin（Adoptium）、Zulu（Azul）、Microsoft OpenJDK、Amazon Corretto、Liberica、GraalVM、Oracle等，每个发行版下面都有对应的版本号。输出内容比较多，如果你关心某个具体版本，可以用grep过滤：
bash复制sdk list java | grep -i "17.*tem"
我个人的选择标准是：
- 企业项目首选Temurin，因为它在Linux和Windows生态中最普及，社区活跃、适配性好，很多CI镜像都基于Temurin。
- 追求兼容性和商业支持可选Zulu，Azul对老版本JDK的补丁支持做得比较久。
- 想搞微服务原生镜像、尝试GraalVM特性的，sdkman里直接装
GraalVM发行版，一条命令搞定。
这个列表脚本实际上是实时从sdkman的版本API拉取的，所以第一次执行时会有几秒钟的等待，这是正常的，不是卡住了。如果长时间没反应，多半是网络问题，可以把SDKMAN_CANDIDATES_API的地址切到备用镜像（后面第6节单独讲）。
4.2 安装与永久切换JDK
以安装Temurin JDK 17为例：
bash复制sdk install java 17.0.9-tem
sdkman会下载对应的压缩包、解压到~/.sdkman/candidates/java/目录，然后自动问你“是否把当前版本设为默认版本”，输入y即可。所谓“默认版本”，就是软链接current指向的版本，每次打开新终端都会默认用它。
如果你安装时没设默认为y，或者装了好几个版本之后想换默认，可以随时执行：
bash复制sdk default java 21.0.1-tem
这条命令的作用是让~/.sdkman/candidates/java/current指向21.0.1-tem，而且这个设置是持久的，新开的终端也会沿用。此时你执行：
bash复制java -version
which java
应该能看到java路径指向~/.sdkman/candidates/java/current/bin/java，版本号也切到了对应的版本。这就是sdkman设计的精妙之处：它不改系统全局配置，只改用户目录下的软链接，所以即使你的/usr/bin/java是系统自带的旧版本，只要~/.sdkman的bin在PATH前面，调度用的就是sdkman管理的版本。
4.3 临时切换与当前Shell级切换
永久切默认版本适合“一段时间内集中用某个版本”的情况，但日常开发中更多是“这个项目用8，那个项目用17”，这时就要用到临时切换：
bash复制sdk use java 8.0.392-tem
use只对当前终端会话生效，新开一个终端又会回到默认版本。所以如果你只想在这个终端里用一段时间，比如临时编译一个旧项目，use是最合适的选择。它不用写文件、不用改配置，用完直接关掉终端就自动恢复了，简直是“环境洁癖”患者的福音。
再补充一个更细的命令：sdk use java 17，这里只写主版本号，sdkman会自动帮你匹配该主版本下的默认发行版（通常是Temurin或官方推荐的发行版）。这样你就不用记一长串的完整版本号了。当然，如果机器上同时装有17.0.9-tem和17.0.10-zulu，sdkman会先尝试匹配能精确匹配的，匹配不上再让你选择。
4.4 查看当前版本与已安装版本
估计很多人第一次用sdkman时会迷茫“我现在到底用的哪个JDK”，其实两条命令就搞定了：
bash复制sdk current java
输出类似Using java version 17.0.9-tem in this shell，只看主版本号的话更直观：
bash复制java -version
如果你忘记了自己装过哪些JDK版本，可以看已安装清单：
bash复制sdk list java
输出内容的Local区域会单独列出已安装的版本，标了installed字样，一眼就能看清。想卸载不用的版本也很简单：
bash复制sdk uninstall java 8.0.392-tem
卸载只是删除对应目录和更新软链接，对其他版本没有任何影响。这里建议定期清理不用的版本，因为每个完整JDK发行版动辄200-300MB，装多了硬盘会吃紧。
5. 进阶配置与自动化场景
5.1 配置文件与自动更新开关
sdkman的全局配置在~/.sdkman/etc/config，默认内容很少，但有几个参数值得关注：
bash复制sdkman_auto_answer=false
sdkman_auto_selfupdate=false
sdkman_insecure_ssl=false
sdkman_rosetta2_compatible=false
翻译一下就是：是否需要每步操作都手动确认、是否自动升级sdkman、是否允许非安全连接、是否启用Rosetta 2兼容模式。我个人的建议是：
- sdkman_auto_answer默认false就好，安装时能多一步确认，防止脚本误操作。
- sdkman_auto_selfupdate建议改成true，这样不用手动惦记升级sdkman自身。毕竟工具链版本刷新很快，自动升级能让你及时拿到新JDK版本和修复补丁。
修改方式也很简单，直接用文本编辑器打开这个文件改掉就行，sdkman会在下一次执行命令时读取新的配置。要注意的是，自动升级只是升级sdkman脚本本身，不会动你的已安装JDK版本，所以不用担心“升级把环境搞崩了”这种问题。
5.2 自动切换：.sdkmanrc真香体验
这是sdkman最值得推荐的一个功能。以前我有个项目必须用JDK 8，另一个新项目要求JDK 17，最痛苦的不是跑一次切换一次，而是总有某个时刻忘了切。sdkman提供了.sdkmanrc机制，可以在进入目录时自动切换版本。
首先，在项目根目录执行：
bash复制sdk env init
这个命令会创建一个.sdkmanrc文件，文件中写了当前使用的JDK版本信息：
text复制# Enable auto-env through the sdkman_auto_env config
# Keep this file and sdkman_auto_env=true in your ~/.sdkman/etc/config
java=17.0.9-tem
然后，你需要编辑~/.sdkman/etc/config，把自动切换功能打开：
bash复制sdkman_auto_env=true
保存后，在新打开的终端中如果你cd到这个项目目录，sdkman会自动执行版本切换，你会看到一行提示：Using java version 17.0.9-tem in this shell。再也不用担心“忘了切版本”导致几天后才发现构建环境不对的问题。团队协作时，把.sdkmanrc文件提交到Git仓库，其他同事拉代码后只要也是sdkman，进入目录就会自动用项目要求的JDK版本。这个功能对团队统一开发环境来说，价值比想象中大得多。
有几点实操细节要注意：
.sdkmanrc文件里的版本号建议写完整版本格式，例如17.0.9-tem，只写17的话可能匹配到不同小版本，虽然能用但不够可复现。- 如果你的Shell是zsh，需要确认初始化脚本里sdkman的自动环境钩子没有被其他插件覆盖，如果没用上，检查
~/.zshrc里的sdkman初始化顺序。 - 自动切换的前提是你已经安装了这个版本，如果项目要求一个你还没装的版本，sdkman会提示你使用
install命令。
5.3 离线安装与本地版本导入
企业内网环境或者特定版本比较罕见时，网络下载可能不可用。sdkman也支持离线安装，你只需要把下载好的SDK压缩包放到~/.sdkman/archives/目录，再执行：
bash复制sdk install java 8.0.392-tem
sdkman会优先在archives目录查找本地文件，找不到才联网下载。这个功能我实际用过一次：某次客户环境是纯内网，无法访问外网，我用有外网的电脑下载好JDK压缩包，拷到内网机器的~/.sdkman/archives/，直接install就装上了，整个过程干净利落。注意压缩包命名要和官方格式一致，否则sdkman可能识别不了。
另外，sdkman也可以导入系统中已有的JDK。比如你的/opt/jdk17目录里已经有一套手动解压的JDK，想统一纳入sdkman管理：
bash复制sdk install java 17-custom /opt/jdk17
这里的17-custom是自定义的版本标识，sdkman会把/opt/jdk17作为当前版本加入管理。不过这个场景比较少见，我自己一般还是用官方版本标识，维护起来更省事。
5.4 不仅管JDK，还能管整个工具链
很多人以为sdkman只用来管JDK，其实它的能力远超这一个点。Maven、Gradle、Spring Boot CLI、Kotlin、Scala、Groovy、Ant、Visual VM、JMeter等几十种Java生态工具它都能管。比如你要装Maven 3.9.6：
bash复制sdk install maven 3.9.6
sdk use maven 3.9.6
装了之后mvn -v就会多出一行Java version: 17.0.9-tem，而且这个Java版本信息会自动跟随当前Shell使用的JDK。这解决了另一个常见的痛：**Maven用的JDK和你java -version显示的JDK不一致。**因为sdkman把PATH设置成了一个整体，java、mvn、gradle这些命令会同时感知到当前JDK版本。
举一个我踩过的真实例子：有一次我在一个JDK 8项目里跑mvn clean install，构建却报“无效的目标发行版: 17”，这个报错说明Maven认为应该用JDK 17编译，但我明明记得自己在JDK 8环境。最后定位发现，Maven的JAVA_HOME配置在~/.mavenrc里被硬写成了JDK 17路径。这就是“工具链和JDK不同步”的典型场景。如果你用sdkman统一管Maven，这类环境错乱会少很多。
5.5 与IDE协同工作的配置技巧
如果你用的是IntelliJ IDEA，装了sdkman之后，IDE里仍然需要手动把Project SDK指向sdkman安装的JDK路径，sdkman本身不会自动配置IDE。路径一般是~/.sdkman/candidates/java/17.0.9-tem，你可以在IDE的Project Structure里添加这个路径。这里有个小技巧：如果项目目录里有.sdkmanrc，你可以在**.idea/misc.xml**里配置project-jdk-name字段，让IDE也跟随项目的JDK要求，但更省事的做法是在IDEA的SDK列表直接选择17.0.9-tem这个具体目录，同时保证Terminal插件里的Shell环境正确加载了sdkman。Eclipse用户也是在Installed JREs中手动添加路径，原理相同。
6. 实战案例：一套终端搞定JDK 8/11/17/21与多工具链
6.1 在一台机器同时维护四种JDK
我用一台16GB内存的MacBook Pro做过一个典型的多环境搭建：线上老服务是JDK 8，一个中台项目是JDK 11，新微服务项目是JDK 17，实验环境想跑JDK 21的新语法特性。这套环境如果用手动管理，光想一下都头大，但sdkman只需要四条安装命令：
bash复制sdk install java 8.0.392-tem
sdk install java 11.0.21-tem
sdk install java 17.0.9-tem
sdk install java 21.0.1-tem
安装完毕后，我把默认版本设为JDK 17（日常主力），需要切其他版本时用use或.sdkmanrc。经过一段时间实测，这套方案的稳定性完全没问题，唯一要注意的是磁盘空间：四个JDK加起来约1GB左右，对于现在的电脑来说不算大，但如果你还装一堆其他发行版，就得留心了。
6.2 多项目目录自动切换演示
假设我的工作目录下有两个项目：legacy-order用JDK 8，cloud-gateway用JDK 17。我会在这两个目录下分别创建.sdkmanrc：
bash复制cd ~/work/legacy-order && sdk env init
# 确保文件内容是 java=8.0.392-tem
cd ~/work/cloud-gateway && sdk env init
# 确保文件内容是 java=17.0.9-tem
然后把sdkman_auto_env=true写进~/.sdkman/etc/config。这样每次打开终端，在legacy-order里跑java -version自动是JDK 8，在cloud-gateway里自动是JDK 17。Maven、Gradle构建时也是跟着JDK走的。
有朋友问过我这套方案和mvnw（Maven Wrapper）的区别，其实两者是互补关系。mvnw锁定的是Maven版本和Maven的JDK要求，但它不能直接帮你切换整机的JAVA_HOME；而sdkman的.sdkmanrc是整个Shell环境的JDK切换。如果你在一个项目里既用了.sdkmanrc又用了mvnw，那体验是最完美的——目录一进JDK就切好，构建也用项目指定的Maven版本和JDK标准。
6.3 工具链版本同步管理示例
Java生态的工具链经常和JDK版本有依赖关系。例如Spring Boot 3.0要求JDK 17+，而老的Spring Boot 2.x通常用JDK 8或11。我常见的一个项目组合是：JDK 17 + Maven 3.9.6 + Spring Boot CLI 3.2.x，以及另一个项目组合JDK 8 + Maven 3.6.3 + Gradle 6.9.x。手动管理这种组合简直是一场灾难。
用sdkman就变成了这样：
bash复制sdk install maven 3.9.6
sdk install springboot 3.2.5
sdk install gradle 6.9.4
然后靠use命令或者.sdkmanrc进行切换。这里要注意的是：工具链版本切换不会自动切换JDK版本，两者是独立的。如果你想在切换工具链的同时也切换JDK，可以参考下面的Shell脚本封装：
bash复制alias j8='sdk use java 8.0.392-tem'
alias j11='sdk use java 11.0.21-tem'
alias j17='sdk use java 17.0.9-tem'
alias j21='sdk use java 21.0.1-tem'
把这几个alias放进~/.zshrc或~/.bashrc，以后切换就变成输入j17这个命令。这个“别名切换法”虽然不如自动切换优雅，但在某些临时场景确实更快。
6.4 在CI/CD环境中使用sdkman的思路
如果你的构建环境是自托管的GitLab Runner或者Jenkins节点，也可以把sdkman的用法迁移过去。CI流程里，通常一台构建机需要跑多个项目的构建，每个项目要求的JDK版本不同。用sdkman就可以在构建脚本里动态切换：
bash复制source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk use java 17.0.9-tem
mvn clean package
有些构建机为了方便还会专门创建一个build账户并预装好sdkman及常用JDK版本，这样每个项目构建前只需执行一行source加一行sdk use，比维护多台专用构建机灵活得多。这里有一个经验：CI里每个项目最好显式指定完整版本号，不要用模糊匹配，因为CI环境是自动化的，模糊匹配容易导致某天sdkman更新了默认发行版，你的构建就悄悄换了JDK，非常难排查。
7. 常见问题与排查技巧实录
7.1 “sdk: command not found”是什么原因？
这个问题是最常见的。如果你是刚装完sdkman后立即执行sdk version，多半是还没source初始化脚本，按前面说的执行：
bash复制source "$HOME/.sdkman/bin/sdkman-init.sh"
如果重新打开终端后依然报“command not found”，需要检查你的Shell配置文件。比如zsh用户需要确认~/.zshrc里有：
bash复制#THIS MUST BE AT THE END OF THE FILE FOR SDKMAN TO WORK!!!
[[ -s "$HOME/.sdkman/bin/sdkman-init.sh" ]] && source "$HOME/.sdkman/bin/sdkman-init.sh"
这行代码正常情况下安装时自动写好了。如果缺失，手动补上即可。这类问题通常是你机器上曾经装过旧版sdkman，后来清理时不干净，或者Shell配置文件权限异常导致初始化脚本没被加载。
7.2 切换版本后java命令不生效怎么办
这种情况八成是PATH优先级问题。sdkman把~/.sdkman/candidates/java/current/bin加到PATH最前面，但如果你在~/.zshrc或~/.bashrc里又写了export JAVA_HOME=/usr/lib/jvm/...或export PATH="/usr/local/opt/openjdk/bin:$PATH"，这些路径可能在sdkman的前面，导致java命令被“劫持”。
排查方式如下：
bash复制which -a java
这条命令会列出所有PATH里能找到的java命令及顺序。如果第一行不是~/.sdkman路径，就说明有别的JDK路径抢先了。解决办法是把sdkman初始化代码移到Shell配置文件的最后，保证它的PATH注入发生在其他配置之后。另外还要注意，JAVA_HOME可能被项目里的/etc/profile.d或IDE启动脚本覆盖，如果终端正常但IDEA里不对，看看IDEA的Run Configuration里是否硬编码了JAVA_HOME。
7.3 安装版本时下载很慢或卡住
sdkman默认从https://api.sdkman.io/2获取版本元数据，从各发行版的官方源下载压缩包。国内或者企业内网访问这些源可能不稳定。我在某次网络状况不好的环境下也遇到过下载JDK卡了半天不动的窘境，解决方式是：
- 给
~/.sdkman/etc/config里设置代理，例如http_proxy和https_proxy环境变量，sdkman会遵循系统的代理设置。 - 如果只是想提高下载速度，可以使用SDKMAN_CANDIDATES_API切换镜像：
bash复制export SDKMAN_CANDIDATES_API=https://api.sdkman.io/2
export SDKMAN_CANDIDATES_DIR=$HOME/.sdkman
如果还是慢，就把压缩包手动下载后放到~/.sdkman/archives/按前面说的离线安装方式处理。这里特别提醒一下：不要随意修改SDKMAN_CANDIDATES_API为来路不明的地址，因为版本信息是从该地址获取的，改到不安全的源有安全风险。
7.4 已安装版本在list里显示但current找不到
这是比较隐蔽的一种状态，多半是软链接损坏了。你可以先看：
bash复制ls -l ~/.sdkman/candidates/java/
正常情况下应该有一个current目录。如果current不存在或者指向一个不存在的版本目录，手工修复：
bash复制ln -s ~/.sdkman/candidates/java/17.0.9-tem ~/.sdkman/candidates/java/current
需要说明的是这种情况我遇到过两次，一次是磁盘空间满导致解压不完整，另一次是我手动删除了某个版本目录但没有用sdk uninstall。所以我的建议是：管理SDK版本时尽量只用sdkman自己的命令，不要手动去candidates目录里删文件，除非你已经明确知道后果。
7.5 自动切换失效或.sdkmanrc不被识别
auto_env功能失效时，首先确认配置文件里的开关：
bash复制grep sdkman_auto_env ~/.sdkman/etc/config
必须输出sdkman_auto_env=true。如果这个配置没问题，大概率是Shell插件冲突。我有一次用zsh的chpwd钩子覆盖了sdkman的目录监听逻辑，导致自动切换怎么都不触发。解决方式是检查~/.zshrc里有没有其他自定义的chpwd函数，把sdkman的初始化放在最后即可。有条件的可以降级排查，先开一个干净的bash窗口测试自动切换是否正常，如果在bash里正常、zsh里不正常，那就能确定问题出在zsh的插件或钩子层面。
7.6 常见问题速查表
| 症状 | 可能原因 | 快速排查 | 解决思路 |
|---|---|---|---|
| sdk: command not found | 初始化脚本未加载 | echo $SDKMAN_DIR |
source初始化脚本或补全配置 |
| java命令仍是旧版本 | PATH顺序冲突 | which -a java |
调整Shell配置顺序，移除旧JDK路径 |
| 下载JDK卡住 | 网络源不稳定 | 查看进度，测试官网连通性 | 配置代理或离线安装 |
| current软链接失效 | 手动删除了版本目录 | ls -l ~/.sdkman/candidates/java/ |
用sdk uninstall规范删除，修复软链接 |
| 自动切换不工作 | 配置或Shell钩子冲突 | 确认auto_env=true，测试bash |
检查zsh插件冲突，调整初始化位置 |
| 新版本下载到一半失败 | 磁盘空间不足 | df -h |
清理旧版本，释放空间后重新install |
7.7 我的一些额外经验
最后再分享几个长期使用sdkman过程中的实用习惯。第一，每台机器都配上sdk selfupdate的自动更新，这样新JDK版本发布后你很快就能在sdk list里看到，不用等到项目要求你升级时现学现卖。第二，不要装太多用不到的版本，我见过有人一台机器上装了20多个JDK，结果自己都记不清哪个项目用哪个，反而乱了。合理做法是装2-4个常用版本，其他的用时再装，装也就一两分钟的事。第三，团队内部统一约定.sdkmanrc的版本格式，把类似java=17.0.9-tem这样的配置作为仓库的一部分提交上去，新同事入职后克隆代码、安装sdkman、进入目录自动环境就绪，省下大量的“你先装个JDK 8，不对是另一个版本”的沟通成本。
我现在的工作机上，sdkman管理着JDK 8、11、17、21四套版本，外加Maven、Gradle、Spring Boot CLI、Kotlin，日常开三个终端同时处理不同项目的需求，再也没出现过“环境切崩了”的情况。这套方案对我的价值就是：它把“环境管理”从一项需要集中注意力的手工劳动，变成了一件自动化、可复现、可提交到Git仓库的常规事务。如果你还在手动改环境变量，或者总是担心新项目要的JDK版本会影响旧项目编译，那我真的建议花十分钟试一下sdkman，它大概率会成为你Java开发工具箱里长期保底的那个工具。