必须安装ARM64版JDK 21，M1/M2/M3芯片需匹配aarch64架构；用uname -m确认输出为arm64，java -version应显示aarch64和LTS字样，否则非生产就绪。
直接装 ARM64 版 JDK 21，别碰 x64 + Rosetta 的组合——性能掉 30% 以上，且 java -version 显示的架构是 aarch64 而不是 amd64，这才是 M1/M2/M3 真正“开箱即用”的起点。
怎么确认你的 Mac 是 Apple Silicon 架构？
终端里跑这一句就行：
uname -m
输出必须是 arm64。如果不是，说明你正在 Rosetta 下运行终端（比如从 Intel 版 Terminal.app 启动），得换成原生的“终端”App（在 /Applications/Utilities/ 里，图标右下角没小箭头的那个）。
常见错误现象：
立即学习“Java免费学习笔记（深入）”；
- 装了 ARM64 JDK，但
java -version显示64-Bit Server VM (build ... mixed mode, <strong>amd64</strong>)→ 终端本身不是原生 arm64 - 用 Homebrew 装了
openjdk@21，但/usr/libexec/java_home -V列不出它 → Homebrew 默认装在/opt/homebrew，而java_home只扫/Library/Java/JavaVirtualMachines/
三种安装方式的实际表现对比
实测下来，没有“最好”，只有“最不踩坑”：
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
-
Oracle 官方 .dmg（推荐）：自动装进
/Library/Java/JavaVirtualMachines/jdk-21.jdk，/usr/libexec/java_home -v 21能立刻识别，IDEA 开箱识别无压力 -
Homebrew
openjdk@21：路径是/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk，得手动 symlink 或改JAVA_HOME，适合命令行主力、IDE 偶尔用的用户 -
SDKMAN!：装完默认指向
~/.sdkman/candidates/java/21.0.2-tem这类路径，java -version没问题，但 IntelliJ IDEA 的 Project SDK 下拉列表里可能不显示——得手动 Add JDK → 选中那个目录下的Contents/Home
关键差异点：
- Oracle 和 Temurin（Eclipse）构建的 JDK 在虚拟线程（
Thread.ofVirtual()）行为上一致；某些 Azul Zulu 构建在 M1 上偶发IllegalThreadStateException，慎选 - Homebrew 安装后，
javac编译速度略快（约 5%），但运行时性能和 Oracle 官方版无明显差别
JAVA_HOME 必须用 /usr/libexec/java_home 动态获取
硬编码路径（比如写死 export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home）在多版本共存时会翻车。正确做法是：
export JAVA_HOME=$(/usr/libexec/java_home -v 21) export PATH=$JAVA_HOME/bin:$PATH
为什么必须这样？
-
/usr/libexec/java_home是 macOS 原生机制，能自动识别所有合法 JDK（包括 Homebrew、SDKMAN!、Oracle 安装的） - 如果你同时装了
jdk-21.0.2.jdk和jdk-21.0.3.jdk，-v 21默认取最新 patch 版，不用手动改路径 - IDEA 启动脚本（
Info.plist）和 Maven 的mvn脚本内部都依赖这个命令查 JDK，硬编码会导致它们“看不见”你配的 JDK
容易被忽略的细节：
- 改完
~/.zshrc后，新开终端才能生效；已打开的终端里执行source ~/.zshrc仅影响当前 shell，不影响子进程（比如从终端启动的 IDEA） - IntelliJ IDEA 默认从 GUI 启动，它读的是系统级 shell 配置（
/etc/zshrc）或登录 shell 配置，不是你当前终端的环境 —— 所以务必验证which java和java -version在“从 Finder 双击启动的 IDEA 终端”里也正确
验证时别只信 java -version
它只告诉你 JVM 跑起来了，不保证开发链路完整。真正要跑通这三步：
- 执行
javac -version→ 确认编译器可用（很多教程漏这步，结果 IDEA 报 “Cannot find javac”） - 写个
Hello.java，用javac Hello.java && java Hello跑通 → 确认 CLASSPATH、rt.jar 加载正常 - 在 IDEA 新建 Project，选 “JDK 21”，看是否能展开
java.base模块、能否跳转到String源码 → 验证 JDK Home 下的src.zip和lib/src.zip是否被正确索引
最后一句提醒：M1/M2/M3 上的 JDK 21，java --version 输出里必须带 aarch64 和 LTS 字样，缺一不可。其它都是过渡方案，不是生产就绪状态。
