GeoXMind
博客

MacBook 标准 JDK 安装与多版本切换

#java #mac

文档定位：本文不是通用转载教程，而是作为当前 MacBook 的 Java 开发环境标准安装文档使用。
适用设备：当前 MacBook（Apple Silicon / arm64）。
默认 Shell：zsh。
标准主力版本：JDK 17。
适用技术栈：Java 17、Spring Boot 3、Maven、PostgreSQL、Vue + Vite 前后端分离项目。

1. 最终目标#

当前 MacBook 的 Java 环境按以下标准配置：

  1. 默认使用 JDK 17，作为 Spring Boot 3 和 Java 后端开发主力版本；
  2. 如需兼容历史项目，可额外安装 JDK 8、JDK 11；
  3. 不建议将 JDK 22、JDK 23、JDK 24 等非 LTS 版本作为日常主力版本；
  4. 当前 MacBook 为 Apple Silicon 架构，应下载 macOS ARM64 / aarch64 版本 JDK；
  5. 环境变量统一写入 ~/.zshrc；
  6. JDK 切换使用函数方式，不使用简单 alias；
  7. 不配置全局 CLASS_PATH；
  8. Maven 不单独绑定固定 JDK，统一跟随当前 JAVA_HOME。

2. 当前 MacBook 环境确认#

打开终端，执行以下命令：

bash
uname -m

当前 MacBook 应返回：

bash
arm64

说明当前设备为 Apple Silicon 架构，后续下载 JDK 时应选择：

text
macOS ARM64 / aarch64

继续确认当前 Shell：

bash
echo $SHELL

正常应返回：

bash
/bin/zsh

因此本机标准配置文件为：

bash
~/.zshrc

3. JDK 版本选择标准#

3.1 标准安装版本#

当前 MacBook 建议安装以下版本：

JDK 版本 是否安装 用途
JDK 8 可选 老项目、旧版 Spring、旧 Maven 项目兼容
JDK 11 可选 企业历史项目、过渡期项目兼容
JDK 17 必装 当前主力开发版本，适用于 Spring Boot 3
JDK 21 可选 新一代 LTS，作为后续升级储备

3.2 本机默认版本#

当前 MacBook 默认 Java 版本统一设置为：

text
JDK 17

原因：

  1. Spring Boot 3 要求 Java 17 及以上；
  2. Java 17 是长期支持版本，稳定性和生态兼容性更好；
  3. 企业后端项目、个人知识库平台、官网后台服务均可统一使用 Java 17；
  4. 可以减少多版本混用导致的 Maven、IDE、构建脚本问题。

4. 下载 JDK#

4.1 推荐下载来源#

当前 MacBook 推荐优先使用以下 OpenJDK 发行版之一：

  1. Eclipse Temurin JDK；
  2. Azul Zulu JDK；
  3. Microsoft Build of OpenJDK；
  4. Amazon Corretto JDK。

如项目或单位明确要求 Oracle JDK，也可以安装 Oracle JDK。

4.2 下载文件选择#

当前 MacBook 是 Apple Silicon，因此下载时必须选择：

text
macOS ARM64 DMG Installer

或：

text
macOS aarch64 DMG Installer

不要选择：

text
macOS x64 DMG Installer

除非设备是 Intel Mac。

5. 安装 JDK#

5.1 使用 DMG 安装包安装#

下载 .dmg 文件后，按以下步骤安装：

  1. 打开 Finder；
  2. 进入 Downloads；
  3. 双击 JDK 的 .dmg 安装包；
  4. 双击里面的 .pkg 安装程序；
  5. 按提示点击“继续”；
  6. 输入当前 MacBook 登录密码；
  7. 等待安装完成。

5.2 检查 JDK 安装目录#

安装完成后，在终端执行：

bash
cd /Library/Java/JavaVirtualMachines
ls

可能看到类似内容：

bash
jdk-17.jdk
jdk-11.jdk
jdk-1.8.jdk

也可能是不同发行版名称，例如：

bash
temurin-17.jdk
zulu-17.jdk
microsoft-17.jdk
amazon-corretto-17.jdk

实际目录名称以本机 ls 输出为准。

6. 查看本机 JDK 真实路径#

macOS 推荐使用 /usr/libexec/java_home 管理 JDK 路径。

查看所有已安装 JDK：

bash
/usr/libexec/java_home -V

示例输出：

