---
tags: [macos, dev-env, onboarding]
create time: 2026-07-01 00:00
---

# macOS 开发环境配置指南

## 概述

面向 Mac 的通用开发环境搭建步骤，覆盖七牛云暑期实习开营前的工具链要求：Git / SSH、Node.js（nvm + pnpm）、TypeScript、Go（GOPROXY）、AI Coding Agent 和 GitHub CLI。按顺序执行即可，每条末尾附验证命令。

## 前置条件

- macOS 12 Monterey 或更高版本
- 系统自带 **Terminal**，推荐使用 **iTerm2**

```bash
brew install iterm2
```

## 一、Homebrew

详见 [[mac-dev-env-setup/homebrew-intro]]（安装步骤与常见命令在此简述，进阶用法见独立文档）。

Homebrew 是 macOS 最重要的包管理器，后续所有工具都通过它安装。

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

首次安装后把 brew 加入 PATH（ARM Mac / Intel Mac 不同，按终端输出的提示操作）：

```bash
# ARM Mac（M1/M2/M3/M4）
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Intel Mac
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

验证：

```bash
brew --version
```

### 常用 brew 命令速查

| 用途 | 命令 |
|------|------|
| 搜索 | `brew search <name>` |
| 安装 | `brew install <name>` |
| 卸载 | `brew uninstall <name>` |
| 升级所有已装包 | `brew upgrade` |
| 清理缓存 | `brew cleanup` |
| 列出可升级包 | `brew outdated` |

## 二、Git & SSH

详见 [[mac-dev-env-setup/git-ssh-config]]（双账号密钥路由、~/.ssh/config 配置机制、连接排障）。

```bash
brew install git
git --version     # 验证
```

### SSH Key 生成速查

```bash
# GitHub
ssh-keygen -t ed25519 -C "hezhaohui0807@163.com" -f ~/.ssh/id_ed25519_github

