Claude Code 安装与配置教程

适用场景

Claude Code 是 Anthropic 提供的命令行编码助手，直接在终端里工作，能读你的仓库、改文件、跑测试、执行 git 操作。这套方案适合两类人：一是每天写代码、受够了「复制到网页对话框再粘贴回来」的开发者；二是想把 AI 编码能力接进脚本或 CI 流水线、做自动化改动的团队。

它和网页版最大的区别是有工作目录。你在哪个项目的目录下启动它，它就能看到那个项目的文件，改动直接落地在磁盘上，之后用 git diff 就能审查。对运维同学来说，也常用来批量改配置文件、写迁移脚本、排查日志。

环境与前置条件

关于 git 这一条值得多说一句：Claude Code 大量依赖 git 来追踪「我改了什么」，没有 git 时它能改文件，但你审查和回滚会非常痛苦。新项目第一件事就是 git init，老项目确保工作区是干净的再启动。

分步骤部署

步骤 1：确认 Node.js 环境

先看当前环境里有没有可用的 Node：

```bash

node -v

npm -v

```

成功输出形如 v22.11.0 和 10.9.0。如果提示 command not found，说明还没装 Node.js。

强烈建议用版本管理工具装，而不是从系统包管理器直接装。macOS/Linux 上可以用 nvm，Windows 上可以用 nvm-windows 或 fnm，安装方式以各自官方仓库的说明为准。原因很实际：系统级 Node 装出来的 npm 全局目录通常属于 root，后面装全局包时会出现权限报错（见「常见报错」第 1 条）。

装好之后新开一个终端窗口，再执行一次 node -v 确认生效。

步骤 2：安装 Claude Code

npm 全局安装，一行命令：

```bash

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

```

这一步在做什么：从 npm 源下载 Claude Code 包并把它注册成全局命令 claude。成功时终端会输出类似 added 3 packages in 8s 的内容，没有红色 ERR 字样。

一个提醒：不要习惯性加 sudo。加了 sudo 装出来的包属于 root，之后升级、改配置都可能因为权限问题卡住，而且报错信息往往很隐晦。

除了 npm，官方通常也会提供原生安装脚本或系统包方式，具体可用渠道以官方文档当前版本为准。选一种就行，不要叠加安装，避免出现两个 claude 命令互相打架。

步骤 3：Windows 用户选一条路线

Windows 有两条路，选哪条取决于你的工作习惯。

路线 A：WSL2（推荐）

如果你的日常开发涉及 Python、Docker、Makefile、shell 脚本，走 WSL2 会顺很多，因为 Claude Code 调用的命令和工具链跟 Linux 保持一致。

```powershell

wsl --install -d Ubuntu

```

装完重启，进入 Ubuntu 终端后，把步骤 1 和步骤 2 按 Linux 的方式重做一遍。注意 WSL 里的 Node 和 Windows 里的 Node 是两套，别混用。

路线 B：原生 PowerShell

直接在 PowerShell 里跑步骤 1、步骤 2 的命令即可。原生环境下有两个额外注意点：一是 Node.js 要装 Windows 版本，二是 PowerShell 默认可能禁止执行脚本，第一次启动 claude 时如果报脚本策略错误，见「常见报错」第 6 条。

步骤 4：首次启动与登录

```bash

claude

```

第一次运行会进入授权流程，通常有两种方式：订阅账号走浏览器 OAuth，登录后回到终端自动完成；Console 账号则填入 API Key。登录态会写入本地配置目录，之后不用每次登录。

启动成功的标志是出现一个交互式会话界面，底部有输入框，可以输入自然语言。这时随便输一句 这个目录里有哪些文件？ 试试，它应该能列出当前目录内容。

想退出会话，输入 /exit 或按两次 Ctrl+C。

步骤 5：配置环境变量

环境变量主要解决三件事：认证、代理、模型选择。

macOS / Linux / WSL，编辑 ~/.zshrc 或 ~/.bashrc：

```bash

export ANTHROPIC_API_KEY="你的 API Key"

export ANTHROPIC_BASE_URL="https://api.anthropic.com"

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,::1"

```

逐条说明：

• ANTHROPIC_API_KEY：使用 Console 账号时必填。如果你用订阅账号登录，通常不需要设置这一项，设置了反而可能覆盖登录态。
• ANTHROPIC_BASE_URL：走官方端点时可以不写；使用企业网关或自建代理转发时，改成网关地址。
• HTTPS_PROXY / HTTP_PROXY：网络受限时填本地代理端口，端口号以你实际代理软件的设置为准。
• NO_PROXY：把本机地址排除在代理之外，避免本地服务被绕一圈。

改完执行 source ~/.zshrc（或对应文件）让它生效。

Windows PowerShell：

```powershell

setx ANTHROPIC_API_KEY "你的 API Key"

setx HTTPS_PROXY "http://127.0.0.1:7890"

```

setx 写的是用户级持久变量，需要新开一个终端窗口才会读到。

另外，团队协作场景下不建议把 Key 写在 shell 配置里到处复制。可以只在一台机器的环境变量中配置，或者用密钥管理工具注入。

步骤 6：项目初始化与权限收口

进入一个项目目录再启动：

```bash

cd ~/projects/my-app

claude

```

进入会话后，第一件事执行：

```

/init

```

它会扫描仓库结构，生成一份 CLAUDE.md，里面记录项目用什么技术栈、怎么跑测试、有哪些约定。这份文件相当于给助手看的「项目说明书」，下次启动会自动读取，回答质量会明显提升。建议把它提交进 git，让全组共享。

接着收口权限。在项目里创建 .claude/settings.json：

