番外篇 —— macOS 上从零搭一套 Claude Code 开发环境

前面九章一直在讲服务器硬件，这篇是个番外。一台日常写代码的 MacBook 也得有一套顺手的工具链——Homebrew 装包、Node 跑 JS、VS Code 写代码、Claude Code 当结对编程伙伴。这里把”国内网络环境下能一次跑通”的最小步骤记下来，本机和新机都能照搬。

这篇只解决四件事

  1. 装 Homebrew，并把它切到清华源（避免被官方源卡住）。
  2. 装 Node.js / npm，npm registry 切到国内源。
  3. 手动从官网下载 VS Code 安装。
  4. 手动装 Claude Code 插件，并在用户级 settings.json 里填好自定义 API。

不装 Claude Code CLI——本文只面向插件用户，CLI 用得到再单独折腾。

1. 安装 Homebrew（清华源）

官方安装脚本要从 GitHub 拉脚本和仓库，国内常常超时。按清华 TUNA 镜像的官方做法来：先设好环境变量，再用镜像版安装脚本装，这样首次安装拉仓库就直接走清华。

macOS 自带 bash、git、curl，但还需要 Command Line Tools。如果没装过，先跑 xcode-select --install。

第一步，在终端设置环境变量，让安装脚本从清华拉 brew 本体和 core 仓库：

1
2
3
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
export HOMEBREW_INSTALL_FROM_API=1

第二步，从清华克隆安装脚本并执行：

1
2
3
git clone --depth=1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git brew-install
/bin/bash brew-install/install.sh
rm -rf brew-install

第三步，把 brew 的路径写进 shell 配置（Apple Silicon 默认装在 /opt/homebrew，Intel 在 /usr/local，且无需这步）：

1
2
3
# 仅 Apple Silicon（uname -m 输出 arm64）需要
test -r ~/.zprofile && echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

第四步，把上面那两个 git 源环境变量也持久化进 profile，这样以后每次 brew update 都会自动走清华，不会被改回 GitHub：

1
2
test -r ~/.zprofile && echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"' >> ~/.zprofile
test -r ~/.zprofile && echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"' >> ~/.zprofile

第五步，把 bottle 二进制包下载也切到清华（不然装包还是会去 GitHub 拉预编译包）：

1
2
3
echo 'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zprofile
echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zprofile
source ~/.zprofile

最后验证：

1
2
brew update
brew --version

自 brew 4.0 起 HOMEBREW_INSTALL_FROM_API=1 已是默认行为，大部分人其实无需克隆 homebrew-core 仓库、也无需设 HOMEBREW_CORE_GIT_REMOTE，只要 HOMEBREW_API_DOMAIN 走镜像即可。但设上 core 源不影响使用，遇到要跑 brew cat 之类开发命令时反而省事，这里就一并配齐。

2. 安装 Node.js 和 npm

直接用 brew 装 LTS 版本就够用。

1
2
3
brew install node
node -v   # v22.x.x 之类
npm -v    # 10.x.x 之类

把 npm registry 切到国内镜像（淘宝维护的 npmmirror，是目前最稳定、和官方同步最及时的国内源）：

1
2
3
4
5
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry
# 应输出 https://registry.npmmirror.com/

如果你坚持用清华源，可以试 https://mirrors.tuna.tsinghua.edu.cn/npm/，但 npm 的同步频率不如 npmmirror 高，遇到新发布的包可能拉不到。我个人长期用 npmmirror。

到这里，命令行基础工具就备齐了。

3. 手动安装 VS Code

不用 brew install --cask——国内访问 VS Code 官方下载有 CDN 加速节点，手动下反而更快、版本更新。

  1. 浏览器打开 https://code.visualstudio.com/
  2. 点击 Download Mac，选 Apple Silicon 或 Intel chip（uname -m 查：arm64 是 Apple Silicon）
  3. 下载下来是一个 .zip，双击解压得到 Visual Studio Code.app
  4. 把它拖到 /Applications 文件夹——不放进 Applications 系统会反复弹”是否移到应用程序”
  5. 第一次打开时 Gatekeeper 会确认一下，点”打开”

可选但推荐的一步：装好以后，在 VS Code 里按 Cmd + Shift + P，搜索并执行 Shell Command: Install 'code' command in PATH，这样终端里就能用 code . 在当前目录打开 VS Code。

4. 手动安装 Claude Code 插件

VS Code 应用内的插件市场是直连微软 Marketplace，国内不一定稳。两种装法挑一种顺手的：

