从零搭建 Mac Java 开发环境：Homebrew + JDK + Maven + Git 全流程配置

本文面向刚拿到新 Mac（Apple Silicon 芯片）的开发者，从零开始搭建一套完整的 Java 开发环境。每一步都会解释为什么要装、装了能做什么、不装会怎样。

写在前面：工具链全景

在开始之前，先理解整个工具链的关系：

复制代码

Xcode CLT          → 编译器基础设施，几乎所有工具的底层依赖
    ↓
Homebrew           → Mac 上的包管理器，用它来安装其他工具
    ↓
Oh My Zsh          → 让终端更好用（可选，但强烈推荐）
    ↓
Git + SSH Key      → 代码版本管理 + 与远程仓库通信
    ↓
JDK 11             → Java 运行和编译环境
    ↓
Maven              → Java 项目构建和依赖管理
    ↓
IntelliJ IDEA      → 集成开发环境，写代码的地方

类型	工具
缺一不可	Xcode CLT、Git、JDK、Maven
强烈推荐	Homebrew、Oh My Zsh
可替换	IntelliJ IDEA（也可用其他 IDE）

一、Xcode Command Line Tools

是什么 & 为什么装

Xcode CLT 是苹果提供的一套命令行编译工具，包含 clang（C/C++ 编译器）、make、git 等基础开发工具。

不装会怎样： 后续几乎所有工具（Homebrew、Git、Maven）都无法正常运行，是整个开发环境的地基。

安装

复制代码

xcode-select --install

执行后会弹出图形安装窗口，点击"安装"等待完成即可。

如果已经安装完整版 Xcode（从 App Store 下载），需要额外执行：

复制代码

# 把 Xcode 移到 Applications（放在 Downloads 不算安装）
sudo mv ~/Downloads/Xcode.app /Applications/

# 绑定工具链路径
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

# 接受许可协议（不做这步 Homebrew 会报错）
sudo xcodebuild -license accept

验证

复制代码

xcode-select -p
# 输出：/Library/Developer/CommandLineTools
# 或：/Applications/Xcode.app/Contents/Developer

clang --version
# 输出：Apple clang version 17.x.x ...

git --version
# 输出：git version 2.x.x

⚠️ 常见问题

问题1：命令卡住或报错"无法连接服务器"

企业网络环境下，苹果软件更新服务器可能被代理拦截，表现为安装进度条卡死或直接报错。

解决：断开公司 Wi-Fi，连手机热点后重新执行命令。

问题2：macOS beta 版本找不到 CLT 包

beta 系统对应的 CLT 包可能尚未发布：

复制代码

# 验证：输出为空说明包还没上线
softwareupdate -l | grep "Command Line Tools"

解决：安装完整版 Xcode 并执行上方绑定命令，效果完全等同 CLT。

二、Homebrew（包管理器）

是什么 & 为什么装

Homebrew 是 macOS 上最主流的包管理器，相当于 Linux 上的 apt 或 yum。有了它，安装任何开发工具只需一行命令，不需要去各个官网手动下载安装包。

不装会怎样： 可以手动安装各个工具，但管理和更新会非常繁琐。强烈建议安装。

安装

复制代码

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Apple Silicon 必做：添加 PATH

这是 Apple Silicon 特有步骤，Intel Mac 不需要。

原因：Apple Silicon 上 Homebrew 安装在 /opt/homebrew，不在系统默认 PATH 里，装完直接用会提示 command not found: brew。

复制代码

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

验证

复制代码

brew --version
# 输出：Homebrew 5.x.x

常用命令备忘

复制代码

brew install <软件名>      # 安装
brew uninstall <软件名>    # 卸载
brew upgrade               # 更新所有软件
brew list                  # 查看已安装列表
brew search <关键词>       # 搜索软件

三、Oh My Zsh（终端增强）

是什么 & 为什么装

macOS 默认使用 zsh 作为 Shell，Oh My Zsh 是 zsh 的配置框架，提供：

丰富的主题（好看的命令提示符）
插件生态（git 状态显示、命令补全等）
进入 git 仓库时自动显示当前分支名

不装会怎样： 终端功能完整，只是用起来没那么顺手。非必须，但装了明显提升效率。

安装

复制代码

sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

