Mac 下 Java 开发环境搭建：JDK 安装、Maven/Gradle 配置及 IntelliJ IDEA 设置

一、架构准备与环境识别

在开始安装任何工具之前，首先需要明确当前 Mac 所采用的处理器架构。苹果的 Mac 设备目前存在两种主流处理器架构：基于 ARM64 的 Apple Silicon（M1/M2/M3/M4 系列芯片）以及基于 x86_64 的 Intel 芯片。这两者在底层二进制指令集、软件包原生执行效率以及默认安装路径上均有明显区别。

打开 macOS 自带的终端（Terminal），执行以下命令确认系统内核架构：

uname -m

如果输出为 arm64，说明当前是 Apple Silicon 芯片设备，在后续下载 JDK 和 IntelliJ IDEA 时必须选择 macOS ARM64 / AArch64 版本；如果输出为 x86_64，则表示为 Intel 芯片，需下载 macOS x64 版本。原生架构的软件包可以免去 Rosetta 2 转译层的性能损耗，在大型工程编译与内存占用上表现更优。

macOS 目前默认使用的 Shell 解释器为 zsh。所有持久化环境变量均建议配置在用户主目录下的 ~/.zshrc 文件中。若之前使用过 bash，注意其配置文件 ~/.bash_profile 在 zsh 下不会自动加载。

二、JDK 安装与版本管理

自 Java 11 以后，各类构建在 OpenJDK 基础上的成熟发行版逐渐成为主流。在生产与开发场景中，推荐使用 Eclipse Temurin（由 Adoptium 基金会维护）、Amazon Corretto 或 Azul Zulu。这些发行版针对 macOS 提供了充分优化的原生安装包，并且提供长期支持（LTS）。当前企业开发中广泛使用的 LTS 版本为 Java 17 与 Java 21。

1. 通过 Homebrew 快速安装

若系统已安装包管理工具 Homebrew，可以通过一行命令安装官方收录的 OpenJDK 发行版。以 Temurin 17 和 Temurin 21 为例：

# 安装 Adoptium 官方 cask 仓库中的 Temurin 17
brew install --cask temurin@17

# 或者安装最新的 LTS 版本 Temurin 21
brew install --cask temurin@21

Homebrew 会将 JDK 规范地存放在系统的全局虚拟机目录下：/Library/Java/JavaVirtualMachines/。这种安装方式符合 macOS 标准规范，可被系统的 Java 调度机制自动识别。

2. 手动下载 DMG 安装包

如果不使用 Homebrew，可以直接前往 Adoptium 官网（adoptium.net）或 Azul 官网下载 .pkg 或 .dmg 格式的安装包。双击运行引导程序即可。安装完成后，文件同样会被放置在 /Library/Java/JavaVirtualMachines/ 路径中。

3. 配置 JAVA_HOME 与动态版本切换

macOS 提供了一个专用的命令工具 /usr/libexec/java_home，用于动态查找和切换系统中已安装的 JDK 路径。该工具能避免硬编码路径带来的维护困难。

在终端中查看系统已检测到的所有 JDK 实例：

/usr/libexec/java_home -V

输出将列出已安装的版本编号、架构（arm64 或 x86_64）以及对应的完整安装目录路径。

编辑当前用户的 ~/.zshrc 文件：

nano ~/.zshrc

在文件末尾加入以下配置。不仅设置了默认的 JAVA_HOME，还通过简易别名（Alias）实现了多版本秒级切换：

# 默认设定 JAVA_HOME 为系统中的 Java 17
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH=$JAVA_HOME/bin:$PATH

# 多版本快速切换别名（按需增加）
alias jdk17="export JAVA_HOME=$(/usr/libexec/java_home -v 17); java -version"
alias jdk21="export JAVA_HOME=$(/usr/libexec/java_home -v 21); java -version"

保存退出后，执行以下命令使配置立即在当前会话生效：

source ~/.zshrc

通过检查输出确认安装正确：