# Gitea
ssh-keygen -t ed25519 -C "hezhaohui0807@163.com" -f ~/.ssh/id_ed25519_gitea
```

公钥分别粘贴到对应平台的 SSH Keys 设置页。详细 Host 别名配置见子文档。

### Git 基础配置

```bash
git config --global user.name "hezhaohui"
git config --global user.email "hezhaohui0807@163.com"
git config --global core.autocrlf input
git config --global init.defaultBranch main
```

## 三、Node.js + pnpm

详见 [[mac-dev-env-setup/node-nvm-pnpm]]（nvm 版本管理机制、Corepack 零开销调度器、pnpm 硬链接存储模型）。

### nvm 速查

```bash
brew install nvm
mkdir -p ~/nvm
```

在 `~/.zshrc` 中追加（完整脚本见子文档）：

```bash
export NVM_DIR="$HOME/nvm"
[ -s "$(brew --prefix)/opt/nvm/nvm.sh" ] && . "$(brew --prefix)/opt/nvm/nvm.sh"
EOF
source ~/.zshrc
```

### pnpm

```bash
corepack enable
corepack prepare pnpm@latest --activate
```

详见子文档了解 Corepack 机制、pnpm workspace 与 store 管理。

### VS Code（推荐）

```bash
brew install --cask visual-studio-code
```

然后在 VS Code 中打开扩展面板，搜索并安装以下插件：
- ESLint
- Prettier
- TypeScript Debugger

## 四、TypeScript

```bash
npm install -g typescript
```

验证：

```bash
tsc -v        # 如 v5.6.3
```

## 五、Go

详见 [[mac-dev-env-setup/go-module-proxy]]（GOPROXY 代理链原理、GOSUMDB 校验机制、Go Workspace / vendor 模式）。

```bash
brew install go
go env -w GOPROXY=https://goproxy.cn,direct
```

验证：

```bash
go version          # 如 go1.23.x
go env GOPROXY      # 应输出：https://goproxy.cn,direct
```

### VS Code Go 插件

VS Code 扩展面板搜索安装 **Go**（by Gore-Multi），安装后会弹出提示是否安装 Go 工具链子组件，点 **Install All** 即可。

## 六、Python（按需）

如果所在组使用 Python 栈，提前装好：

```bash
brew install python@3.12
python3 -m pip install --upgrade pip
python3 -m venv ~/venvs/default
source ~/venvs/default/bin/activate
```

### uv（可选，更快的 Python 包管理器）

```bash
brew install uv
```

## 七、Java（按需）

```bash
brew install --cask temurin
# 或
brew install openjdk@17
```

在 `~/.zshrc` 中加入 JAVA_HOME：

```bash
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
```

## 八、GitHub CLI

详见 [[mac-dev-env-setup/gh-cli-commands]]（PR / Issue / Fork 常用命令与完整工作流）。

```bash
brew install gh
gh auth login          # 按提示登录 GitHub 账号
gh --version           # 验证
```

### 日常高频命令速查

| 操作 | 命令 |
|------|------|
| Clone 仓库 | `gh repo clone owner/repo` |
| Fork + 克隆 | `gh repo fork owner/repo` |
| Checkout PR | `gh pr checkout 12` |
| 创建 PR | `gh pr create --title "feat: xxx" --body "desc"` |
| 列出 Issues | `gh issue list --label bug` |
| 查看自己的 PR/Issue | `gh pr status` / `gh issue status` |
| 终端查看详情 | `gh pr view 42` / `gh issue view 42` |

> [!tip] gh + Claude Code 协作
> 先用 `gh issue list` 拉出任务，再让 Claude Code 在当前分支实现，比在浏览器切来切去高效得多。见 [[mac-dev-env-setup/ai-coding-agent]]。

## 九、AI Coding Agent — Claude Code

详见 [[mac-dev-env-setup/ai-coding-agent]]（Prompting 四原则、CLAUDE.md 上下文注入、与 gh CLI 组合工作流）。

### 安装

```bash
npm install -g @anthropic-ai/claude-code
```

### 首次运行

```bash
claude
```

按提示登录 Anthropic 账号并配置 API Key。

> [!info] 让 Claude Code 调用 GitHub CLI
> Claude Code 可以原生理解仓库上下文，配合 `gh` 使用效果更好：先 `gh issue list` 查看任务，再让 Claude Code 直接在当前分支实现。

## 十、VS Code 常用插件汇总

| 插件名 | 用途 |
|--------|------|
| Go | Go 语言支持 |
| ESLint | JS/TS 代码检查 |
| Prettier | 代码格式化 |
| GitLens | Git 增强 |
| Error Lens | 行内错误提示 |
| Thunder Client | API 调试（替代 Postman） |
| Todo Tree | 自动收集 TODO/FIXME |
| Remote - SSH | SSH 远程开发 |
| Docker | Dockerfile / compose 支持 |

一键批量安装（保存为 `extensions.txt` 后运行 `code --install-extension $(cat extensions.txt)`）：

```text
golang.go
dbaeumer.vscode-eslint
esbenp.prettier-vscode
eamodio.gitlens
bierner.markdown-preview-github-styles
mutantdino.resourcemonitor
```

## 关联笔记
- [[weekly/00-week-zero-prep-guide]] — 开营前预习指南（总览）
- [[mac-dev-env-setup/homebrew-intro]] — Homebrew 深度指南
- [[mac-dev-env-setup/git-ssh-config]] — Git & SSH 双账号路由与排障
- [[mac-dev-env-setup/node-nvm-pnpm]] — nvm / Corepack / pnpm 工作原理
- [[mac-dev-env-setup/go-module-proxy]] — Go Module 代理链与校验机制
- [[mac-dev-env-setup/gh-cli-commands]] — GitHub CLI 常用命令与工作流
- [[mac-dev-env-setup/ai-coding-agent]] — AI 编码提示词策略与安全边界