1. 一个让团队反复翻车的问题JDK版本到底该怎么管干 Java 这行谁还没经历过这种场面某个项目在 A 机器上编译得好好的换到 B 机器上就报错。代码明明一行没改报错信息却指向UnsupportedClassVersionError或者 Gradle 疯狂提示“无法识别语言级别”。我见过太多次这种“在我机器上明明能跑”的闹剧绝大多数时候问题不在代码而在 JDK 版本没对齐。SDKMAN 就是为了解决这个问题出现的一款版本管理工具。它不直接提供 JDK 本身而是用一套 shell 命令统一处理 JDK以及 Maven、Gradle、Kotlin、Spring Boot 等几十种 SDK的安装、切换、卸载。我的很多项目需要同时兼容 Java 8 和 Java 17/21平时切换全靠 SDKMAN几秒钟就能完成再也不用在配置文件里来回注释。这篇博文主要适合三类人看一是刚接触 Java 生态、想搞清楚 JDK 怎么装怎么换的同学二是被多个项目 JDK 版本不一致折磨的上班族三是在团队里负责搭环境、想让新同事十分钟上线开发的工具人。我不会只给命令还会解释背后的目录结构和 PATH 机制这样遇到问题你自己能排查。1.1 手动管理 JDK 版本的本质问题先说说最原始的方案。去某个发行版官网下载压缩包解压到/usr/lib/jvm/jdk-17或者 macOS 的/Library/Java/JavaVirtualMachines然后在~/.bashrc或~/.zshrc里写export JAVA_HOME/usr/lib/jvm/jdk-17 export PATH$JAVA_HOME/bin:$PATH这种方法不是不能用而是不可持续。第一你的PATH上可能同时存在系统自带的 JDK、包管理器装的 JDK、手动解压的 JDK某个路径顺序不对java -version就会给你一个“惊喜”。第二切换版本等于手工改配置文件再 source操作繁琐且容易破坏原有配置。第三你在一台机器上改了默认版本可能会影响到别人正在跑的服务。多个项目共用一个开发机时这种静态切换简直是要吵架的节奏。更麻烦的是不同包管理器装的 JDK 路径完全不一样。这边 Homebrew 装在/opt/homebrew/opt/openjdk17那边 apt 装在/usr/lib/jvm/java-17-openjdk-amd64每次换机器就要重新找路径。这种“一个机器一套路径”的局面本身就是灾难。1.2 SDKMAN 解决的是“版本切换”这个核心问题SDKMAN 的思路和手工方案完全不同。它把所有的 SDK 版本统一放在~/.sdkman/candidates/目录里比如 JDK 的所有版本会放在~/.sdkman/candidates/java/下面每个版本一个子目录~/.sdkman/candidates/java/ ├── 11.0.24-tem ├── 17.0.12-tem └── 8.0.432-tem你执行sdk use java 17.0.12-tem时SDKMAN 并不是把文件搬来搬去而是把JAVA_HOME指向那个子目录同时把该子目录的bin放到PATH最前面。由于切换的是当前 shell 环境变量所以不同终端窗口完全可以各自持有不同的 JDK 版本。这种设计最大的好处是无侵入不修改系统文件不破坏已有安装所有内容都集中在用户目录下删掉~/.sdkman就等于完全卸载。SDKMAN 的管理范围也不止 JDK。执行sdk list可以看到它支持的完整候选列表里面包括 Gradle、Maven、Kotlin、Scala、Groovy、Spring Boot 等。也就是说你可以在同一个工具里把 Java 生态常用工具链的版本全部锁住。这也是它名字里那层“通用版本管理器”的底气。2. 安装与初始化从执行脚本到可用的完整链路2.1 安装前的环境检查SDKMAN 官方定位是类 Unix 环境下的工具macOS、Linux 和 Windows 的 WSL 都可以用。Windows 原生 CMD 和 PowerShell 不支持需要借助 Git Bash 或 WSL。安装前先确认几个基础命令是否可用which curl which zip which unzip echo $BASH_VERSION我见过几次安装失败不是脚本有问题而是环境里根本没有unzip。比如某些最小化安装的 Linux 服务器zip和unzip默认不带SDKMAN 安装后后续解压 JDK 就报错。用 apt 或 yum 补上unzip再跑安装脚本问题立刻消失。bash 版本也别太旧3.2 以下容易出现语法不兼容好在主流发行版基本都是 4.x 起步。网络方面安装脚本本身不下载太大内容真正的大头是后面安装 JDK。如果你的机器有全局代理或公司网络有特殊限制提前把http_proxy和https_proxy配好否则下载会一直卡在“Downloading…”。2.2 安装脚本与初始化配置官方推荐的安装方式是通过curl管道执行脚本curl -s https://get.sdkman.io | bash但我个人更建议把脚本先下载下来看一眼再执行。一是脚本更新频率并不低直接管道执行出了问题不好排查二是很多团队的内网开发机上curl 走代理拿到的不一定是最新内容。下载下来本地执行curl -s https://get.sdkman.io -o sdkman_install.sh bash sdkman_install.sh脚本执行完会在你的~/.bashrc或~/.zshrc末尾追加类似的内容#THIS MUST BE AT THE END OF THE FILE FOR SDKMAN TO WORK!!! export SDKMAN_DIR$HOME/.sdkman [[ -s $HOME/.sdkman/bin/sdkman-init.sh ]] source $HOME/.sdkman/bin/sdkman-init.sh注意那行注释写的“必须在文件末尾”。原因很简单sdkman-init.sh初始化时会修改PATH、定义一堆 shell 函数。如果你在这行之后又写了别的export JAVA_HOME或者export PATH就可能会把它建立的路径覆盖掉。这就是后续很多“切了没生效”问题的源头。刚安装完需要手动 source 一次才能在当前终端生效source $HOME/.sdkman/bin/sdkman-init.sh sdk version执行sdk version能正常输出版本号说明安装已经成功。新开一个终端后SDKMAN 的sdk命令会自动出现在 shell 里因为启动文件的 source 已经配好了。如果你用的是 zsh并且之前装过 zinit、oh-my-zsh 之类的框架请确认启动文件里的框架加载行和 sdkman 的 source 行不要互相覆盖。2.3 初始化失败的常见定位思路遇到过sdk: command not found别急着重装。先检查四件事echo $SDKMAN_DIR是否指向正确目录如果之前手动设置过这个变量可能会和默认值冲突。grep -n sdkman ~/.bashrc ~/.zshrc看 source 行是否存在且没有被注释掉。ls ~/.sdkman/bin/看看sdkman-init.sh是否真的存在。如果目录是空的说明安装脚本根本没跑完。如果装的是自定义 shell比如 fishSDKMAN 默认只支持 bash 和 zshfish 需要额外做兼容适配常见做法还是在 bash/zsh 里切。这里有个小概率的翻车点安装过程中断导致~/.sdkman目录残缺。此时重新执行安装脚本前最好先rm -rf ~/.sdkman清理干净否则新脚本可能因为目录已存在而跳过初始化。我踩过一次这个坑重装后sdk version一直报错最后把所有残留删除才解决。3. 高频命令实操JDK 的装、切、查、卸3.1 先学会看版本列表SDKMAN 管理 JDK 时版本标识符是自己发明的不是java -version输出的那种格式。执行sdk list java会输出一大张表列出发行商、标识符、安装状态。你只需要关注两列Identifier和Status。标识符格式类似17.0.12-tem、11.0.24-zulu前半段是版本号后半段是发行商缩写。常见后缀对应发行版特点temTemurin社区主流、兼容性好zuluZuluARM 平台表现好、有商业支持libericaLiberica JDK带 JavaFX 可选包graalvmGraalVM支持 Native ImageopenOpenJDK官方开源构建对于绝大多数业务开发Temurin 就够用。你不需要理解每个发行商的区别只要知道如果自己项目里有特定环境要求再根据表选择即可。Status 列里installed表示已装active表示当前正在使用。有时候你会看到版本列表里有17.0.12-tem和17.0.12-zulu这种同版本号不同后缀的条目它们可以共存互不影响。这对需要对比两个发行商在同一版本下行为差异的场景非常方便。3.2 安装指定版本安装命令很直接sdk install java 17.0.12-tem命令执行后SDKMAN 会从对应发行商拉取二进制包解压到~/.sdkman/candidates/java/17.0.12-tem然后询问是否把它设为默认版本。如果你安装的时候不想被打断交互可以在命令末尾加-y。也可以输入部分版本号sdk install java 17前提是17这个前缀刚好唯一匹配。如果匹配到多个候选SDKMAN 会列出匹配项让你选择或者干脆提示“Candidate version is ambiguous”。很多时候直接安装17.0.12-tem这种全量标识符更省心少一步判断。安装完成后SDKMAN 会自动创建一个未版本化的软链接目录~/.sdkman/candidates/java/current指向你当前激活的版本。这个current链接就是后续JAVA_HOME指向的目标。理解这一点很重要不是 SDKMAN 改一次 JDK 就物理删一个目录它只是把current这个“指针”移到另一个子目录上。3.3 默认版本、会话版本和临时执行版本这是整个工具使用频率最高的三个命令含义却经常被混在一起sdk default java 17.0.12-tem # 全局默认写入配置 sdk use java 17.0.12-tem # 仅当前 shell 会话生效 sdk exec java 17.0.12-tem -- java -version # 临时用指定版本跑一条命令default修改的是缺省值新开的终端都会用这个版本。use只影响当前终端进程不影响其他窗口也不影响重启后的设置适合临时切一下就不切回来的场景。exec最冷门但很实用比如你只想在指定 JDK 下跑某个构建命令不想改变任何当前环境sdk exec java 17.0.12-tem -- ./gradlew build我自己的使用习惯是default用来设定最常用的长期版本use用来应付临时测试exec用在 CI 或脚本里。为了确认生效可以执行java -version which java echo $JAVA_HOME当which java输出指向~/.sdkman/candidates/java/current/bin/java且JAVA_HOME指向~/.sdkman/candidates/java/current说明切换成功。3.4 卸载与磁盘占用卸载某个版本不需要手动删除目录sdk uninstall java 11.0.24-tem执行后会先确认再删除对应目录。等价写法是sdk rm。要查看当前生效的版本sdk current java如果想一次性看完所有已安装版本的状态可以把sdk list java的输出用grep过滤sdk list java | grep installed还有一个容易忽略的点SDKMAN 会把下载的压缩包留在~/.sdkman/archives/目录。这个目录平时不起眼但如果你安装过很多版本它可能占掉几个 G。确认不需要再次安装时可以清理ls -lh ~/.sdkman/archives/ rm -rf ~/.sdkman/archives/*.zip我一般会在季度例行清理时顺手看一下反正真正安装好的 JDK 已经在 candidates 目录里了压缩包留着只是占磁盘空间。4. 把版本锁进项目里团队协作才是终极目标4.1.sdkmanrc让项目自己声明 JDK 版本自己一台机器切版本已经很好用了但团队协作场景更需要的是“项目决定版本”而不是“个人决定版本”。SDKMAN 提供了.sdkmanrc文件机制。在项目根目录创建这个文件java17.0.12-tem手动写或者用命令生成sdk env initsdk env init会把当前默认版本写入.sdkmanrc。文件生成后进入项目目录执行sdk env install这条命令会把.sdkmanrc里声明但还没有安装的版本自动装好。如果已经齐全则执行sdk envSDKMAN 读取当前目录的.sdkmanrc把 shell 环境切换到对应版本。之后新开终端进入这个目录再补一次sdk env环境就对齐了。我把.sdkmanrc提交到 Git 仓库配合 CI 里的sdk env install整个团队用到的 JDK 版本就变成了一份可共享的配置。对比之前在文档里写“请安装 JDK 17具体地址见某某某”这种方式靠谱得多。这里有个细节.sdkmanrc不只可以声明 JDK还可以声明 Gradle、Maven 等工具版本。如果你的项目对构建工具版本也有严格要求完全可以一起锁住。我见过一些团队还手动维护“环境初始化文档”其实一个版本控制仓库里的.sdkmanrc就比文档更可靠因为它能被执行、能被 CI 复用。4.2 与 IDE 和构建工具的联动逻辑如果你用 IntelliJ IDEA导入项目时可以直接指定 Project SDK 指向 SDKMAN 目录里的版本。路径一般是~/.sdkman/candidates/java/17.0.12-tem。这样做的好处是 IDE 内部运行和终端命令保持一致。构建工具层面Gradle 提供了 Toolchain 机制可以在build.gradle里声明java { toolchain { languageVersion JavaLanguageVersion.of(17) } }Gradle 会自动在当前机器上查找匹配的已安装 JDK包括 SDKMAN 目录下的版本。找不到时会尝试自动下载但在受限网络下可能失败这时sdk env手动装好反而更稳。Maven 则用toolchains.xml指定 JDK 路径。如果你项目里用的是 Maven Wrapper 或 Gradle Wrapper它们负责的是构建工具本身的版本JDK 版本仍需要环境提供SDKMAN 在这里就补上了最后一块拼图。谈一点个人感受很多人以为装好 SDKMAN 就高枕无忧实际上 IDE 自己的设置、构建工具和 CI 节点三者是三个独立环节。SDKMAN 能统一的是本地开发机的 shell 环境IDE 需要你显式选择CI 则需要单独的安装步骤。把这几个地方都确认了才不会出现“本地编译通过流水线却挂掉”的尴尬。4.3 多项目并行开发时的真实体验同时维护多个项目时我习惯给每个项目开独立的终端窗口。窗口 A 执行sdk env切到 Java 8 的项目窗口 B 保持 Java 21 的环境。由于use和env只修改当前 shell互不干扰这比在全局环境里来回改彻底得多。有个细节要提醒如果你在某终端里执行过sdk default它会改变全局缺省值新开的终端窗口都会受到影响。所以建议把“设置默认版本”这个动作只做一次日常切换尽量走.sdkmanrc或use。否则新开终端时你可能会“莫名其妙”进入一个自己不预期的版本排查半天才发现是上次误操作改了 default。还有一个自动化小技巧可以在 shell 配置里绑定cd时自动执行sdk env这样每次进入带有.sdkmanrc的目录环境自动就绪。zsh 开启chpwd函数bash 则自己写cd()包装函数。不过我不太推荐所有人都这么干因为自动切换可能掩盖一些基于全局默认值的操作。手工敲一次sdk env的成本很低还能让你明确意识到环境变化的发生。5. 踩坑记录升级失效、PATH 冲突与离线环境处理5.1 SDKMAN 升级后命令失效的完整排查链路有段时间一执行sdk selfupdate升级 SDKMAN 后新开终端就提示sdk: command not found。表面上像是升级失败实际原因是升级过程会更新~/.sdkman/bin/下的脚本如果 shell 启动文件里 source 的位置有问题新终端加载时会找不到缓存文件。排查链路可以按这个顺序走type sdk which sdk echo $SDKMAN_DIR source ~/.sdkman/bin/sdkman-init.sh sdk version前两步确认命令是不是真的存在第三步确认目录变量第四步手动重新初始化。如果手动 source 后sdk version正常问题基本锁定在 shell 配置加载顺序。打开~/.zshrc检查 sdkman 的 source 行是否在文件末尾附近有没有被插件管理器覆盖。特别是装了 oh-my-zsh 的人如果 sdkman 行写在插件加载之前新增环境变量在后面被重置就会出现“明明装了却用不了”。解决方法很简单把 source 行移到文件最后即可。5.2 切换成功后 JAVA_HOME 被其他路径抢占另一个高频问题sdk use java 17后java -version输出的居然是旧的 8。这时候别怀疑 SDKMAN 没工作先执行echo $JAVA_HOME which -a java echo $PATHwhich -a java能列出 PATH 里所有能找到的 java。如果输出既有$HOME/.sdkman/candidates/java/current/bin/java又有/usr/bin/java那大概率是 PATH 中 sdkman 的路径不在最前面。常见罪魁祸首是 IDE 启动器、Docker 相关脚本或你手动往.zshrc里加的 export。还有一种情况你之前手动设过全局JAVA_HOME/Library/Java/JavaVirtualMachines/jdk8.jdk/Contents/HomeSDKMAN 切换只改了自身维护的变量你手动 export 的 JAVA_HOME 优先级更高于是 JDK 还是旧的。我给一个通用规则凡是涉及 JAVA_HOME 的配置统一交给 SDKMAN 维护自己不要额外写export JAVA_HOME。如果确实需要临时指向其他 JDK用sdk exec或sdk use不要和 SDKMAN 抢地盘。把这两类配置分开后我自己就再没遇到过“切了没生效”的怪事。5.3 慢网络与离线环境下的安装思路SDKMAN 在线安装 JDK 时本质上是从发行商的 CDN 拉取压缩包再进行解压和配置。网络环境不好时sdk install下载大包偶尔会非常慢甚至失败。sdk install本身没有断点续传重试一次就得重新下载体验不太好。我的替代思路是先用浏览器或下载工具把发行包下好再手动安排位置。比如从 Temurin 发布页下载对应压缩包解压后把目录放到~/.sdkman/candidates/java/17.0.12-tem/下然后执行ln -sfn ~/.sdkman/candidates/java/17.0.12-tem ~/.sdkman/candidates/java/current export JAVA_HOME~/.sdkman/candidates/java/current export PATH$JAVA_HOME/bin:$PATH但这种方式有个问题SDKMAN 的sdk list java不一定会识别手动放置的版本因为它靠解压后的元数据判断版本。如果你的环境离线和内网比较严格更稳妥的办法还是提前在能联网的机器上安装好然后整机拷贝~/.sdkman/candidates/java目录到目标机器对应位置最后手动 source。我在这块也只是提供经验方向限网环境里每个人的方案不太一样别指望一个方案能全场景照搬。5.4 与 Homebrew/apt 等包管理器共存时的规则同一台机器上同时存在 SDKMAN 和 Homebrew 之类的包管理器本身没有问题但 PATH 顺序一定要关注。Homebrew 安装 openjdk 通常会触发提示export PATH/opt/homebrew/opt/openjdk17/bin:$PATH如果这段代码写在 zshrc 里且位于 SDKMAN 的 source 之后那么java命令会优先命中 Homebrew 版本。想用 SDKMAN 版本要么删除 Homebrew 的环境变量配置要么把 SDKMAN 的 source 放到 Homebrew 那行之后。这里没有标准答案取决于你想让哪个工具接管。就我而言既然选择了 SDKMAN 管理 JDK系统里其他的 openjdk 就应该只保留给编译工具或系统组件用不让它进普通 shell 的 PATH。这样规则简单问题也就没了。提示无论你采用哪种组合请记住一个原则——同一时间内JAVA_HOME 和 java 命令必须指向同一个版本。很多人排查半天最后发现 java 是 A 版本、JAVA_HOME 却是 B 路径IDE 和终端表现完全不一致根源就是这两个变量脱节。关于坑其实还有最后一个常见情况在 CI 流水线里用 SDKMAN 安装 JDK每次拉一个全新环境如果流水线脚本里只执行了sdk install而没有先初始化sdk命令也会不存在。解决办法是在流水线里先 source~/.sdkman/bin/sdkman-init.sh再执行后续调用。这和我本地排查链路是同一个逻辑不初始化SDKMAN 的 shell 函数和环境变量就是空的。我个人实际使用 SDKMAN 已经很多年最省心的不是它帮我装了多少个 JDK而是它让“JDK 版本”变成一个项目属性而不再是个人记忆。你只要把.sdkmanrc提交进仓库任何机器都能在几分钟内复现完全一致的环境。如果你现在还在手工维护那个越来越臃肿的 PATH真的可以试试入坑成本很低退出成本更低——删掉~/.sdkman就回到原点了。