Claude Code 怎么配置和使用？从安装到实战踩坑全记录（2026）

Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手，可以直接在终端里用自然语言操作你的代码仓库------读文件、改代码、跑测试、提交 Git，一条命令搞定。这篇文章从安装到配置到实际项目里怎么用，把我折腾了两天的经验全写出来，包括那些官方文档没提的坑。

上个月我把一个 Node.js 老项目的重构任务交给 Claude Code 试了试。说实话一开始我是拒绝的------终端里写代码？听着就不靠谱。结果跑了两天之后真香了，重构 14 个文件，测试全过，比我自己手撸快了大概 3 倍。但中间踩的坑也不少，尤其是配置环节。

先说结论

维度	结论
安装耗时	顺利的话 5 分钟，踩坑可能 2 小时
适合场景	重构、写测试、批量改文件、代码
不适合场景	需要频繁看 UI 效果的前端样式调整
模型	默认 Claude Sonnet 4.6，可切 Opus 4.7
月费	官方 Max 套餐 $100/月起，也可以走 API 按量付

环境准备

你需要：

Node.js 18+（我用的 20.12.2，低版本会报奇怪的错）
npm 或 yarn
一个终端，macOS/Linux 原生终端都行，Windows 建议 WSL2

先确认 Node 版本没问题：

bash 复制代码

node -v
# v20.12.2

如果你还在用 Node 16，升一下吧，不然后面安装会报 engine "node" is incompatible 然后卡住。

方案一：官方直连安装 + API Key

最标准的路子。

bash 复制代码

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

装完之后终端输入 claude 就能启动。第一次启动会让你登录 Anthropic 账号或者填 API Key。

这里有个坑------如果你网络环境不太行，npm install 这步可能卡在下载二进制包上，等半天然后超时：

bash 复制代码

npm ERR! network timeout at: https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-1.0.12.tgz

解决办法是换 npm 镜像源，或者直接开代理。我当时折腾了 40 分钟才搞定这一步。

装好之后，配置 API Key：

bash 复制代码

export ANTHROPIC_API_KEY="sk-ant-xxxxx"

写到 .bashrc 或 .zshrc 里持久化。然后进到你的项目目录：

bash 复制代码

cd ~/projects/my-app
claude

启动后它会自动扫描项目结构，然后你就可以用自然语言跟它对话了。

方案二：用 API 聚合平台的 Endpoint

这是我目前在用的方案。原因很简单------Anthropic 官方 API 的账单只能绑国际信用卡，而且如果团队多人用，每个人都得有自己的 Key，月底对账很麻烦。

Claude Code 支持自定义 API 端点。核心就是设两个环境变量：

bash 复制代码

export ANTHROPIC_BASE_URL="https://api.ofox.ai/anthropic"
export ANTHROPIC_API_KEY="your-ofox-key"

graph LR A[终端: claude 命令] --> B[Claude Code CLI] B --> C{ANTHROPIC_BASE_URL} C -->|官方| D[api.anthropic.com] C -->|聚合平台| E[api.ofox.ai/anthropic] E --> F[Anthropic 官方通道]

设好之后正常启动 claude 就行，用起来和直连没区别。我测了一下延迟，P95 大概在 280ms 左右，体感上打字流式输出很顺畅，没有明显卡顿。

如果你想在项目级别配置（不影响全局），可以在项目根目录建 .claude/settings.json：

json 复制代码

{
 "env": {
 "ANTHROPIC_BASE_URL": "https://api.ofox.ai/anthropic",
 "ANTHROPIC_API_KEY": "your-key"
 },
 "model": "claude-sonnet-4-6-20260401",
 "permissions": {
 "allow_file_write": true,
 "allow_shell": false
 }
}

allow_shell 我设成 false 了。这个选项控制 Claude Code 能不能直接执行 shell 命令。官方说有沙箱，但我还是保守点，需要跑命令的时候让它告诉我，我自己复制粘贴执行。

实战：用 Claude Code 重构一个 Express 项目