```json

{

"permissions": {

"allow": [

"Read",

"Edit",

"Bash(npm run test:*)",

"Bash(git status)",

"Bash(git diff:*)"

],

"deny": [

"Read(./.env)",

"Read(./secrets/**)",

"Bash(rm -rf:*)",

"Bash(curl:*)"

]

}

}

```

含义是：读文件、改文件、跑测试和查看 git 状态不用每次确认；.env 和 secrets 目录禁止读取；删除和外部请求禁止执行。具体规则语法以官方文档为准，不同版本可能有细微差别。

会话里还可以用 /permissions 交互式查看和调整。除非你在一次性的容器或临时目录里，否则不建议使用跳过权限确认的参数，误删文件没有回收站。

验证部署是否成功

按顺序执行三条命令：

```bash

claude --version

claude doctor

claude -p "用一句话概括这个仓库的用途"

```

预期结果：

1. claude --version 输出一个版本号字符串。

2. claude doctor 输出环境自检结果，逐项列出 Node 版本、安装方式、配置路径等。如果有标红项，按提示修复。若你的版本没有这条命令，用 claude --help 查看当前版本支持的命令列表。

3. claude -p "..." 是非交互模式，直接打印回答后退出。能返回一句通顺的中文描述，说明认证、网络、模型调用整条链路都是通的。这一条尤其值得跑，因为它同时验证了 API 连通性，而不仅仅是「命令能执行」。

三条都通过，就可以正常投入使用了。

常见报错与解决

报错 1：npm ERR! code EACCES / permission denied 相关

原因：npm 的全局安装目录属于 root，当前用户没有写权限。这是不用版本管理工具、直接用系统包管理器装 Node 的典型后果。

解决：不要加 sudo，改用 nvm 重装 Node；或者把 npm 全局目录改到用户家目录下：

```bash

npm config set prefix ~/.npm-global

export PATH="$HOME/.npm-global/bin:$PATH"

```

把 export 那行写进 shell 配置文件并 source 一次。

报错 2：claude: command not found

原因：包装上了，但 npm 的全局 bin 目录不在 PATH 里。

解决：先确认目录位置：

```bash

npm config get prefix

```

输出路径后面拼上 /bin（Windows 上是直接拼该路径），把它加入 PATH：

```bash

export PATH="$PATH:$(npm config get prefix)/bin"

```

WSL 里出现这个报错，多半是因为用 Windows 的 Node 装了包、却在 WSL 里执行命令，两边环境不匹配。在 WSL 里重新装一遍即可。

报错 3：Error: Claude Code requires Node.js version ...

原因：Node.js 版本低于要求。

解决：切到当前 LTS 版本。用 nvm 的话：

```bash

nvm install --lts

nvm use --lts

node -v

```

切完重新执行一次全局安装命令，因为换 Node 版本后全局包不会自动迁移。

报错 4：fetch failed / ECONNRESET / ETIMEDOUT

原因：网络无法直连 API 端点，或者在受限网络里没走代理。

解决：确认代理软件在运行，并设置代理变量：

```bash

export HTTPS_PROXY="http://127.0.0.1:7890"

export HTTP_PROXY="http://127.0.0.1:7890"

```

端口按你的代理软件实际监听端口改。设置完用 curl -I https://api.anthropic.com 验证一下能否通到端点。另外注意有些代理工具只代理浏览器流量，需要开启「终端代理」或系统代理模式。

报错 5：Invalid API key · Please run /login

原因：API Key 写错、已失效，或者环境变量里的 Key 和曾经登录的账号冲突。

解决：在会话里重新登录：

```

/login

```

如果是环境变量导致的问题，先清掉再登录：

```bash

unset ANTHROPIC_API_KEY

```

并检查 shell 配置文件里是否残留旧的 ANTHROPIC_API_KEY 定义。用订阅账号时不需要设置这个变量。

报错 6：PowerShell 提示「因为在此系统上禁止运行脚本」

原因：Windows 默认的脚本执行策略限制了 .ps1 文件运行。

解决：把当前用户的策略改成允许本地脚本：

```powershell

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

```

改完关闭并重开 PowerShell。

后续维护

备份。需要备份的东西就三样：用户级配置目录（通常在家目录下的 .claude）、项目里的 CLAUDE.md、项目里的 .claude/ 目录。后两者建议直接提交进 git，随代码一起走。用户级目录里有登录凭据，不要提交到仓库，也不要贴进聊天窗口。换机器时把非敏感部分手工复制过去即可。

升级。两种方式，任选其一：

```bash

claude update

```

或者重新执行一次全局安装命令，npm 会覆盖旧版本。团队场景建议固定一个节奏（比如每月一次）统一升级，避免同事之间行为差异。如果因为某些原因需要暂时关闭自动更新，可以设置 DISABLE_AUTOUPDATER=1，具体变量名以官方文档当前版本为准。

升级后建议重跑一次 claude doctor，确认配置没被新版本改坏。

日志与监控。会话内用 /cost 可以查看当前会话的用量，用来判断是不是某次对话烧得特别快——通常是让它在超大仓库里做全量搜索导致的。用 claude --debug 启动可以看到更详细的请求日志，排查连接问题很有用。

写脚本或接 CI 时，用非交互模式配合结构化输出：

```bash

claude -p "把 src 下所有 TODO 注释汇总成列表" --output-format json

```

这样输出是可解析的 JSON，方便后续用 jq 之类工具处理，也便于记录每次调用的结果。

权限定期复查。权限白名单是随项目演进的，早期为了让流程跑通加的宽松规则，事后容易忘。建议每次迭代结束扫一眼 .claude/settings.json，把不再需要的放行项删掉，尤其是涉及删除、推送、外部请求的规则。这件事花两分钟，能省掉很多后悔。