java -version
echo $JAVA_HOME

三、构建工具配置：Maven 与 Gradle

在现代 Java 工程中，构建工具负责管理第三方依赖、编译源码、执行单元测试以及打包交付物。Maven 与 Gradle 是目前使用最为广泛的两个解决方案。

1. Maven 安装与国内镜像源配置

通过 Homebrew 安装 Maven 简便且便于升级：

brew install maven

安装完成后，运行 mvn -v 验证是否能够正确输出版本信息与对应的 Java 运行环境路径。

默认情况下，Maven 会访问位于海外的 Maven Central 中央仓库，国内拉取依赖时速度受限且偶尔出现网络超时。我们需要配置阿里云镜像加速，并规范本地仓库存储路径。

创建用户级 Maven 配置目录与文件：

mkdir -p ~/.m2
nano ~/.m2/settings.xml

写入以下精简且生产可用的 settings.xml 配置内容：

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 https://maven.apache.org/xsd/settings-1.2.0.xsd">

  <!-- 自定义本地依赖缓存路径（默认在 ~/.m2/repository） -->
  <localRepository>/Users/<你的用户名>/.m2/repository</localRepository>

  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>central</mirrorOf>
      <name>阿里云公共仓库</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
</settings>

2. Gradle 安装与初始化设置

同样可以通过 Homebrew 安装 Gradle：

brew install gradle

安装完成后，执行 gradle -v 确认版本。

Gradle 的全局配置放置在 ~/.gradle/ 目录。为了让所有未单独配置镜像的 Gradle 工程全局使用国内加速源，可创建全局初始化脚本 ~/.gradle/init.gradle：

mkdir -p ~/.gradle
nano ~/.gradle/init.gradle

写入以下脚本内容：

allprojects {
    repositories {
        mavenLocal()
        maven { url 'https://maven.aliyun.com/repository/public/' }
        maven { url 'https://maven.aliyun.com/repository/google/' }
        mavenCentral()
    }
}

此外，在 ~/.gradle/gradle.properties 中可以开启守护进程（Daemon）与并行构建，显著缩短后续编译时间：

nano ~/.gradle/gradle.properties

# 开启后台常驻守护进程
org.gradle.daemon=true
# 开启并行构建任务
org.gradle.parallel=true
# 启用构建缓存
org.gradle.caching=true
# 调整 Gradle 运行最大内存
org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8

3. Maven 与 Gradle 关键机制对比

在搭建环境时，理解 Maven 与 Gradle 的核心差异有助于选择合适的工程管理方式：

四、IntelliJ IDEA 全局设置与工具链集成

IntelliJ IDEA 是 Java 开发事实上的首选 IDE。安装后，需要对其进行一系列全局设置，使其与前面安装的 JDK、Maven、Gradle 正确绑定，避免出现“终端编译通过但 IDE 报红”的不一致现象。

1. 选择正确的安装包

从 JetBrains 官网下载 IntelliJ IDEA（Ultimate 或 Community 版本）时，请务必在下载下拉框中核实安装包架构：

• Apple Silicon（M 系列芯片）：选择 .dmg (Apple Silicon)。这是基于 AArch64 原生架构编译的，启动速度与索引效率极高。
• Intel 处理器：选择 .dmg (Intel)。

2. 配置 Project SDK（默认 JDK）

在未打开项目的欢迎界面，或者在顶部菜单栏依次点击：IntelliJ IDEA -> Settings（快捷键 Cmd + ,）：

1. 进入 Build, Execution, Deployment -> Build Tools -> Gradle 或全局 Project Structure（从 File -> New Projects Setup -> Structure for New Projects... 访问）。
2. 在 SDKs 栏目中，点击 + 号，选择 Add JDK...。
3. 此时 macOS 的文件选择器会弹出，导航至 /Library/Java/JavaVirtualMachines/ 目录，选择刚才安装的 JDK 路径（例如 temurin-17.jdk/Contents/Home）。
4. IDEA 会自动识别出 JDK 版本与平台架构，将其设为默认的 Project SDK。

