前言

Claude Code 能力很强，但新手上手时容易在环境配置、提示词写法、费用控制等方面踩坑。本文整理 10 个高频问题及对应解法，帮你少走弯路。

错误 1：连接超时，请求发不出去

现象：安装完运行命令提示 connect ETIMEDOUT，或长时间无响应。

原因：Claude Code 默认请求 Anthropic 官方 API（api.anthropic.com），部分网络环境无法直连。

解决：根据你的接入方式处理——

• 用官方 API 且网络可直连：确认代理/网络正常即可，无需改 Base URL。
• 走第三方中转：配置 ANTHROPIC_BASE_URL 指向服务商提供的地址。

export ANTHROPIC_BASE_URL="https://api.highwayapi.ai/openai"

写入 ~/.zshrc 或 ~/.bashrc 持久化保存。

错误 2：API Key 泄露到 Git 仓库

现象：不小心把 Key 写进代码或配置文件，提交到了远程仓库。

后果：Key 可能被盗用，产生意外费用。

解决：

1. 立即撤销泄露的 Key，到对应平台控制台删除旧 Key、生成新 Key。
2. 用环境变量，不要把 Key 硬编码进代码，统一用 ANTHROPIC_API_KEY。
3. 配好 .gitignore，确保 .env 不被提交：

# .gitignore

.env

.env.local

提醒：即使事后删除了提交，Key 仍可能留在 Git 历史里，所以"撤销旧 Key"这一步不能省。

错误 3：提示词太模糊

现象：让它"优化一下代码"，结果改了一堆不相关的地方。

原因：模糊需求会导致不可控的输出。

解决：写清楚改哪个文件、实现什么、有什么约束。

不好的提示词：

优化一下代码

好的提示词：

重构 src/utils/parser.js 中的 parseJSON 函数，要求：

1. 增加错误处理，捕获 JSON.parse 异常

2. 返回值改为 { success: boolean, data: any, error?: string }

3. 保持向后兼容，不改变函数签名

错误 4：没有创建 CLAUDE.md 项目上下文

现象：对项目理解不准，生成的代码风格不统一。

解决：在项目根目录创建 CLAUDE.md，写入项目背景、技术栈、规范：

# 项目说明

基于 Express + TypeScript 的后端 API 项目。

## 技术栈

- Node.js 20 / Express 4.x / TypeScript 5.x

- PostgreSQL + Prisma ORM

## 编码规范

- ESLint + Prettier

- 函数命名 camelCase

- 接口返回统一格式：{ code, message, data }

## 目录结构

- src/routes: 路由

- src/controllers: 业务逻辑

- src/models: 数据模型

错误 5：一次让 AI 做太多事

现象：让它"重构整个项目"，结果改到一半卡住或改乱了。

原因：上下文窗口虽大，但一次处理太多文件容易出错、也难 review。

解决：拆分任务，小步推进。

# 1. 先重构单个模块

claude "重构 src/auth 模块，提取公共逻辑到 utils"

# 2. 跑测试确认没破坏功能

claude "运行测试，确保重构没有破坏现有功能"

# 3. 再处理下一个模块

claude "重构 src/user 模块，应用相同的模式"

错误 6：忽略 Token 消耗，费用失控

现象：一个月下来费用超出预期。

原因：频繁传入大量代码、没选对模型、上下文没精简。

解决：

1. 按难度选模型：简单任务用更轻量的 Haiku 系列，复杂任务用 Sonnet 或 Opus 系列，没必要一律用最贵的。
2. 精简上下文：只传相关文件，不要每次都把整个代码库丢进去；用 /compact 压缩历史。
3. 利用 Prompt Caching：重复的系统提示和长上下文前缀会被缓存，能显著降低重复请求的费用。
4. 设置预算告警：在你使用的 API 平台上配置用量上限或提醒，避免无感超支。

错误 7：不 Review AI 生成的代码

现象：直接运行生成的代码，结果出 bug 或藏着安全隐患。

解决：

1. 逐行读懂生成的代码。
2. 跑测试确认功能正确。
3. 按项目规范做 Code Review。
4. 重点审查涉及用户输入、数据库查询的部分（注入、越权等）。

错误 8：把 AI 生成的配置直接用到生产

现象：让它生成 Nginx 配置或数据库迁移脚本，直接上生产，结果服务挂了。

原因：生成的配置未必匹配你的真实环境。

解决：

1. 先在测试环境验证。
2. 改动前备份原配置。
3. 灰度发布，别一次性全量上线。

错误 9：中转/接入配置的细节坑

现象：Key 和地址都填了，还是连不上。

常见原因：

• ANTHROPIC_BASE_URL 末尾多了 /，或路径写错（以服务商文档为准）。
• Key 复制时混进了空格或换行符。
• 改完没 source，环境变量没生效。

排查：

# 看变量是否正确

echo $ANTHROPIC_API_KEY

echo $ANTHROPIC_BASE_URL

# 测连通性（model 换成你实际可用的，地址换成你的）

curl -H "x-api-key: $ANTHROPIC_API_KEY" \

-H "anthropic-version: 2023-06-01" \

-H "content-type: application/json" \

-d '{"model":"claude-sonnet-4-6","max_tokens":100,"messages":[{"role":"user","content":"hi"}]}' \

"$ANTHROPIC_BASE_URL/messages"

错误 10：没用 Git 版本控制兜底

现象：改完发现改坏了，却不知道动了哪些地方，无法回滚。

解决：养成"改前先提交"的习惯。

# 改动前先存档

git add .

git commit -m "chore: snapshot before AI refactor"

# 让 Claude Code 改代码

claude "重构 xxx"

# 看改了什么

git diff

# 不满意就回滚（注意 reset --hard 会丢弃工作区改动，确认后再执行）

git reset --hard HEAD

总结

Claude Code 很强，但用好它靠的是习惯：提示词写具体、任务拆小步、改动前留 Git 存档、生成的代码必 review、上生产前先在测试环境验证。把这 10 个坑避开，就能明显减少返工。API 接入方式按自己的网络和计费情况选择即可，官方直连和第三方中转各有适用场景。