安装时提示是否覆盖 .zshrc，选 Y。原文件自动备份为 .zshrc.pre-oh-my-zsh，不会丢失之前的配置。

四、Git + SSH Key 配置

是什么 & 为什么装

Git 是目前最主流的版本控制系统，用于追踪代码变更、多人协作开发。

SSH Key 是非对称加密的身份认证方式。配置后，本机和代码托管平台之间免密通信，无需每次 push/pull 输入密码。

不配 SSH Key 会怎样： 每次与远程仓库交互都需要输入用户名密码，且部分平台已不支持密码认证。

步骤一：配置 Git 用户信息

复制代码

git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

# 验证
git config --global --list

这些信息会出现在每一次 commit 记录里，建议用真实姓名和常用邮箱。

步骤二：检查并修复 .ssh 目录权限

复制代码

ls -la ~ | grep .ssh

正常输出：

复制代码

drwx------  3 yourusername  staff  96 ...

如果所有者是 root（新 Mac 偶尔出现）：

复制代码

sudo chown -R $(whoami) ~/.ssh
chmod 700 ~/.ssh

权限不对会导致 ssh-keygen 报 Permission denied，必须先修复再继续。

步骤三：生成 SSH 密钥对

复制代码

ssh-keygen -t ed25519 -C "your_email@example.com"

三次交互全部回车，使用默认值：

复制代码

Enter file in which to save the key:   # 回车
Enter passphrase:                       # 回车（不设密码）
Enter same passphrase again:            # 回车

生成两个文件：

~/.ssh/id_ed25519 --- 私钥，绝对不能泄露，留在本机
~/.ssh/id_ed25519.pub --- 公钥，上传到 GitLab/GitHub

步骤四：将公钥添加到代码托管平台

复制代码

# 查看公钥，复制完整的这一行
cat ~/.ssh/id_ed25519.pub
# 输出示例：ssh-ed25519 AAAA...（很长）... your_email@example.com

将完整内容粘贴到 GitLab/GitHub 的 SSH Keys 设置页面。

步骤五：验证 SSH 连通性

复制代码

ssh -T git@github.com
# 成功输出：Hi username! You've successfully authenticated...

# 如果是公司 GitLab
ssh -T git@gitlab.example.com
# 成功输出：Welcome to GitLab, @username!

⚠️ 常见问题

问题：平台报"密钥类型被禁止"或"密钥无效"

原因：粘贴时漏掉了开头的 ssh-ed25519，只粘贴了中间的 Base64 内容。

必须粘贴完整的一整行，格式为：

复制代码

ssh-ed25519 AAAA...（Base64内容）... your_email@example.com

五、克隆代码仓库

为什么单独说这一步

克隆是把远程仓库的代码下载到本地的操作，是日常开发的起点。有几个细节值得注意。

创建代码目录

Mac 不自带代码目录，建议统一放在一个地方便于管理：

复制代码

mkdir -p ~/Develop
cd ~/Develop

SSH 协议 vs HTTPS 协议

克隆仓库有两种地址格式：

协议	格式	特点
SSH（推荐）	`git@github.com:user/repo.git`	用密钥认证，免密，更安全
HTTPS	`https://github.com/user/repo.git`	每次需要输入账号密码或 Token

始终优先使用 SSH 协议。

克隆命令

复制代码

# 标准克隆（完整历史记录）
git clone git@github.com:your-org/your-repo.git

# 浅克隆（只拉最新一个版本，适合大仓库，速度更快）
git clone --depth=1 git@github.com:your-org/your-repo.git

什么时候用 --depth=1： 大型项目历史记录可能有几个 GB，浅克隆只拉最新代码，速度快很多。如果只是运行项目而不需要查看历史，用浅克隆即可。

六、JDK 11

是什么 & 为什么装

JDK（Java Development Kit）是 Java 开发工具包，包含运行环境、编译器、调试工具等。

为什么是 JDK 11： LTS（长期支持）版本，业界主流项目大多在 JDK 8/11/17 上运行，11 是兼容性和现代特性的最佳平衡点。

不装会怎样： 无法编译和运行任何 Java 代码，Maven 也无法工作。

下载安装

推荐 Microsoft Build of OpenJDK（免费、稳定）：

👉 https://www.microsoft.com/openjdk

