Apple Silicon Mac + macOS 14+ 的单路径配置。从空白状态到可以 git push，仅需 30-60 分钟。

一台全新的 Mac 可以在 30 到 60 分钟内准备好真正的开发工作。本指南适用于 Apple Silicon + macOS 14（Sonoma）或更新版本，目标是达到"打开终端就能 git push"的状态——不多也不少。

我认为初始配置的价值不在于安装了多少工具，而在于只安装必要的工具。以前很多开发者会在这一步装入大量自认为有用的软件；如今聚焦于「最小可工作状态」，由于后续指南各司其职，这里只覆盖真正的基础依赖。

生产力工具（Raycast/Rectangle）、编辑器和语言运行时由单独的指南覆盖。这里只安装进入可用终端所必需的内容。

TL;DR

五项 macOS 系统设置（按键重复、触控板、Finder、Dock、截图）
Xcode Command Line Tools → Homebrew → 七个核心 CLI 工具（一行 brew 命令）
Git 全局配置 + SSH 密钥（ed25519）→ 注册到 GitHub → gh auth login

自动化脚本（可选）

如果你更倾向于运行单个脚本而不是逐步操作 — 请始终下载 → 验证 SHA-256 → 检查 → 运行。

setup-mac.sh

# 1. 下载
curl -fsSL https://devalice.jaceclub.com/assets/mac/initial-setup/setup-mac.sh -o setup-mac.sh
 
# 2. 验证 SHA-256
shasum -a 256 setup-mac.sh
# 期望值：d6b501f8fa1986d980c70525d1d4476bef444bc0dd2c62fb13f2e5a9128c63cf
 
# 3. 检查
less setup-mac.sh
 
# 4. 运行
bash setup-mac.sh

该脚本是幂等的 — 部分完成或失败后可安全重新运行。它自动化了以下前六个章节；在浏览器中注册 SSH 密钥到 GitHub 以及 gh auth login 仍需手动确认。

如果你想了解每个步骤，请继续阅读下面的手动章节。

前提条件

macOS 14（Sonoma）或更新版本 — macOS 12（Monterey）及更早版本与部分最新 Homebrew 包不兼容
推荐 Apple Silicon（M1-M4） — Intel Mac 也可以，但 Homebrew 路径不同（/opt/homebrew vs /usr/local），下文会注明
管理员账户（可使用 sudo）
网络连接以及已登录的 Apple ID

Intel Mac 用户：只需记住你的 Homebrew 路径是 /usr/local，本指南的其余内容同样适用。

1. macOS 系统设置 — 5 分钟

通过「系统设置」或终端命令应用。一次配置，每天获益。

1.1 按键重复 — 最高效益的改动

默认值太慢，会悄悄拖慢你的打字速度。调到最大。

# 按键重复速率（首次重复后的速率）— 比滑块最大值更快
defaults write -g KeyRepeat -int 1
# 初始按键重复延迟（首次重复前的延迟）— 比滑块最小值更短
defaults write -g InitialKeyRepeat -int 10

退出并重新登录才会生效。（重启也可以。）

1.2 触控板 — 轻点点按 + 三指拖移

# 启用轻点点按
defaults write com.apple.AppleMultitouchTrackpad Clicking -bool true
defaults -currentHost write -g com.apple.mouse.tapBehavior -int 1

三指拖移仅支持 GUI 操作：系统设置 → 辅助功能 → 指针控制 → 触控板选项 → 「使用触控板进行拖移」→ 「三指拖移」。

1.3 Finder — 显示隐藏文件、完整路径、扩展名

defaults write com.apple.finder AppleShowAllFiles -bool true
defaults write com.apple.finder _FXShowPosixPathInTitle -bool true
defaults write -g AppleShowAllExtensions -bool true
killall Finder

1.4 Dock — 自动隐藏，去除动画

释放屏幕空间，让 Dock 出现更快。

defaults write com.apple.dock autohide -bool true
defaults write com.apple.dock autohide-delay -float 0
defaults write com.apple.dock autohide-time-modifier -float 0.15
killall Dock

1.5 截图 — 保持桌面整洁

默认保存位置是桌面，会迅速杂乱。更改保存位置。

mkdir -p ~/Pictures/Screenshots
defaults write com.apple.screencapture location ~/Pictures/Screenshots
defaults write com.apple.screencapture type png
killall SystemUIServer

2. Xcode Command Line Tools — 5 分钟

Homebrew、Git 和编译器均依赖此工具。

xcode-select --install

弹出 GUI 对话框 → 安装 → 接受许可证 → 等待约 5 分钟（约 100MB）。

验证

xcode-select -p
# /Library/Developer/CommandLineTools  ← 期望输出

如果已安装完整的 Xcode.app，会看到 /Applications/Xcode.app/Contents/Developer — 同样正确。

3. Homebrew + 核心 CLI — 10 分钟

3.1 安装 Homebrew

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

