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