Apple Silicon → 选 macOS aarch64 .pkg
Intel 芯片 → 选 macOS x64 .pkg

下载 .pkg 文件双击安装，按向导完成。

配置 JAVA_HOME

复制代码

# 验证 JDK 路径
export JAVA_HOME=$(/usr/libexec/java_home)
echo $JAVA_HOME
# 示例：/Library/Java/JavaVirtualMachines/microsoft-11.jdk/Contents/Home

# 写入 .zshrc，永久生效
echo "export JAVA_HOME=$(/usr/libexec/java_home -v 11)" >> ~/.zshrc
source ~/.zshrc

为什么要设置 JAVA_HOME： Maven、Gradle 等工具启动时读取这个变量来定位 Java。不设置可能找不到 Java，或用了错误版本。

验证

复制代码

java -version
# 输出：openjdk version "11.0.25" ...

echo $JAVA_HOME
# 输出：JDK 11 路径

⚠️ 常见问题

Homebrew 安装 Maven 时顺带安装了新版 openjdk，导致版本混乱

复制代码

# 检查当前版本
java -version

# 如果不是 11，手动指定
echo "export JAVA_HOME=$(/usr/libexec/java_home -v 11)" >> ~/.zshrc
source ~/.zshrc

七、Maven

是什么 & 为什么装

Maven 是 Java 生态最主流的项目构建和依赖管理工具，做三件事：

依赖管理 --- 自动下载项目所需第三方库，不需要手动管理 jar 包
项目构建 --- 编译、测试、打包一条命令搞定
标准化 --- 统一项目结构，让团队在同一套规范下工作

不装会怎样： 无法构建绝大多数 Java 项目。

安装

复制代码

brew install maven

# 增加内存配置，防止大项目 OOM（内存溢出）
echo 'export MAVEN_OPTS="$MAVEN_OPTS -Xmx4g"' >> ~/.zshrc
source ~/.zshrc

内存参数参考：8GB 内存 Mac 建议 -Xmx2g，16GB 及以上用 -Xmx4g。

配置 settings.xml

settings.xml 是 Maven 核心配置文件，用于配置私有仓库地址、镜像源、认证信息等。

复制代码

# 创建 Maven 本地目录
mkdir -p ~/.m2/

# 备份旧配置（如有）
test -r ~/.m2/settings.xml && \
  cp ~/.m2/settings.xml ~/.m2/settings.xml.$(date '+%Y%m%d').bak

# 进入团队配置仓库目录（必须先 cd 进去）
cd ~/Develop/your-config-repo
git pull --rebase

# 建立软链（必须在配置仓库目录内执行！）
ln -fsv $(pwd)/path/to/settings.xml ~/.m2/settings.xml

# 验证软链
ll ~/.m2/settings.xml
# 应显示：settings.xml -> /Users/xxx/Develop/your-config-repo/...

为什么用软链： 软链让本地配置和仓库保持同步，团队更新配置后 git pull 就能自动获取，不需要手动覆盖文件。

验证

复制代码

mvn -version
# 期望输出：
# Apache Maven 3.9.x
# Java version: 11.0.x, vendor: Microsoft
# OS name: "mac os x", arch: "aarch64"   ← Apple Silicon 原生应显示 aarch64

⚠️ 常见问题

软链路径错误（最高频的 Maven 异常根源）

必须进入配置仓库目录后再执行 ln 命令，$(pwd) 会展开为当前路径：

复制代码

# ✅ 正确：先进目录再执行
cd ~/Develop/your-config-repo
ln -fsv $(pwd)/path/to/settings.xml ~/.m2/settings.xml

# ❌ 错误：在其他目录执行，$(pwd) 展开为错误路径
# 即使命令不报错，软链也会指向一个不存在的路径

八、IntelliJ IDEA

是什么 & 为什么装

IntelliJ IDEA 是目前 Java 开发最主流的 IDE，提供智能代码补全、内置调试器、Git 可视化、Maven 项目管理等功能。

不装会怎样： 可以用 VSCode 代替，但 IDEA 对 Java/Kotlin 的支持是业界最好的，大多数 Java 团队的标配。

下载安装

👉 https://www.jetbrains.com/idea/download

Apple Silicon 选 macOS Apple Silicon (.dmg)，原生 arm64，性能比通用版好很多。