光说配置没意思，来个真实案例。

我有个两年前写的 Express 项目，路由全堆在 app.js 里，500 多行，没有类型检查，错误处理基本靠 try-catch 裸写。

进入项目目录启动 Claude Code 之后，我先让它了解项目：

markdown 复制代码

> 读一下整个项目结构，告诉我代码质量有什么问题

它花了大概 15 秒扫完所有文件，给了一份还挺靠谱的分析------指出了路由没拆分、缺少统一错误处理中间件、数据库连接没做连接池、环境变量硬编码这几个问题。

然后我一个一个让它改：

markdown 复制代码

> 把 app.js 里的路由按资源拆分到 routes/ 目录下，保持现有 API 路径不变

它先创建了 routes/users.js、routes/orders.js、routes/products.js，把对应的路由代码搬过去，然后改 app.js 的 import。整个过程大概 30 秒，改了 6 个文件。

但这里出了个问题。它把一个中间件函数 authMiddleware 从 app.js 搬到 routes/users.js 里了，但 routes/orders.js 也用到了这个中间件。跑起来直接报错：

vbnet 复制代码

ReferenceError: authMiddleware is not defined
 at /routes/orders.js:12:23

我跟它说了这个报错，它立刻意识到问题，把 authMiddleware 提取到 middleware/auth.js，然后两个路由文件都 import 这个公共模块。修复后测试全过。

这种"改出 bug → 贴报错 → 它修复"的循环挺高效的，比自己 debug 快。但你得盯着，不能完全放手。

几个实用技巧

切换模型。默认是 Sonnet 4.6，如果遇到复杂的架构决策，可以临时切到 Opus 4.7：

shell 复制代码

> /model claude-opus-4-7-20260415

Opus 贵不少，但理解复杂代码库的能力确实强一档。我一般只在需要大范围重构或者写复杂算法的时候切过去，日常用 Sonnet 够了。

用 /compact 压缩上下文 。聊久了上下文会爆，Claude Code 会提示 token 快满了。这时候输入 /compact，它会把之前的对话压缩成摘要，释放上下文空间。

善用 .claudeignore 。跟 .gitignore 语法一样，把 node_modules、dist、.env 这些排除掉，不然它扫描项目的时候会很慢：

bash 复制代码

# .claudeignore
node_modules/
dist/
.env
*.log
coverage/

踩坑记录

坑 1：权限问题

macOS 上全局安装后，第一次运行报了个权限错误：

arduino 复制代码

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@anthropic-ai'

老问题了，sudo npm install -g 或者用 nvm 管理 Node 版本就行。我用 nvm，所以没这个问题，但同事踩了。

坑 2：大文件卡死

让它读一个 8000 行的 SQL migration 文件，直接卡住了，等了两分钟没响应。后来我把文件拆成几段喂给它才行。目前没找到比手动拆分更好的办法。

坑 3：Git 操作要小心

Claude Code 可以直接帮你 git commit，但有一次它把我还没改完的文件也一起提交了。现在我都会在 settings 里把 Git 写操作关掉，让它只读 Git 状态：

json 复制代码

{
 "permissions": {
 "allow_git_write": false
 }
}

坑 4：API 429 限流

用 Anthropic 官方 API 的时候，连续高频对话偶尔会触发限流：

erlang 复制代码

Error: 429 Too Many Requests - Rate limit exceeded. Please retry after 32 seconds.

没什么好办法，要么等，要么升套餐。走聚合平台的话限流策略不太一样，OpenRouter 和 ofox.ai 这类服务商一般有多通道负载均衡，被限流的概率低一些，但也不是完全没有。

小结

Claude Code 目前是我用过的终端 AI 编程工具里完成度最高的。适合后端重构、批量改文件、写单元测试这些场景。配置上主要就是 Node 版本别太低、API Key 设对、权限控制别全开。

日常开发我现在基本是 Cursor 写新功能 + Claude Code 做重构和代码，两个搭配着用。如果你的项目以后端为主，值得花半小时配一下试试。