text
Matching Java Virtual Machines (3):
    17.0.x (arm64) "Eclipse Adoptium" - "OpenJDK 17" /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home
    11.0.x (arm64) "Eclipse Adoptium" - "OpenJDK 11" /Library/Java/JavaVirtualMachines/temurin-11.jdk/Contents/Home
    1.8.0_xxx (arm64) "Eclipse Adoptium" - "OpenJDK 8" /Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home

查看 JDK 17 路径：

bash
/usr/libexec/java_home -v 17

查看 JDK 11 路径：

bash
/usr/libexec/java_home -v 11

查看 JDK 8 路径：

bash
/usr/libexec/java_home -v 1.8

7. 配置环境变量#

7.1 打开 zsh 配置文件#

执行：

bash
vi ~/.zshrc

如果不熟悉 vi，也可以用 VS Code 打开：

bash
code ~/.zshrc

如果 code 命令不可用，则使用：

bash
open -e ~/.zshrc

8. 当前 MacBook 标准 JDK 配置#

将以下内容添加到 ~/.zshrc 文件末尾。

bash
# ==========================================================
# Java / JDK Standard Config for Current MacBook
# Default JDK: 17
# Shell: zsh
# Architecture: Apple Silicon arm64
# ==========================================================

# Maven 可选配置：如本机已经单独安装 Maven，可取消注释并改成实际路径
# export MAVEN_HOME="$HOME/dev/apache-maven-3.9.6"
# export PATH="$MAVEN_HOME/bin:$PATH"

# 默认使用 JDK 17

# JDK 切换函数：比 alias 更稳定
function use_jdk() {
  local version="$1"

  if [ -z "$version" ]; then
    echo "Usage: use_jdk <version>"
    echo "Example: use_jdk 17"
    return 1
  fi

  local new_java_home
  new_java_home="$(/usr/libexec/java_home -v "$version" 2>/dev/null)"

  if [ -z "$new_java_home" ]; then
    echo "JDK $version is not installed on this MacBook."
    echo "Installed JDKs:"
    /usr/libexec/java_home -V
    return 1
  fi

  export JAVA_HOME="$new_java_home"

  # 清理 PATH 中已有的 JavaVirtualMachines JDK bin 路径，避免 java 命令仍指向旧版本
  export PATH="$(echo "$PATH" | tr ':' '\n' | grep -v '/Library/Java/JavaVirtualMachines/.*/Contents/Home/bin' | paste -sd ':' -)"
  export PATH="$JAVA_HOME/bin:$PATH"

  echo "Current JDK switched to: $version"
  echo "JAVA_HOME=$JAVA_HOME"
  java -version
}

# 常用快捷命令
function jdk8()  { use_jdk 1.8; }
function jdk11() { use_jdk 11; }
function jdk17() { use_jdk 17; }
function jdk21() { use_jdk 21; }

# 查看当前 Java 环境
function javainfo() {
  echo "JAVA_HOME=$JAVA_HOME"
  echo "java path=$(which java)"
  java -version
  echo ""
  echo "Installed JDKs:"
  /usr/libexec/java_home -V
}

9. 让配置立即生效#

保存 ~/.zshrc 后执行：

bash
source ~/.zshrc

验证当前 Java 版本：

bash
java -version

验证 JAVA_HOME：

bash
echo $JAVA_HOME

查看完整 Java 环境：

bash
javainfo

10. JDK 版本切换方法#

10.1 切换到 JDK 17#

bash
jdk17

或：

bash
use_jdk 17

10.2 切换到 JDK 11#

bash
jdk11

或：

bash
use_jdk 11

10.3 切换到 JDK 8#

bash
jdk8

或：

bash
use_jdk 1.8

10.4 切换到 JDK 21#

bash
jdk21

或：

bash
use_jdk 21

11. Maven 配置标准#

11.1 Maven 与 JDK 的关系#

Maven 本身不应该绑定死某个 JDK。Maven 启动时会读取当前终端中的 JAVA_HOME。

因此切换 JDK 后，必须用以下命令检查 Maven 实际使用的 Java 版本：

bash
mvn -v

示例输出中应关注：

text
Java version: 17.x.x
Java home: /Library/Java/JavaVirtualMachines/xxx-17.jdk/Contents/Home

11.2 如果 Maven 使用了错误的 JDK#

先执行：

bash
jdk17

再执行：

bash
mvn -v

如果仍然不对，检查：

bash
which mvn
which java
echo $JAVA_HOME
echo $PATH

常见原因是 ~/.zshrc、~/.bash_profile、IDE 配置、Maven Wrapper 或项目脚本中重复写死了旧 JDK 路径。