完成后，安装程序会打印 PATH 配置说明。Apple Silicon — 将以下两行添加到 ~/.zprofile：

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

⚠️ Intel Mac：使用 /usr/local 替代 /opt/homebrew。安装程序打印的说明针对你的机器是正确的——按它来。

验证

brew --version
# Homebrew 4.x.x
brew doctor
# Your system is ready to brew.

3.2 一行安装七个核心 CLI

你每天都会用到的工具：

brew install git gh mise jq ripgrep fzf eza

工具	用途
`git`	比 Apple 内置 git 更新，支持现代 LFS 和插件
`gh`	GitHub CLI（PR、repo clone、认证）
`mise`	多语言运行时管理器（asdf 的继任者）— Node、Python、Ruby 等
`jq`	命令行 JSON 解析和转换
`ripgrep`	更快的 `grep` 替代品，遵守 `.gitignore`（`rg`）
`fzf`	交互式模糊搜索器（`Ctrl-R` 历史记录搜索）
`eza`	现代 `ls` 替代品（`exa` 的继任者），支持 git 状态和树形视图

fzf Shell 集成（可选）

启用 Ctrl+R 历史记录搜索：

$(brew --prefix)/opt/fzf/install --all

4. Git 配置 + SSH 密钥 — 10 分钟

4.1 Git 全局配置

使用与 GitHub 账户相同的邮箱。

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase false
git config --global core.editor "code --wait"  # 如果你使用 VS Code

code --wait 需要先安装 VS Code。如果还没安装，暂时跳过。

4.2 SSH 密钥 — 推荐 ed25519

比 RSA 4096 更短且更安全。

ssh-keygen -t ed25519 -C "you@example.com"
# 保存文件位置：[回车]（使用默认 ~/.ssh/id_ed25519）
# 输入密码：[可选但推荐]

注册到 ssh-agent 和 macOS 钥匙串：

eval "$(ssh-agent -s)"
 
cat <<'EOF' >> ~/.ssh/config
Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
EOF
 
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

4.3 将公钥添加到 GitHub + 认证

将公钥复制到剪贴板：

pbcopy < ~/.ssh/id_ed25519.pub

在浏览器中打开 https://github.com/settings/ssh/new → 标题："Mac（型号）" → 密钥：粘贴 → Add SSH key。

为 HTTPS 操作（PR 创建等）认证 gh：

gh auth login
# GitHub.com → HTTPS → Y（使用 GitHub 凭据认证 Git）→ 使用网络浏览器登录

浏览器将打开并显示一次性代码。输入后授权即可。

5. 验证 — 一切安装正确了吗？

一次性检查：

echo "--- 版本 ---"
sw_vers | head -2
brew --version | head -1
git --version
gh --version | head -1
mise --version
echo "--- GitHub 认证 ---"
ssh -T git@github.com 2>&1 | head -1
gh auth status 2>&1 | head -3

期望输出：

--- 版本 ---
ProductName: macOS
ProductVersion: 14.5
Homebrew 4.x.x
git version 2.46.x
gh version 2.x.x
mise 2026.x.x
--- GitHub 认证 ---
Hi <your-username>! You've successfully authenticated, but GitHub does not provide shell access.
github.com
  ✓ Logged in to github.com account <your-username>

一切正常打印后，你就完成了。现在可以 git clone <repo> 开始工作了。

6. 故障排除

"command not found: brew" — PATH 未加载

检查 ~/.zprofile 中是否包含 eval "$(/opt/homebrew/bin/brew shellenv)"。打开新终端后重试。

"xcrun: error: invalid active developer path"

Command Line Tools 损坏。重新安装：

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Homebrew 安装提示"Permission denied"

/opt/homebrew 或 /usr/local 权限问题。按安装程序建议的 chown 命令逐字执行。

SSH "Permission denied (publickey)"

ssh-add -l                              # 密钥是否在 agent 中？
ssh -vT git@github.com 2>&1 | tail -20  # 详细输出

如果密钥缺失，重新运行 ssh-add --apple-use-keychain ~/.ssh/id_ed25519。如果仍然失败，确认密钥已在 GitHub 上注册。

`git push` 一直要求密码

你用 HTTPS 克隆了仓库。切换远端到 SSH：

git remote set-url origin git@github.com:<user>/<repo>.git

部分 Homebrew 包在 Apple Silicon 上失败

少数旧包只能在 Rosetta 2 下运行：

softwareupdate --install-rosetta --agree-to-license
arch -x86_64 brew install <package>

下一步

本指南在"终端正常可用"处停止。接下来：

开发工具：编辑器、运行时（Node · Python · Ruby）— /mac/dev-toolchain
生产力工具：Raycast、Rectangle、Karabiner — /mac/productivity
AI 智能体环境：Claude Code、Cursor — /ai-agents/claude-code
自动化脚本已在本页顶部章节 ✅

参考资料

更新日志

2026-05-12 — 初始翻译（devAlice M2 i18n 种子）

新 Mac 开发者配置 — 开箱后第一个小时