最近一个同事的项目在启动时抛了UnsupportedClassVersionError，折腾了小半天，最后发现是 JDK 版本没对上：他本机默认java是 21，而项目里某个依赖是用 8 编译的，运行环境一换直接字节码不兼容。这种问题在 Mac 上做 Java 开发几乎是人人都会撞上的事，原因也很简单——Mac 上可以同时装好几个 JDK，但系统默认用的往往是最后装的那个，版本切换全靠口口相传的“玄学操作”。
今天这篇文章就把“Mac 如何切换 JDK 版本”这件事彻底拆开。我会从 JDK 的安装路径、系统自带的java_home机制讲起，再给出手动 alias 切换、jenv 管理两种实操方案，最后把 IDEA、Maven、DBeaver 这些工具的联动配置和常见报错排查一并说清楚。无论你是刚入门的 Java 新手，还是被多项目版本折磨的老手，这套内容应该能帮你少踩很多坑。
1. 为什么 Mac 开发者需要 JDK 版本自由切换
1.1 一次真实的版本混乱现场
先说说我自己遇到的一个典型现场。早几年我在维护一个老旧的 Spring Boot 项目时，本地开发环境装的是 JDK 8，但另一个新项目要求 JDK 17。两个项目经常要并行开发，我当时不知道有切换工具这回事，就采取了一个很笨的办法：用哪个项目就手动改/etc/profile里的JAVA_HOME，改完还要重新登录终端，搞得很崩溃。
后来换到新电脑，我决定一次性装好 JDK 8、11、17、21 四个版本，结果新的麻烦又来了。因为安装顺序靠后的 JDK 会自动写入/Library/Java/JavaVirtualMachines/并成为系统默认，而有些老项目需要 JDK 8 才能正常编译，我每次都要去“系统设置”里翻找 Java 配置面板，或者重新安装旧版 JDK 来覆盖默认值，既费时间又容易出错。
这种混乱的本质是：macOS 上 JDK 的“存在”和“默认生效”是两回事。你可以同时装很多个 JDK，但最终java命令指向哪一个，取决于JAVA_HOME环境变量和系统路径的优先级。谁没搞清楚这个机制，谁就永远在“装完又卸、卸完又装”的循环里打转。
1.2 哪些人真的需要多版本并存
不是所有人都需要折腾多版本 JDK。如果你只是自己写写单模块项目、用最新 LTS 版本就够了，那完全没必要装多个 JDK，直接固定用 JDK 17 或 21 就行，省心。
但下面这几类人，多版本并存几乎是刚需：
- 同时维护多个公司项目或开源项目的开发者，不同项目锁定的 JDK 版本不同。
- 用 Gradle、Maven 等构建工具构建老项目的场景，老插件可能不兼容新版 JDK。
- 做中间件或框架二次开发的人，比如自己在本地跑 Elasticsearch、Tomcat、Hadoop 这些对 JDK 版本有硬性要求的组件。
- 学习者在看不同版本的教程时，教程用了 JDK 8，而自己电脑只装了 JDK 21，编译选项、模块系统等差异会带来额外干扰。
以我个人的经验，只要你有两个以上“必须本地运行”的项目，就值得花半小时配置一套可靠的切换方案。这半小时投入换来的是之后每次切换都只要一条命令。
1.3 先说结论：三种主流切换方案怎么选
目前 Mac 上主流的 JDK 版本切换方案有三类，我先把结论放在前面，后面再逐个展开：
| 方案 | 原理 | 适合人群 | 需要额外安装 |
|---|---|---|---|
手动修改.zshrc中的JAVA_HOME | 每次手动 export 环境变量 | 只装 1-2 个 JDK，偶尔切换 | 否 |
| alias 快速切换 | 在.zshrc中定义多个别名，一条命令切换 | 需要频繁切换，但不追求项目管理 | 否 |
| jenv 管理工具 | 类似 pyenv，支持目录级、全局级版本切换 | 多项目并行、希望自动化切换 | 是 |
| SDKMAN | 类似 jenv，但更侧重 JDK 本身的安装和版本管理 | 喜欢一体化工具链的人 | 是 |
如果你只是偶尔切一下，alias 方案完全够用，这也是本文实操部分第一个要讲的。如果你有多个项目要并行维护，希望进入某个目录就自动使用对应 JDK 版本，那么 jenv 会更顺手。SDKMAN 也很好用，但它更像是一个“全家桶”式的环境管理器，有些人不喜欢它额外生成一堆Shell函数，所以本文不重点展开。
2. 装好几个 JDK：从官方包到 Homebrew 的完整姿势
2.1 先看清你的 Mac 芯片和 macOS 版本
在动手安装之前，有两件事必须先确认，否则后面很容易出现“明明装了 JDK 却找不到”的问题。
第一是 Mac 的芯片架构。Apple Silicon（M1、M2、M3 系列）和 Intel 芯片的安装路径不同，Homebrew 的默认安装路径也不同。Apple Silicon 的 Homebrew 默认装在/opt/homebrew/，而 Intel Mac 的 Homebrew 装在/usr/local/。这个路径差异会直接影响你后续配置环境变量。
第二是 macOS 版本。/usr/libexec/java_home这个命令在 macOS 10.9 之后的系统里都是自带的，如果你的系统版本较老，建议先升级到当前主流版本（macOS 11 以上）。另外，从 JDK 9 开始，Oracle 官方安装包的安装方式也变了，很多老教程里双击 pkg 的流程已经不完全适用。
确认方法很简单：
uname -m # 输出 arm64 表示 Apple Silicon，x86_64 表示 Intel sw_vers # 查看 macOS 版本2.2 方式一：官方 pkg 安装包
最直接的方式是去 Oracle 官网或 Adoptium 官网下载对应平台的 pkg 安装包。以 Adoptium（Eclipse Temurin）为例，下载页面会提供 macOS 平台的.pkg文件，双击安装后，JDK 会自动放入/Library/Java/JavaVirtualMachines/目录下。
比如你下载了 Temurin 17 的 pkg 并安装，最终目录会是：
/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home这个路径就是 JDK 的JAVA_HOME。用这种方式安装的 JDK 会自动注册到系统 Java 目录里，之后用/usr/libexec/java_home -V就能看到它，这也是推荐用 pkg 安装包的原因——省去手动注册的麻烦。
2.3 方式二：Homebrew cask 与 formula 的区别
很多人在 Mac 上喜欢用 Homebrew 装东西，但在这里有一个关键区别要讲清楚：Homebrew 安装 JDK 有两种方式，一种是 cask，一种是 formula，名字上很像，行为却差很多。
cask 方式：
brew install --cask temurin17 brew install --cask temurin8这种方式本质上是帮你把官方 pkg 安装包跑一遍，JDK 同样会进入/Library/Java/JavaVirtualMachines/，系统能自动识别，和官网下载安装没有本质区别。
formula 方式：
brew install openjdk@17 brew install openjdk@21这种方式装的是 Homebrew 自己维护的 openjdk 构建，而且不会自动放入/Library/Java/JavaVirtualMachines/，而是放在 Homebrew 的 opt 目录里，例如：
/opt/homebrew/opt/openjdk@17 # Apple Silicon /usr/local/opt/openjdk@17 # Intel如果你用java_home -V查看，是看不到这种 JDK 的，还是要手动链接或者直接引用路径。很多人在这一步迷糊，是因为按网上教程装了openjdk@17后，终端里怎么都找不到这个版本。
我的建议是：如果你不是特别在意“纯净的官方构建”，直接用 cask 安装 Temurin 或 Liberica 会更省事。如果只能用 formula，请记住它不会自动注册，需要手动告诉系统路径。
2.4 安装后必查：JDK 到底被放到了哪里
无论你用什么方式安装，装完以后第一件事就是验证 JDK 是否被系统正确识别。运行：
/usr/libexec/java_home -V这个命令会列出当前系统里所有注册过的 JDK。如果某个 JDK 没出现在列表里，说明它没有被正确注册，后续就算配了环境变量也可能出现各种找不到版本的问题。
另外，确认每个版本的路径是很关键的。你可以在终端里逐个查看：
/usr/libexec/java_home -v 17 /usr/libexec/java_home -v 1.8输出类似/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home或/Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home。把这个路径记下来，后面的所有配置都是围绕它展开的。
3. 切换的核心机制：JAVA_HOME、PATH 和 java_home 命令
3.1 谁在读取 JAVA_HOME
版本切换的本质，是控制操作系统里java、javac这些命令实际指向的 JDK。而控制这一切的关键，就是JAVA_HOME环境变量和PATH环境变量。
JAVA_HOME是一个约定俗成的环境变量，它告诉运行在 JVM 之上的工具（比如 Maven、Gradle、Tomcat、IDEA 启动器等）应该去哪个 JDK 目录找可执行文件。而PATH里的$JAVA_HOME/bin决定了你在终端直接敲java -version时用的是哪一个。
这两个变量必须一致，否则就会出现经典的“终端 java 是 17，但 Maven 用的却是 8”这种怪异现象。所以我后面所有切换操作，都会同时设置JAVA_HOME和PATH。
有一点很多人会忽略：PATH的优先级不是唯一的。如果PATH中/usr/bin/java排在$JAVA_HOME/bin之前，那么即使JAVA_HOME改了，java命令仍然可能走系统的旧版本。这就是为什么只改JAVA_HOME有时候并不生效。
3.2 /usr/libexec/java_home 才是 macOS 原生的“版本选择器”
macOS 自带了一个/usr/libexec/java_home命令，它可以从系统注册的 JDK 列表里，按版本号返回对应的JAVA_HOME路径。
这个命令有几个很实用的参数：
java_home -V # 列出所有 JDK java_home -v 17 # 返回 17 版本 JDK 的路径 java_home -v 1.8 # 返回 JDK 8 的路径 java_home --arch arm64 # 按架构筛选它最大的价值在于：不依赖你自己记忆路径。即使是 JDK 版本升级（比如从17.0.5升到17.0.9），只要版本号主版本没变，命令返回的路径还是正确的，你不用手动去改.zshrc。
所以，我配置 alias 时，用的就是这种动态获取路径的方式，而不是写死某一个 JDK 的绝对路径。这能省掉很多升级后配置失效的麻烦。
还有一个常见误区：有人在.zshrc里写export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home，这样做本身没错，但如果 JDK 小版本升级后路径变了，这一行就失效了。用$(/usr/libexec/java_home -v 17)动态获取则一劳永逸。
3.3 .zshrc 配置中常见的引号大坑
写.zshrc的时候有一个细节非常容易踩坑，我特意单独拿出来说。
你的 shell 配置文件默认是~/.zshrc（macOS 从 Catalina 起默认 zsh）。正确的做法是使用单引号来包裹 alias 命令，因为单引号内的内容不会被展开，命令只在执行 alias 时才动态计算。
错误的写法是这样：
alias jdk17="export JAVA_HOME=$(/usr/libexec/java_home -v 17)"问题出在双引号：$(...)在打开终端加载.zshrc的时候就被执行了一次，之后这个 alias 里的JAVA_HOME路径就被固定死了。如果后来你的 JDK 升级导致路径发生变化，这个 alias 就失效了，而且排查起来很隐蔽。
正确的写法是把等号后面的命令整体放进单引号：
alias jdk17='export JAVA_HOME=$(/usr/libexec/java_home -v 17)'这样每次执行jdk17这条命令时，才会动态去获取最新的 17 版本路径。
4. 不用额外工具：alias 手动切换 JDK 版本的完整实操
4.1 第一步：运行 java_home -V 确认本机版本
打开终端，先运行：
/usr/libexec/java_home -V输出大概长这样：
Matching Java Virtual Machines (3): 21.0.3 (x86_64) "Eclipse Temurin" - "OpenJDK 21.0.3" /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home 17.0.11 (x86_64) "Eclipse Temurin" - "OpenJDK 17.0.11" /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home 1.8.0_412 (x86_64) "Eclipse Temurin" - "OpenJDK 8.0.412" /Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home确认你需要切换的版本都在列表里。如果某个版本没出现，先别急着配置，回到第 2 节把安装方式调整好。
这里我建议把输出里的主版本号记下来，比如17、21、1.8。java_home -v后面支持的参数，就是这种格式。
4.2 第二步：写 alias 到 .zshrc
编辑~/.zshrc，在文件末尾加入：
# JDK 版本切换 alias alias jdk8='export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) && export PATH="$JAVA_HOME/bin:$PATH" && java -version' alias jdk11='export JAVA_HOME=$(/usr/libexec/java_home -v 11) && export PATH="$JAVA_HOME/bin:$PATH" && java -version' alias jdk17='export JAVA_HOME=$(/usr/libexec/java_home -v 17) && export PATH="$JAVA_HOME/bin:$PATH" && java -version' alias jdk21='export JAVA_HOME=$(/usr/libexec/java_home -v 21) && export PATH="$JAVA_HOME/bin:$PATH" && java -version'这里有一个细节我要解释一下：export PATH="$JAVA_HOME/bin:$PATH"为什么一定要把$JAVA_HOME/bin放在$PATH前面？因为系统路径/usr/bin里可能也有java，如果它排在前面，你敲java命令用的就还是旧版。前置之后，$JAVA_HOME/bin里的java就会优先被找到。
写完保存后，执行：
source ~/.zshrc4.3 第三步：验证切换是否生效
现在来验证。在终端里输入：
jdk17如果一切正常，你会看到类似openjdk version "17.0.11"的输出，说明JAVA_HOME和PATH已经切换成功。再执行：
java -version javac -version echo $JAVA_HOME这三条命令的输出应该指向同一个版本。如果java和javac版本不一致，说明PATH的优先级还有问题，或者你没有执行source ~/.zshrc。
这个方法的核心优势是简单、透明、没有额外依赖。但它的缺点也很明显：一切靠手动，你进入不同项目目录时还得自己记住要切换哪个版本，忘了就会出错。如果你同时维护的项目多，建议往下看 jenv 方案。
5. 进阶玩法：jenv 实现智能 JDK 版本管理
5.1 安装 jenv 并完成初始化
jenv 是 Mac 上管理 JDK 版本的常用工具，思路和 Python 的 pyenv 类似。它本身不负责下载 JDK，而是把自己变成一个“转发器”：你把系统里已经装好的 JDK 注册给它，然后由它决定在某个目录下使用哪个版本。
安装方式很简单，前提是你已经装好了 Homebrew：
brew install jenv然后配置 shell 初始化。在~/.zshrc末尾加入：
export PATH="$HOME/.jenv/bin:$PATH" eval "$(jenv init -)" export JAVA_HOME="$HOME/.jenv/versions/$(jenv version-name)"这里要注意最后一行export JAVA_HOME的作用是让所有读取JAVA_HOME的工具（比如 Maven）都能拿到 jenv 当前选中的版本。很多人装了 jenv 但发现 Maven 不生效，就是因为缺少这一行。
保存后执行：
source ~/.zshrc5.2 把 JDK 版本注册进 jenv
接着把 JDK 注册到 jenv。回到第 2 节记下的 JDK 路径，逐个添加：
jenv add /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home jenv add /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home jenv add /Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home每执行一条，jenv 会输出类似17.0 added的提示。全部添加完后，用下面的命令确认列表：
jenv versions输出中带星号的表示当前全局生效的版本。如果你在注册时发现版本号被识别成17.0这种带小版本的格式，而你希望用17来称呼它，可以建一个别名：
jenv alias 17 17.05.3 全局、目录、临时三种切换级别
jenv 最吸引人的地方，是它支持三种不同粒度的切换方式：
全局切换（所有目录默认生效）：
jenv global 17目录级切换（进入某个目录自动生效）：
在项目根目录下执行：
jenv local 21这会在当前目录生成一个.java-version文件，里面写着21。之后你在这个目录里打开终端、运行 Maven/Gradle，jenv 都会自动把 JDK 切换到 21。离开这个目录，全局版本不受影响。
临时切换（只在当前终端会话生效）：
jenv shell 8关闭当前终端窗口后失效。日常开发最常用的是global和local。我自己的习惯是：全局固定在最新的 LTS 版本，老项目单独用jenv local锁定旧版本，这样既不会影响新项目，也不会因为忘记切换而出现老项目跑不起来的问题。
6. IDE 与构建工具的 JDK 联动配置
6.1 IntelliJ IDEA 的 Project SDK 设置
终端切好了并不代表一切就绪，因为 IDEA 有自己的一套 JDK 管理机制，它不完全跟随系统环境变量。
在 IDEA 里，依次打开File -> Project Structure -> Project，右侧的SDK下拉框可以切换当前项目的 JDK。如果你的某个 JDK 不在列表里，点击Add SDK -> JDK，手动选择对应的 JDK Home 路径即可。
这里有一个实用技巧：IDEA 的Project SDK只决定 IDEA 编译这个项目时用的 JDK，而项目的 Maven importer和Runner也可能单独指定 JDK。如果你的项目依赖是通过 Maven 导入的，还建议去Settings -> Build, Execution, Deployment -> Build Tools -> Maven -> Importing，把 “JDK for importer” 设置成和 Project SDK 一致。否则会出现“IDEA 里显示的是 JDK 17，但 Maven 重新导入后依赖报错”的怪异问题。
6.2 Maven 跑起来用的是哪个 Java
Maven 使用的 JDK 和终端配置有很强的关联性。如果你在终端执行mvn -version，输出里有这样一行：
Java version: 17.0.11, vendor: Eclipse Adoptium, runtime: /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home这表示 Maven 当前用的是哪个 JDK。它会读取JAVA_HOME环境变量，所以只要你的 alias 或 jenv 方案正确设置了JAVA_HOME，Maven 通常也会跟着切。
但有一个容易忽略的场景：在 IDEA 里运行 Maven 命令时，IDEA 会优先使用Maven -> Runner -> JRE中指定的 JDK，而不是JAVA_HOME。因此，如果你在 IDEA 的 Maven 面板里跑clean package，发现编译版本不对，请去检查这个设置项，把它改成和项目 SDK 一致。
6.3 DBeaver、Tomcat 等周边工具的 JDK 指定
DBeaver 这类数据库客户端、Tomcat 等中间件，它们启动时也会寻找 JDK。DBeaver 默认使用系统JAVA_HOME，但如果你在 DBeaver 里连接老版本的数据库驱动，偶尔会遇到“Driver class not found”之类的异常，本质是驱动版本和 JDK 不兼容。
这些工具一般允许在启动配置里指定-vm参数。以 DBeaver 为例，编辑安装目录下的dbeaver.ini，加入：
-vm /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home/bin这个方法同样适用于 Eclipse 系的其他工具。Tomcat 的话，是在catalina.sh或启动脚本里设置JAVA_HOME。现在用一个固定路径指定是很常见的手段，这里要提醒大家：Tomcat 老版本对新 JDK 的模块访问权限有额外要求，如果启动报模块错误，除了换 JDK，也需要在catalina.sh里加--add-opens参数，不过这两个方向别混淆。
7. 高频报错排查：切换 JDK 版本时最容易踩的坑
7.1 java 与 javac 版本不一致
这是最典型的“切了但没完全切”的症状：java -version显示的是新版本，javac -version却还是旧版本。
原因通常是PATH中同时存在多个 JDK 的bin目录，而java和javac可能来自不同的目录。比如java在/usr/bin下找到了，而/usr/bin/java可能是系统自带的老版本，javac却从$JAVA_HOME/bin找到了新版。
排查方法：
which java which javac看这两个命令分别指向哪里。如果指向/usr/bin/java，说明你的PATH里$JAVA_HOME/bin没有排在最前面。先执行echo $PATH检查顺序，再回头检查 alias 里的export PATH="$JAVA_HOME/bin:$PATH"是否写对。
7.2 jenv 提示 version not defined
使用 jenv 时常见的报错是：
jenv: version `17' is not defined (or in current dir .java-version)这个报错说明当前目录下的.java-version文件指定的版本没有被 jenv 识别。一般有两种可能：一是你还没有执行jenv add注册对应 JDK；二是注册后没有重新加载 shell。
解决办法是回到第 5 节，先jenv add对应路径，再jenv rehash刷新，然后重新打开终端或者source ~/.zshrc。
7.3 UnsupportedClassVersionError 与 ClassNotFoundException
UnsupportedClassVersionError的意思是：你要运行的 class 文件编译版本高于当前 JVM 支持的最高版本。比如 class 文件是 Java 17 编译的，但当前 JVM 是 JDK 8，就会报这个错。
解决办法很直接：把 JDK 切到高于或等于编译版本的那个版本。如果编译版本是 11，那就用 11 或更高；但要注意老项目可能同时用了--release参数，版本切太高也可能出现其他兼容性问题。
ClassNotFoundException则是另一个方向的问题，常见于依赖没有正确加载。这种报错和 JDK 版本切换没有直接关系，但切换 JDK 后可能触发 Maven 依赖重解析，如果某依赖只在特定 JDK 版本下才解析成功，就会表现出“切换后突然找不到类”。建议先mvn clean install重新构建，再看是否真的和版本切换相关。
7.4 切换后新终端窗口不生效
很多人在终端里执行 alias 或 jenv 切换成功了，但一打开新的终端窗口，版本又变回原样。这个问题在大学里被问过无数次。
原因只有一个：.zshrc没有被正确加载，或者你的配置文件写在了.bash_profile里，而当前 shell 是 zsh。Mac 从 Catalina 开始默认 shell 就是 zsh，读取的是~/.zshrc，不是 Bash 的~/.bash_profile。
检查方法：
echo $SHELL如果输出/bin/zsh，那你所有的配置都应该写在~/.zshrc里。写完以后，新终端会自动执行这个文件；如果你想让当前终端立即生效，就手动执行source ~/.zshrc。
7.5 常见问题速查表
| 问题现象 | 直接原因 | 推荐动作 |
|---|---|---|
java与javac版本不一致 | PATH顺序混乱 | 检查which java，确保$JAVA_HOME/bin在最前 |
| 新终端窗口不生效 | 配置写在错误的文件 | 确认 shell 是 zsh，配置写入~/.zshrc |
| jenv 找不到版本 | 未注册或未 rehash | jenv add后再jenv rehash |
| 终端版本对，IDEA 不对 | IDEA 有独立 SDK 配置 | 在 Project Structure 和 Maven 配置中分别设置 |
| Maven 编译版本不对 | Runner JRE 未同步 | 修改 IDEA 中 Maven Runner 的 JRE 设置 |
| alias 里版本写死 | 使用了双引号 | 改为单引号，让$(/usr/libexec/java_home)动态执行 |
JDK 安装后java_home -V找不到 | 安装路径未注册 | 改用 cask 或官方 pkg 安装，避免裸用 formula |
最后再分享一个我个人的小习惯：我给常用 alias 命令加了提示语，比如jdk17执行后会直接显示当前生效的JAVA_HOME和java -version，省得每次切换完了还要再敲一行echo $JAVA_HOME去确认。另外，如果你也在用 SDKMAN，注意它和 jenv 不要同时启用，两套初始化逻辑会在JAVA_HOME上互相覆盖，曾经让我排查了整整一晚上。用一个顺手的工具，把它用透，比装一堆工具最后都不知道谁在生效要靠谱得多。