12. IntelliJ IDEA 配置标准#

如果使用 IntelliJ IDEA，建议按以下标准配置。

12.1 Project SDK#

进入：

text
File -> Project Structure -> Project -> SDK

选择：

text
JDK 17

12.2 Gradle 或 Maven JVM#

进入：

text
Settings -> Build, Execution, Deployment -> Build Tools

对于 Maven 项目，确认 Maven Runner 使用 JDK 17。

对于 Gradle 项目，确认 Gradle JVM 使用 JDK 17。

12.3 Spring Boot 3 项目#

Spring Boot 3 项目建议统一：

text
Project SDK: JDK 17
Language Level: 17
Maven Runner JRE: JDK 17

13. 当前 MacBook 标准验证清单#

配置完成后，依次执行以下命令：

bash
uname -m
echo $SHELL
/usr/libexec/java_home -V
echo $JAVA_HOME
which java
java -version
javac -version
mvn -v

期望结果：

  1. uname -m 返回 arm64；
  2. echo $SHELL 返回 /bin/zsh；
  3. /usr/libexec/java_home -V 能看到 JDK 17；
  4. echo $JAVA_HOME 指向 JDK 17 的 Contents/Home；
  5. which java 优先指向 $JAVA_HOME/bin/java；
  6. java -version 显示 Java 17；
  7. javac -version 显示 Java 17；
  8. mvn -v 中的 Java version 显示 Java 17。

14. 常见问题处理#

14.1 输入 jdk17 提示 command not found#

原因：~/.zshrc 没有生效。

解决：

bash
source ~/.zshrc

再执行：

bash
jdk17

如果仍然失败，检查配置是否写入了正确文件：

bash
echo $SHELL

如果返回 /bin/zsh，就必须配置 ~/.zshrc。

14.2 java -version 不是 JDK 17#

先执行：

bash
jdk17

再检查：

bash
which java
java -version
echo $JAVA_HOME

如果 which java 没有指向 JDK 17，说明 PATH 中存在其他 Java 路径，需要检查 ~/.zshrc 中是否有重复 Java 配置。

14.3 /usr/libexec/java_home -v 17 找不到 JDK#

说明本机没有正确安装 JDK 17，或者安装的是异常目录。

检查：

bash
ls /Library/Java/JavaVirtualMachines

如果没有 JDK 17，需要重新下载并安装 ARM64 版本 JDK 17。

14.4 Maven 仍然使用旧 JDK#

执行：

bash
jdk17
mvn -v

如果 Maven 仍显示旧版本，检查是否存在以下情况：

  1. ~/.zshrc 中重复设置了 JAVA_HOME；
  2. ~/.bash_profile 中也设置了旧 JDK；
  3. IDE 中 Maven Runner 写死了旧 JDK；
  4. 项目中使用了 Maven Wrapper，并在脚本中写死了 Java 路径；
  5. 终端没有重新加载配置。

14.5 是否需要配置 CLASS_PATH#

不需要。

当前 MacBook 标准环境不配置全局 CLASS_PATH。Java 项目的依赖应交给 Maven、Gradle 或 IDE 管理。

15. 推荐目录规范#

当前 MacBook 建议采用以下开发目录结构：

text
~/dev
  ├── java
  ├── maven
  ├── projects
  ├── scripts
  └── tools

如手动安装 Maven，可放在：

text
~/dev/maven/apache-maven-3.9.6

对应配置为：

16. 一键检查脚本#

可在终端执行以下命令，快速检查当前 Java 和 Maven 环境：

bash
cat <<'EOF' > ~/dev/scripts/check-java-env.sh
#!/usr/bin/env bash
set -e

echo "===== Mac Architecture ====="
uname -m

echo ""
echo "===== Shell ====="
echo "$SHELL"

echo ""
echo "===== Installed JDKs ====="
/usr/libexec/java_home -V || true

echo ""
echo "===== JAVA_HOME ====="
echo "$JAVA_HOME"

echo ""
echo "===== Java Path ====="
which java || true

echo ""
echo "===== Java Version ====="
java -version || true

echo ""
echo "===== Javac Version ====="
javac -version || true

echo ""
echo "===== Maven Version ====="
mvn -v || true
INNER_EOF

chmod +x ~/dev/scripts/check-java-env.sh
~/dev/scripts/check-java-env.sh

如果提示目录不存在，先执行：

bash
mkdir -p ~/dev/scripts