适用场景
Claude Code 是跑在终端里的编程助手：在项目目录下启动后，它能读取文件、修改代码、执行构建与测试命令，把「提问—改代码—跑验证」串成一条流水线。
这篇教程解决三件事：在 macOS 与 Windows 上把 Claude Code 装起来；把 API Key、网络代理、中转网关这些环境变量配对；撞上装不上、连不通、认证失败的报错时，知道从哪儿下手排查。
适合两类人：想在本地命令行里用 AI 辅助编码的开发者，以及需要在代理或内网环境下把 Claude Code 接进团队工作流的运维同学。
环境与前置条件
先把下面这张清单和实际环境对一遍：
- 操作系统：macOS（Intel 与 Apple Silicon 均可）、Linux 主流发行版、Windows 10/11。Windows 上有两条路——WSL2，或者原生 Windows 配合 Git for Windows 提供的 Bash 环境。
- 运行时：走 npm 安装需要预装 Node.js 与 npm，最低版本要求以官方文档当前版本为准，装 LTS 版本即可。走原生安装脚本则由脚本自带运行时，不需要预装 Node。
- 硬件：终端工具本身占用很小，内存 8 GB 及以上比较从容；磁盘建议留出 2 GB 左右余量给运行时和依赖缓存。另外每个项目都会产生会话记录，长期使用会慢慢增长。
- 网络：需要能访问 Anthropic 的接口。在需要代理的网络里，或者通过企业网关接入时，提前准备好代理地址或网关地址及令牌。
- 账号凭证：二选一。Claude 订阅账号（浏览器授权登录），或 Anthropic Console 的 API Key。
- 权限：全局安装 npm 包要写系统目录，建议用 nvm 这类版本管理器，避免用 sudo 引发后续的权限归属问题。
分步骤部署
第 1 步：确认终端与运行时
打开终端（macOS 用 Terminal 或 iTerm，Windows 用 PowerShell 或 Windows Terminal），执行：
```
node -v
npm -v
```
能打印出版本号，说明运行时齐了。如果提示命令不存在，先装 Node.js：macOS 可以 brew install node，Windows 可以从 Node.js 官网下载 LTS 安装包，或用 winget、scoop 等包管理器安装。装完重开终端，再执行上面两条命令。
第 2 步：安装 Claude Code
方式一：npm 全局安装
```
npm install -g @anthropic-ai/claude-code
```
安装过程会打印一堆包解析日志，末尾出现 added N packages 之类的提示即为成功。注意不要在前面加 sudo，也不要以管理员身份运行——提权安装会让后续升级和配置目录的归属变乱。
方式二：原生安装脚本
官方文档同时提供 macOS/Linux 的 shell 脚本和 Windows 的 PowerShell 脚本，命令会随版本调整，去官方文档复制当前那条即可：macOS/Linux 通常是 curl ... | bash 形式，Windows 通常是 irm ... | iex 形式。这种方式不依赖 Node。
安装完成后可能需要重开终端，让 PATH 变更生效。
第 3 步：确认命令可用
```
claude --version
```
打印出版本号，说明可执行文件已经进了 PATH。再跑一次自检：
```
claude doctor
```
它会检查安装方式、运行时版本、配置目录、网络连通性等项目。每一项都能看到状态，异常项会附带建议。
第 4 步：登录或配置凭证
在任意目录执行：
```
claude
```
首次运行会引导选择登录方式。走订阅账号时选浏览器授权：终端给出一个链接，浏览器打开、确认授权，再把页面上的验证码粘回终端。授权成功后终端会显示当前账号和可用模型。
如果改用 API Key，macOS / Linux 下：
```
export ANTHROPIC_API_KEY="你的密钥"
```
Windows PowerShell 当前会话：
```
$env:ANTHROPIC_API_KEY="你的密钥"
```
Windows 想永久写入用户环境变量：
```
setx ANTHROPIC_API_KEY "你的密钥"
```
setx 设完必须新开一个终端窗口才生效。macOS/Linux 想永久生效，把 export 那行写进 ~/.zshrc（zsh）或 ~/.bashrc（bash），再 source 一次。
第 5 步：配置网络代理
终端进程不会自动继承系统代理设置，需要单独指定。macOS / Linux：
```
export HTTPS_PROXY="http://127.0.0.1:7890"
export HTTP_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"
```
Windows PowerShell：
```
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"
```
端口换成自己代理软件实际监听的端口。NO_PROXY 里的本地地址不要带端口号，按主机名写。
第 6 步：接入中转网关（可选）
用企业网关或第三方中转服务时，改的是接口地址，而不是密钥字段：
```
export ANTHROPIC_BASE_URL="https://你的网关地址"
export ANTHROPIC_AUTH_TOKEN="网关分配的令牌"
```
网关地址和令牌向服务提供方索取。具体变量名与取值以官方文档当前版本为准，配完建议重开终端再验证。
第 7 步：写一份 settings.json
除了环境变量，也可以用配置文件统一管理。用户级配置放在 ~/.claude/settings.json（Windows 是 C:\Users\你的用户名\.claude\settings.json）：
```json
{
"env": {
"HTTPS_PROXY": "http://127.0.0.1:7890"
},
"permissions": {
"allow": [
"Read",
"Bash(git status)",
"Bash(npm run test:*)"
],
"deny": [
"Bash(rm -rf:*)"
]
}
}
```
env 里的键值会在启动时注入进程，等于把代理、网关地址固化下来，不必每次手敲 export。permissions.allow 是白名单，列进去的操作不再逐次询问；permissions.deny 是黑名单，优先级更高。字段名与可写项以官方文档为准，改完用 claude doctor 确认能被正确解析。
第 8 步：在项目里初始化
```
cd 你的项目目录
claude
```
进去后执行斜杠命令 /init，它会扫描项目结构并生成一份 CLAUDE.md，把技术栈、目录约定、常用命令记进去。之后每次会话启动都会读取这份文件，省掉重复交代背景的功夫。CLAUDE.md 建议提交进版本库，团队共用。
常用的斜杠命令：/help 看全部命令，/config 交互式改配置，/model 切换模型，/permissions 管理权限，/clear 清空当前上下文。
验证部署是否成功
分三层验证，逐层排除问题。
第一层，命令是否可用：
```
claude --version
claude doctor
```
预期：前者打印版本号；后者各项检查状态正常，没有报错项。
第二层，凭证是否有效。 新建一个空目录做隔离测试：
```
mkdir ~/cc-test && cd ~/cc-test
claude -p "用一句话说明当前目录里有哪些文件"
```
-p 是非交互模式，跑完直接退出。预期几秒内输出一句描述当前目录内容的文字。如果卡住不动或报认证错误，说明网络或凭证有问题。
第三层，在真实项目里跑一次只读任务：
```
cd 你的项目目录
claude -p "总结一下这个项目的目录结构"
```
预期它会列出目录、读取若干文件后给出结构化总结。这一步能过，说明文件读取、权限确认、模型调用三个环节都已打通。
常见报错与解决
报错 1：npm error code EACCES 或 permission denied
原因：全局安装要写系统目录，当前用户没有写权限。
解决：不要用 sudo。改用 Node 版本管理器重装 Node，或者把全局目录挪到用户家目录：
```
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm install -g @anthropic-ai/claude-code
```
export 那行记得写进 shell 配置文件持久化。
报错 2：claude: command not found（Windows 上提示「不是内部或外部命令」）
原因：npm 全局可执行文件目录不在 PATH 里，或者装完没有重开终端。
解决：先看全局目录在哪：
```
npm config get prefix
```
macOS/Linux 把 <prefix>/bin、Windows 把 <prefix> 加进 PATH，然后重开终端。刚装完就执行 claude --version 失败，多半是没重开终端。
报错 3（Windows）：提示需要 Git Bash，或 No such file or directory
原因：原生 Windows 下 Claude Code 依赖 Git for Windows 提供的 Bash 环境，没装 Git，或安装路径没被识别到。
解决：从 Git for Windows 官网下载安装，再重开终端。装了仍报错的话，显式指定 bash 路径：
```
setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
```
重开终端后再跑 claude doctor。也可以用 WSL2 绕过这类路径问题。
报错 4：fetch failed、ETIMEDOUT、ECONNRESET
原因：终端进程连不上接口，通常是没走代理，或者代理软件只开了系统代理而终端不继承。
解决：按第 5 步显式设置 HTTPS_PROXY，先用 curl 验证代理链路：
```
curl -x http://127.0.0.1:7890 -I https://api.anthropic.com
```
能返回 HTTP 状态码说明代理正常，再回去跑 claude doctor。注意终端里设的代理只在当前窗口有效。
报错 5：401 Unauthorized 或 Invalid API key
原因：密钥错误、过期、被撤销，或者环境变量里的 Key 与登录账号互相冲突。
解决：先确认变量确实传进了进程：
```
echo $ANTHROPIC_API_KEY
```
Windows 用 echo $env:ANTHROPIC_API_KEY。确认无误后，在 Claude Code 里执行 /login 重新授权，或到 Console 重新生成密钥。如果同时存在订阅登录和 API Key，清掉不用的那个，避免指向混乱。
报错 6：SELF_SIGNED_CERT_IN_CHAIN 或 unable to verify the first certificate
原因：公司网络做了 HTTPS 中间人解密，Node 不认这张自签证书。
解决：拿到公司根证书文件，指给 Node：
```
export NODE_EXTRA_CA_CERTS="/path/to/company-ca.pem"
```
Windows 用 setx NODE_EXTRA_CA_CERTS "C:\path\to\company-ca.pem"，之后重开终端。
报错 7：EBADENGINE 或提示 Node 版本过低
原因：Node 版本低于官方要求。
解决：升级到当前 LTS。用 nvm 的话：
```
nvm install --lts
nvm use --lts
```
升级后重装一遍全局包，再 claude doctor 复查。
后续维护
配置与数据备份
需要备份的是 ~/.claude/ 目录（Windows 为 %USERPROFILE%\.claude），里面有 settings.json、会话记录、项目级缓存。换机器或重装系统前整目录拷走即可。项目里的 CLAUDE.md 和 .claude/ 跟着代码仓库走，不必单独备份。
凭证与密钥安全
不要把 API Key 写进项目配置文件再提交到版本库。团队协作时，个人配置放 .claude/settings.local.json 并加进 .gitignore；共享的团队配置放 .claude/settings.json，里面只放不含密钥的项。
升级
npm 方式安装的：
```
npm update -g @anthropic-ai/claude-code
```
原生脚本安装的，用官方提供的更新方式（部分安装器自带更新子命令，以官方文档为准）。升级后跑一遍 claude doctor，确认配置仍能解析——配置格式偶尔会调整，报错时对照官方文档改字段名。
日志与排查
会话记录按项目存放在 ~/.claude/projects/ 下，出问题时先去这里找最近一次会话。终端侧的异常用 claude doctor 做整体体检，用 claude --debug 启动查看详细请求日志。长期不用的旧会话可以定期清理，磁盘占用主要来自这块。
权限边界
默认情况下，涉及写文件、执行命令的操作会逐次询问。批量任务里有人会用跳过权限确认的参数（--dangerously-skip-permissions），它意味着不再逐条拦截，只建议在容器、临时目录这类可随时丢弃的环境里使用。日常开发更稳的做法是在 settings.json 里把常用只读命令加进 allow，把危险命令（递归删除、强制推送等）写进 deny。
用量与成本
订阅账号和 API Key 的计费方式不同，额度与用量口径以官方页面为准。团队里可以把项目约定写进 CLAUDE.md，减少反复澄清带来的无效往返；需要了解当前会话消耗时，用 /cost 之类的命令查看。