方式一：插件市场（顺利的话最快）

  1. VS Code 左侧活动栏点扩展图标（或 Cmd + Shift + X）
  2. 搜 Claude Code，发布者是 Anthropic
  3. 点 Install

方式二：手动下 VSIX（市场连不上时备用）

  1. 浏览器打开 https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code
  2. 右侧 “Resources” 区域点 Download Extension，得到一个 .vsix 文件
  3. 回到 VS Code，按 Cmd + Shift + P，执行 Extensions: Install from VSIX...，选刚下的文件

装完左侧活动栏会多一个 Claude 图标，点开会提示登录或填 API Key——这一步先不管，下一节统一用配置文件搞定。

5. 配置自定义 OpenAI Compatible API

Claude Code 插件读 用户级的配置文件 ~/.claude/settings.json，里面 env 段定义的环境变量会在每次启动时注入到 Claude 进程里。把自定义 API 信息塞这里就行——既不污染全局 shell 环境，也方便迁机器。

5.1 准备目录和文件

1
2
mkdir -p ~/.claude
touch ~/.claude/settings.json

5.2 填入 API 配置

用 VS Code 打开它：

1
code ~/.claude/settings.json

填入下面的内容，把三个 xxx 换成你提供商给的实际值：

1
2
3
4
5
6
7
8
9
10
11
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-provider.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxxxxxx",
    "ANTHROPIC_MODEL": "anthropic/claude-opus-4.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-4.7",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "anthropic/claude-sonnet-4.6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "anthropic/claude-haiku-4.5",
    "CLAUDE_CODE_SUBAGENT_MODEL": "anthropic/claude-haiku-4.5"
  }
}

字段含义：

字段 说明
ANTHROPIC_BASE_URL 自定义 API 端点，不要带末尾的斜杠，也不要带 /v1 路径。SDK 会自己拼 /v1/messages。
ANTHROPIC_AUTH_TOKEN 你的 API Key。这个变量名比 ANTHROPIC_API_KEY 优先级高，且兼容更多第三方网关。
ANTHROPIC_MODEL 默认走的模型 ID，按提供商支持的填。Claude 官方家族是 claude-opus-4-7 / claude-sonnet-4-6 / claude-haiku-4-5 这一代。

前提：你的提供商必须直接支持 Anthropic Messages API 格式（路径是 /v1/messages）。市面上常见的 OpenRouter、One-API、New-API、各种自建网关默认都开了这条兼容路径。如果你的提供商只有 OpenAI 格式（/v1/chat/completions），那需要在中间架一层 LiteLLM 之类的转换代理——这超出本文范围，先不展开。

5.3 重启 VS Code，验证

把 VS Code 完全退出（Cmd + Q，不是关窗口），然后从终端重新启动：

1
code .

打开 Claude 插件面板，问一句 “你好”，能正常返回就成了。

6. 一些容易踩的坑

端点路径写错了

ANTHROPIC_BASE_URL 要写到域名级别，例如 https://api.example.com，不要写成 https://api.example.com/v1 或 https://api.example.com/v1/messages。SDK 内部会拼路径，重复拼会变成 /v1/v1/messages 直接 404。

改了配置没生效

VS Code 的窗口进程在启动时读一次环境变量，之后改 settings.json 需要完全退出（Dock 上图标消失）再重开，不只是关窗口。

Key 报 401

先用 curl 直接打你的端点确认 Key 本身是好的：

1
2
3
4
5
6
7
8
9
curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "ping"}]
  }'

anthropic-version 这个头不是日期戳，而是 API 的稳定版本号，官方至今一直就是 2023-06-01，它不会随模型更新而变，照抄就行——真正要跟模型对应着改的是请求体里的 model 字段。

返回正常 JSON，就说明端点和 Key 都没问题，问题在插件配置；返回 401，先去提供商后台核对 Key。

模型名对不上

不同网关给 Claude 模型起的别名不一样——有些用官方 ID（claude-sonnet-4-5），有些自己改名（anthropic/claude-sonnet-4、claude-3.5-sonnet-latest）。报 model not found 时去提供商文档里翻一下它支持的模型列表，把 ANTHROPIC_MODEL 换成对应名字。

小结

整套流程下来，本机就有了：

  • 走清华源的 Homebrew，装包不再卡。
  • 走 npmmirror 的 Node.js / npm，未来要装 JS 工具链都顺。
  • 官网下载安装的 VS Code，更新最及时。
  • 手动装好的 Claude Code 插件，靠用户级 ~/.claude/settings.json 接到自定义 API。

整套配置不污染全局 shell 环境，换台机器把 ~/.claude/settings.json 拷过去就能继续用。