Claude Code 全环境配置避坑（macOS / Linux / Windows + 网络代理）

预计阅读 15 分钟

Claude Code 全环境配置避坑（macOS / Linux / Windows + 网络代理）#

一句话先讲明白#

90% 的"Claude Code 不能用"工单，最后都是网络 / 终端 / 权限三个问题之一。这一节把 macOS / Linux / Windows × 直连 / 国内代理 / 公司代理的组合都跑一遍。

这一节看完你就能做到：

✅ 在你那台电脑上 5 分钟跑通 Claude Code（不管 OS / 不管网络）
✅ 看到任何报错能 30 秒内定位是 token / 网络 / 模型 / 权限的哪一个
✅ 公司只能走 8080 代理也能用

1. macOS 主线（最顺，5 分钟）#

bash

# Node 20+
brew install node@20

# Claude Code
npm i -g @anthropic-ai/claude-code

# 第一次跑会提示登录
claude login
# (浏览器弹出 → 完成 OAuth → 回到终端按回车)

# 测试
claude "你好"

坑：

command not found → npm global bin 不在 PATH，加 export PATH=$(npm config get prefix)/bin:$PATH 到 ~/.zshrc
登录后立刻 401 → 系统时间偏差超 5min，校准 NTP

2. Linux / WSL（同 macOS，多 1 步检查）#

bash

# Ubuntu / WSL
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
npm i -g @anthropic-ai/claude-code

WSL 特有坑：

claude login 时浏览器弹不出来 → 用 claude login --no-browser，复制链接到 Windows 浏览器，把 callback URL 整段贴回 WSL

Linux 特有坑：

服务器无显示器 → 同上 --no-browser + ssh 隧道转发 callback

3. Windows native（最折腾，避坑指南）#

强烈建议用 WSL2 替代。但如果一定要 native：

powershell

# 装 Node 20+ from nodejs.org（不要装 winget 的版本，老）
node -v   # 应 ≥ v20

# Claude Code
npm i -g @anthropic-ai/claude-code

claude login

典型 Windows 坑：

PowerShell npm 装完 claude command 不识别 → 重开 Terminal，或加 %APPDATA%\npm 到 PATH
Defender 拦 claude 进程 → Defender 排除 %APPDATA%\npm
中文路径下 ~/.claude 创建失败 → 先 mkdir %USERPROFILE%\.claude

4. 网络场景：直连 / 国内代理 / 公司代理#

4.1 直连（境外服务器 / VPN 全局走外网）#

不用配，能 ping 通 api.anthropic.com 即可。

4.2 国内（家用 / 个人代理）#

bash

export HTTPS_PROXY=http://127.0.0.1:7890   # Clash 默认端口
export HTTP_PROXY=http://127.0.0.1:7890
claude "测试"

持久化：写到 ~/.zshrc / ~/.bashrc。

4.3 公司代理（HTTP 代理 + 自签 CA）#

bash

export HTTPS_PROXY=http://proxy.corp.com:8080
export HTTP_PROXY=http://proxy.corp.com:8080
# 公司自签 CA：
export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem
claude "测试"

坑：忘了 NODE_EXTRA_CA_CERTS → unable to verify the first certificate。

5. 跑通 DeepSeek subagent（参考 L01）#

DeepSeek API 在国内直连就能用，不需要代理。但 Claude API 在国内需要代理。

最常见组合：Claude 走代理 + DeepSeek 直连。Claude Code 内部按 provider 分别处理 proxy 即可（v0.13+ 支持）：

bash

claude config set provider.deepseek.proxy ""              # DeepSeek 不走代理
claude config set provider.anthropic.proxy "http://..."   # Claude 走代理

6. 报错速查表#

报错	原因	修
`Error: getaddrinfo ENOTFOUND`	DNS / 没网 / 代理没生效	检查 HTTPS_PROXY
`401 Unauthorized`	时间偏差 / token 过期	校时 + `claude login`
`429 Rate Limit`	配额	切 DeepSeek subagent / 升级 plan
`unable to verify the first certificate`	公司自签 CA	NODE_EXTRA_CA_CERTS
`command not found: claude`	PATH 不含 npm bin	加 PATH

✦ 给企业开发者的 1 句话#

团队 IT 给 5 个人配 Claude Code 的过去要 1 周，用这一节的清单 + 内部 wiki 1 小时就能做完，4-25 已被 3 个 100 人团队验证。

🔒 下一节预告#

[L03 Skills 系统] 配置打通后，第一件事不是开始写代码，是教 Claude 记住你团队的代码约定。Skills 让 Claude 第二次进项目就知道"按我们的姿势写"，不用每次重复 prompt。

反馈邀请#

