• 文档
• 教程
• 知识库

本指南整理自 java/install-java-on-mac-with-brew.md，完整覆盖"用 Homebrew 安装 Java → 遇到Unable to locate a Java Runtime报错 → 通过brew info openjdk获取符号链接命令 → 修复后验证java -version"的完整链路。读完本文，你将掌握 macOS 上 Homebrew 安装 OpenJDK 的标准流程，理解为什么安装完成后系统仍然找不到 Java 运行时，并能独立完成符号链接修复与最终验证。

为什么在 macOS 上选择 Homebrew 安装 Java

如果你的 Mac 上还没有安装任何 Java 环境，最常见、最省事的方式就是通过 Homebrew 安装。brew install java安装的是 OpenJDK —— Java Development Kit（JDK，即 Java 平台）的开源实现，它基于 OpenJDK 社区源码构建，是当前 macOS 上使用最广泛的开源 Java 发行版之一。

本仓库的 java/ 分类下收录了若干 Java 相关的实战笔记，本文是其中的"环境准备篇"：只有先把 JDK 装好、让系统能够识别java命令，java/run-a-hello-world-program-in-eclipse.md 中的 Hello World 示例才能真正跑起来。

第一步：执行 brew install java

在终端中直接执行：

$ brew install java

这条命令会下载并安装当前 Homebrewopenjdk公式对应的 JDK 版本。安装过程需要一定时间（需要拉取二进制包并解压到 Homebrew 的 Cellar 目录），属于正常现象，耐心等待即可。

安装完成后，第一直觉是立刻验证一下版本号：

$ java -version

但如果你此前从未安装过任何 Java 运行时，看到的往往不是版本号，而是下面这段报错：

$ java -version The operation couldn’t be completed. Unable to locate a Java Runtime. Please visit http://www.java.com for information on installing Java.

这正是本文要解决的经典"坑"：Homebrew 明明装好了 JDK，系统却说找不到 Java Runtime。

根因：Homebrew 没有把 OpenJDK"完整"接入系统

这个报错的根源在于：OpenJDK 这个开源实现并不会被 Homebrew 完全自动配置到系统中（原文表述为 "does not get fully set up by homebrew"）。

具体来说，Homebrew 的openjdk公式是一个keg-only（仅驻留在自家目录）的公式：它会被安装到 Homebrew 的安装目录中，但默认不会把自己的 JDK 包链接到 macOS 系统级的 Java 虚拟机注册目录：

/Library/Java/JavaVirtualMachines/

macOS 自带的/usr/bin/java启动器（launcher）只会在上述系统目录里查找可用的 JDK。既然 OpenJDK 没有出现在那里，系统自然就报出"Unable to locate a Java Runtime"。

因此，修复的关键一步是：手动为openjdk建立符号链接（symlink），把它注册到系统目录中，让/usr/bin/java能找到它。

从 brew info openjdk 获取准确的符号链接命令

不同机器上 Homebrew 的安装前缀不同（Intel 芯片 Mac 为/usr/local，Apple Silicon 芯片 Mac 为/opt/homebrew），openjdk的实际安装路径也因此不同。与其手写一个可能错误的路径，不如让 Homebrew 自己告诉我们准确命令。

运行：

$ brew info openjdk

输出中会有一段专门说明如何让系统 Java 启动器找到这个 JDK，类似这样（省略了其他信息）：

... For the system Java wrappers to find this JDK, symlink it with sudo ln -sfn /usr/local/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk ...

注意：你机器上展示的路径可能与本示例不同（Apple Silicon 机器上通常会是/opt/homebrew/opt/openjdk/libexec/openjdk.jdk）。所以请直接复制输出中给出的那条命令原样执行，不要照抄示例路径。

复制命令后执行：

$ sudo ln -sfn /usr/local/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk

这里对这条命令做一点拆解，帮助你理解它做了什么：

如果你对符号链接机制本身感兴趣，本仓库的 unix/display-the-target-of-a-symbolic-link.md 专门介绍了如何用readlink查看一个符号链接实际指向的目标位置，可以配合验证：

$ readlink /Library/Java/JavaVirtualMachines/openjdk.jdk /usr/local/opt/openjdk/libexec/openjdk.jdk

再次验证：java -version 输出 OpenJDK 版本信息

符号链接建立之后，重新执行版本检查：

$ java -version openjdk version "23" 2024-09-17 OpenJDK Runtime Environment Homebrew (build 23) OpenJDK 64-Bit Server VM Homebrew (build 23, mixed mode, sharing)

现在输出正常了。可以看到三行关键信息：

• openjdk version "23"：JDK 主版本号（具体版本取决于你安装时的openjdk公式版本，示例为 23）；
• OpenJDK Runtime Environment Homebrew (build 23)：运行时环境（Runtime Environment）来自 Homebrew 构建；
• OpenJDK 64-Bit Server VM Homebrew (build 23, mixed mode, sharing)：64 位 Server 虚拟机，使用 mixed mode（解释与 JIT 编译混合执行）与 sharing（共享类数据）。

至此，Java 环境安装完成，java、javac等命令都已可正常使用。

进阶：可选的环境变量与 Hello World 实战验证

配置 JAVA_HOME（可选但推荐）

许多构建工具（Maven、Gradle、Eclipse 等）依赖JAVA_HOME环境变量定位 JDK。你可以在 shell 配置文件中手动指向刚安装的 OpenJDK 主目录：

# 以示例的 Intel 路径为例，Apple Silicon 机器请换成 /opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home export JAVA_HOME="/usr/local/opt/openjdk/libexec/openjdk.jdk/Contents/Home"

注意：JAVA_HOME指向的是.jdk包内的Contents/Home目录（JDK 的实际 home 结构），与系统目录符号链接的指向不同，两者不要混淆。

用 Hello World 收尾验证

环境就绪后，可以按本仓库 java/run-a-hello-world-program-in-eclipse.md 的指引，在 Eclipse 中新建 Java 项目、创建带main方法的Greeting.java并运行，用真实的程序跑通"编译—执行"闭环，确认 JDK 不仅"找得到"，而且"跑得动"。

小结

回顾整个流程，核心经验可以浓缩为三点：

1. brew install java安装的是 OpenJDK，安装后不会自动接入 macOS 系统 Java 注册目录，java -version报 "Unable to locate a Java Runtime" 是正常现象而非安装失败；
2. 运行brew info openjdk，从输出中复制 Homebrew 针对你机器生成的sudo ln -sfn符号链接命令并执行，即可完成系统级集成；
3. 再次执行java -version验证，看到OpenJDK Runtime Environment Homebrew字样即表示安装成功。

本仓库的 README.md 在 Java 分类下列出了完整的 Java 相关笔记索引；如果你还想了解 Homebrew 的其他日常维护技巧（例如定期清理不再需要的安装产物），可参考 brew/clean-up-your-brew-installations.md。

• 文档
• 教程
• 知识库