Qiniu/technical/mac-dev-env-setup.md

tags, create time

tags	create time
macos dev-env onboarding	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

brew install iterm2

一、Homebrew

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

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

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

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

# 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

验证：

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 配置机制、连接排障）。

brew install git
git --version     # 验证

SSH Key 生成速查

# 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 基础配置

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 速查

brew install nvm
mkdir -p ~/nvm

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

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

pnpm

corepack enable
corepack prepare pnpm@latest --activate

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

VS Code（推荐）

brew install --cask visual-studio-code

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

• ESLint
• Prettier
• TypeScript Debugger

四、TypeScript

npm install -g typescript

验证：

tsc -v        # 如 v5.6.3

五、Go

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

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

验证：

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 栈，提前装好：

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

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

brew install uv

七、Java（按需）

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

在 ~/.zshrc 中加入 JAVA_HOME：

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

八、GitHub CLI

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

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 组合工作流）。

安装

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

首次运行

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)）：

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 编码提示词策略与安全边界