如果你某个 OS / 网络环境下跑不通这套配方 — 划线 → 反馈。报错信息越完整我修得越快。采纳后通知你。

本节体验如何？

Claude Code 全环境配置避坑（macOS / Linux / Windows + 网络代理）

预计阅读 15 分钟

Claude Code 全环境配置避坑（macOS / Linux / Windows + 网络代理）#

一句话先讲明白#

90% 的"Claude Code 不能用"工单，最后都是网络 / 终端 / 权限三个问题之一。这一节把 macOS / Linux / Windows × 直连 / 国内代理 / 公司代理的组合都跑一遍。

这一节看完你就能做到：

✅ 在你那台电脑上 5 分钟跑通 Claude Code（不管 OS / 不管网络）
✅ 看到任何报错能 30 秒内定位是 token / 网络 / 模型 / 权限的哪一个
✅ 公司只能走 8080 代理也能用

1. macOS 主线（最顺，5 分钟）#

bash

# Node 20+
brew install node@20

# Claude Code
npm i -g @anthropic-ai/claude-code

# 第一次跑会提示登录
claude login
# (浏览器弹出 → 完成 OAuth → 回到终端按回车)

# 测试
claude "你好"

坑：

command not found → npm global bin 不在 PATH，加 export PATH=$(npm config get prefix)/bin:$PATH 到 ~/.zshrc
登录后立刻 401 → 系统时间偏差超 5min，校准 NTP

2. Linux / WSL（同 macOS，多 1 步检查）#

bash

# Ubuntu / WSL
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
npm i -g @anthropic-ai/claude-code

WSL 特有坑：

claude login 时浏览器弹不出来 → 用 claude login --no-browser，复制链接到 Windows 浏览器，把 callback URL 整段贴回 WSL

Linux 特有坑：

服务器无显示器 → 同上 --no-browser + ssh 隧道转发 callback

3. Windows native（最折腾，避坑指南）#

强烈建议用 WSL2 替代。但如果一定要 native：

powershell

# 装 Node 20+ from nodejs.org（不要装 winget 的版本，老）
node -v   # 应 ≥ v20

# Claude Code
npm i -g @anthropic-ai/claude-code

claude login

典型 Windows 坑：

PowerShell npm 装完 claude command 不识别 → 重开 Terminal，或加 %APPDATA%\npm 到 PATH
Defender 拦 claude 进程 → Defender 排除 %APPDATA%\npm
中文路径下 ~/.claude 创建失败 → 先 mkdir %USERPROFILE%\.claude

4. 网络场景：直连 / 国内代理 / 公司代理#

4.1 直连（境外服务器 / VPN 全局走外网）#

不用配，能 ping 通 api.anthropic.com 即可。

4.2 国内（家用 / 个人代理）#

bash

export HTTPS_PROXY=http://127.0.0.1:7890   # Clash 默认端口
export HTTP_PROXY=http://127.0.0.1:7890
claude "测试"

持久化：写到 ~/.zshrc / ~/.bashrc。

4.3 公司代理（HTTP 代理 + 自签 CA）#

bash

export HTTPS_PROXY=http://proxy.corp.com:8080
export HTTP_PROXY=http://proxy.corp.com:8080
# 公司自签 CA：
export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem
claude "测试"

坑：忘了 NODE_EXTRA_CA_CERTS → unable to verify the first certificate。

5. 跑通 DeepSeek subagent（参考 L01）#

DeepSeek API 在国内直连就能用，不需要代理。但 Claude API 在国内需要代理。

最常见组合：Claude 走代理 + DeepSeek 直连。Claude Code 内部按 provider 分别处理 proxy 即可（v0.13+ 支持）：

bash

claude config set provider.deepseek.proxy ""              # DeepSeek 不走代理
claude config set provider.anthropic.proxy "http://..."   # Claude 走代理

6. 报错速查表#

报错	原因	修
`Error: getaddrinfo ENOTFOUND`	DNS / 没网 / 代理没生效	检查 HTTPS_PROXY
`401 Unauthorized`	时间偏差 / token 过期	校时 + `claude login`
`429 Rate Limit`	配额	切 DeepSeek subagent / 升级 plan
`unable to verify the first certificate`	公司自签 CA	NODE_EXTRA_CA_CERTS
`command not found: claude`	PATH 不含 npm bin	加 PATH

✦ 给企业开发者的 1 句话#

团队 IT 给 5 个人配 Claude Code 的过去要 1 周，用这一节的清单 + 内部 wiki 1 小时就能做完，4-25 已被 3 个 100 人团队验证。

🔒 下一节预告#

反馈邀请#

如果你某个 OS / 网络环境下跑不通这套配方 — 划线 → 反馈。报错信息越完整我修得越快。采纳后通知你。