下载后双击 .dmg，将 IDEA 图标拖到 Applications 文件夹完成安装。

配置 Checkstyle

团队项目通常有代码格式规范，安装后务必配置 Checkstyle：

打开 IDEA → Preferences → 搜索 Checkstyle
安装 CheckStyle-IDEA 插件
导入团队的 checkstyle 配置文件

不配的后果： 每次提交代码都会因格式问题被 CI 拦截，浪费大量时间在格式修复上。

九、最终 .zshrc 配置汇总

完成所有步骤后，~/.zshrc 中应包含以下关键配置：

复制代码

# Homebrew（Apple Silicon 必须）
eval "$(/opt/homebrew/bin/brew shellenv)"

# Java
export JAVA_HOME=$(/usr/libexec/java_home -v 11)

# Maven
export MAVEN_OPTS="$MAVEN_OPTS -Xmx4g"

验证配置加载正常：

复制代码

source ~/.zshrc
echo $JAVA_HOME        # 应输出 JDK 11 路径
echo $MAVEN_OPTS       # 应输出 -Xmx4g
which brew             # 应输出 /opt/homebrew/bin/brew

十、常用终端操作速查

快捷键

快捷键	效果
`Control + U`	清除当前行所有输入
`Control + C`	中断正在运行的命令
`Control + A`	跳到行首
`Control + E`	跳到行尾
`Control + W`	删除前一个单词
`Control + D`	退出当前 Shell
`Command + K`	清空终端屏幕
`Command + T`	新建标签页
`Command + N`	新建终端窗口

常用命令

复制代码

pwd                  # 查看当前路径
ls -la               # 查看目录内容（含隐藏文件）
cd ~/Develop         # 进入目录
mkdir -p ~/foo       # 创建目录（-p 自动创建父级）
cat ~/.zshrc         # 查看文件内容
source ~/.zshrc      # 重新加载配置文件
which java           # 查看命令实际路径
ll ~/.m2/settings.xml  # 查看软链指向

全流程验证清单

复制代码

# 基础工具链
xcode-select -p                   # ✅ 有路径输出
clang --version                   # ✅ Apple clang 版本号
git --version                     # ✅ git 2.x.x

# 包管理
brew --version                    # ✅ Homebrew 5.x.x

# SSH 连通性
ssh -T git@github.com             # ✅ 认证成功提示

# Java 环境
java -version                     # ✅ openjdk 11.x.x
echo $JAVA_HOME                   # ✅ 指向 JDK 11
mvn -version                      # ✅ Maven 3.x.x + Java 11 + aarch64

# Maven 配置
ll ~/.m2/settings.xml             # ✅ 软链指向正确路径

# 服务治理（视团队要求）
lsof -i:6604                      # ✅ KESS Agent 监听正常

# 代码协作工具（视团队要求）
kdev                              # ✅ 有帮助信息输出

高频坑汇总

问题现象	根因	解决方案
`xcode-select --install` 卡住失败	企业网络代理拦截苹果服务器	换手机热点 / 安装完整版 Xcode
`ssh-keygen` 报 Permission denied	`.ssh` 目录归 root 所有	`sudo chown -R $(whoami) ~/.ssh`
`brew: command not found`	Apple Silicon PATH 未配置	向 `.zshrc` 写入 brew shellenv
GitLab 报密钥无效	公钥粘贴不完整，缺 `ssh-ed25519` 前缀	重新 `cat ~/.ssh/id_ed25519.pub` 完整复制
Maven 构建找不到依赖	`settings.xml` 软链路径错误	进入配置仓库目录，重新执行 `ln -fsv`
`mvn -version` 显示 Java 版本不对	多个 JDK 版本共存，JAVA_HOME 指向错误	`export JAVA_HOME=$(/usr/libexec/java_home -v 11)`
KESS Agent 安装包被系统拦截	macOS 安全策略阻止未知开发者	系统设置 → 隐私与安全性 → 仍然允许
`kdev` 报 Permission denied	安装时未用 sudo，`/usr/local/bin/` 写入失败	重新用 `sudo curl` 安装

按顺序走，每步验证通过再继续。遇到问题先对照坑汇总排查，90% 的情况不需要额外搜索。