3. 关联自定义 Maven 与本地仓库

默认情况下，IntelliJ IDEA 会使用其内置的 Bundled Maven，且该 Maven 默认读取空配置，这会导致依赖下载极慢。我们需要显式关联外部配置：

1. 打开 Settings -> Build, Execution, Deployment -> Build Tools -> Maven。
2. Maven home path：可选择 Use plugin/bundled，或者指向 Homebrew 安装的绝对路径（如 /opt/homebrew/opt/maven/libexec）。
3. User settings file：勾选右侧的 Override 复选框，将其路径指定为前面配置的 /Users/<用户名>/.m2/settings.xml。
4. Local repository：此时系统会自动根据 settings.xml 中的设置变更为对应的 ~/.m2/repository 目录。

4. 统一全局文件编码为 UTF-8

不同操作系统间协作时，编码混乱常常引起中文乱码或编译失败。在设置中锁定 UTF-8：

• 进入 Editor -> File Encodings。
• 将 Global Encoding 与 Project Encoding 均设置为 UTF-8。
• 将 Default encoding for properties files 设为 UTF-8，并勾选 Transparent native-to-ascii conversion（自动转义 properties 中的特殊中文字符）。

五、环境联调验证与常见问题排查

完成上述全部安装与设置后，我们可以通过一个标准工程进行闭环联调，并排查可能出现的典型问题。

1. 综合联调验证

在 IntelliJ IDEA 中新建一个基于 Maven 或 Gradle 的基础 Java 项目：

1. 选择 New Project -> Java，构建系统（Build system）选择 Maven，JDK 选择刚配置的 17。
2. 等待项目初始化完成。观察右下角进度条，确认依赖是从 maven.aliyun.com 快速下载，而非从海外源缓慢拉取。
3. 在 src/main/java 下创建 Main.java 并运行：

public class Main {
    public static void main(String[] args) {
        System.out.println("Java Environment on macOS is ready!");
        System.out.println("Current Java Version: " + System.getProperty("java.version"));
        System.out.println("OS Architecture: " + System.getProperty("os.arch"));
    }
}

如果控制台能正常输出字符串，且 os.arch 显示为 aarch64（在 M 系列芯片上），则表明从 JVM、构建工具到 IDE 的整套链条全部以原生高效模式运转。

2. 常见问题与排查指南

问题一：终端中 java -version 显示正常，但 IDEA 启动项目时提示找不到 JDK。
排查与修复： macOS 图形界面应用程序（如 IDEA）默认不继承 ~/.zshrc 中设置的环境变量。不要依赖 IDEA 自动扫描 PATH，而是必须在 IDEA 的 Project Structure -> SDKs 中显式添加 /Library/Java/JavaVirtualMachines/ 下的 JDK 目录。

问题二：Maven 下载依赖时报证书校验错误（SSLHandshakeException）或连接超时。
排查与修复： 首先检查 ~/.m2/settings.xml 中的镜像 URL 是否为标准的 https://maven.aliyun.com/repository/public；其次检查网络是否启用了企业内部安全代理。如果特定网络阻断了 SSL 握手，可检查系统钥匙串中的根证书完整性。

问题三：在 Apple Silicon 设备上运行依赖底层 JNI 库（如特定驱动或图形库）时报 UnsatisfiedLinkError: incompatible architecture (have 'x86_64', need 'arm64')。
排查与修复： 这表明第三方 jar 包中只内置了针对 Intel x86_64 的动态链接库（.dylib），而当前使用的是 ARM64 原生 JDK。此时可以通过别名快速切换为 x86_64 架构的 JDK 并通过 Rosetta 运行，或者升级第三方依赖版本以获取支持 Apple Silicon 的最新构件。

遵循以上规范完成搭建后，macOS 上的 Java 开发环境无论在面对日常单体项目调试、微服务架构部署还是大型工程的高频编译时，都能提供稳定、高效的运行支撑。