Claude Code 国内完整上手指南：从 10 分钟配置到让它帮你提第一个 PR

Claude Code 国内完整上手指南：从 10 分钟配置到让它帮你提第一个 PR

Claude Code 从去年底火到现在，身边朋友一半都在用，我上周末终于把它跑通了。官方文档默认海外环境、网上零散教程大多过时，国内开发者配置起来比想象中绕。踩完坑后整理出这份完整版：从环境装好、API 配置、第一次交互，到 CLAUDE.md 和 slash command 的正确用法。读完你能在 10 分钟内跑起来、半小时内让它帮你完成一个真实小任务。

---

一、先讲清楚：Claude Code 到底是个啥

很多朋友问我"它不就是个 Copilot 吗"——真不是。简单对比一下：

工具	形态	能做什么
Copilot	IDE 插件，输入时补全	写到一半帮你接下一行
Cursor	改过的 VSCode + AI Composer	对话式改一两个文件
Claude Code	终端里跑的 Agent CLI	读整个仓库、自己跑 bash、改多个文件、跑测试、提 commit

最直观的差别：你告诉 Claude Code "帮我给这个 Flask 项目加一个登录模块，改完跑测试，跑过再提交"，它真的会按顺序做完所有事——读代码、改文件、执行 pytest、看结果、必要时修 bug，最后 git commit。

这种"一句话派个活"的感觉，是传统补全工具没法给的。

---

二、环境准备（2 分钟）

Claude Code 本体是一个 npm 包，对环境的要求很简单：

# 1. Node.js 版本 ≥ 18（建议 20 LTS）
node --version
# 如果没装或版本太低，用 nvm 装一个
# curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# nvm install 20

# 2. 全局安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 3. 验证安装
claude --version
# 预期输出类似：claude-code 0.x.x

Windows 用户推荐用 WSL2 + Ubuntu 跑，原生 PowerShell 也能跑但偶尔有路径解析问题，WSL 更稳。

---

三、核心一步：配置 API Key（国内开发者必看）

这一步是 90% 国内用户卡死的地方。Claude Code 默认访问 api.anthropic.com，国内网络大概率连不通，要么超时要么直接 ECONNRESET。

正确姿势：用环境变量把 Claude Code 的请求指到国内可达的 API 端点。

# 国内开发者第一步（所有 Claude Code 教程通用起点）
export ANTHROPIC_BASE_URL=https://api.yutaikeji.cn
export ANTHROPIC_API_KEY=yt-xxxxxxxx   # 玉兔AI 控制台注册即得

# 写入 shell 配置让它永久生效
# zsh 用户
echo 'export ANTHROPIC_BASE_URL=https://api.yutaikeji.cn' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY=yt-xxxxxxxx' >> ~/.zshrc
source ~/.zshrc

# bash 用户把 ~/.zshrc 换成 ~/.bashrc 即可

💡 国内开发者要让 Claude Code 跑起来，API Key 和 base_url 是必需配置。我这里用的是 玉兔AI——注册即送额度，够把本文操作完整跑一遍；接口 100% 兼容 Anthropic 原生协议，Claude Code 不需要任何改造。

⚠️ 踩坑提示： 如果你同时装了 Claude Desktop 的 subscription 账号（Pro/Max），启动 claude 时它会优先尝试 OAuth 登录而不是读环境变量。解决办法：启动前先 claude logout 清掉 session，再 claude 就会老老实实用 API Key 模式。

---

四、第一次启动：让它给你看代码

进入任意一个你熟悉的项目目录，启动：

cd ~/code/my-fastapi-project
claude

第一次进入会问你两个东西：权限模式 和 模型选择。

• 权限模式：我推荐先选 default（每次动手前会确认）。熟悉后再切 acceptEdits 或 bypassPermissions。
• 模型：默认 claude-sonnet-4-6 是最平衡的选择。如果你要处理超复杂问题可切 claude-opus-4-7。

进入交互界面后，试试这句：

> 看一下当前项目的结构，告诉我这是什么技术栈、主要入口文件在哪，
  然后列出 3 个你觉得代码质量有问题、但改起来风险不大的地方。

如果一切正常，你会看到它用 ls、read_file 一通扫，几秒钟后给你一份简短总结 + 改造建议列表。这是最好的 smoke test——说明 API、模型、权限、工具调用全链路打通。

---

五、Claude Code 三板斧：CLAUDE.md / slash commands / hooks

会启动只是入门。Claude Code 真正强的是下面这三样定制能力，学会就能让它变成你个人的 pair programmer。

板斧一：CLAUDE.md —— 给这个仓库留的"说明书"

在项目根目录放一个 CLAUDE.md，Claude Code 每次启动会自动读。它记住的是 这个项目的约定——比如用什么 lint 工具、commit 格式、哪些文件不该动。

示例：

# 本项目约定

## 技术栈
- 后端：FastAPI + SQLAlchemy 2.0 + PostgreSQL
- 测试：pytest，覆盖率底线 80%
- Lint：ruff + mypy --strict

## 代码规范
- 所有 API 必须写 OpenAPI schema
- 数据库迁移用 alembic，不要手写 SQL
- 环境变量通过 pydantic Settings 管理，禁止 os.environ.get 散落

## 禁区
- /alembic/versions/ 下的历史迁移文件不要改
- .env 文件不要读、不要写
- 生产环境配置只读（/config/prod.yaml）

## 常用命令
- 跑测试：uv run pytest
- 跑 lint：uv run ruff check . && uv run mypy src/
- 启动开发：uv run uvicorn src.main:app --reload

这份文件一写，后面你让它"加一个接口"它会自动遵守 ruff + mypy + 测试覆盖率的要求。一次性投入，长期收益。

板斧二：slash commands —— 自定义命令

在项目里新建 .claude/commands/review.md：

你是这个项目的 code reviewer。请完成以下事情：

1. 跑 `git diff main...HEAD` 拿到本分支改动
2. 逐文件 review，重点关注：
   - 是否有潜在 bug 或边界条件没处理
   - 命名是否清晰
   - 是否缺测试覆盖
3. 给出一个 markdown 格式的 review report，每条问题标注文件:行号

$ARGUMENTS

启动 Claude Code 后输入 /review，它就会执行这套流程。把你每天重复做的事写成 command，之后一行唤起。

板斧三：hooks —— 自动化触发器

Hooks 能力很大，这里只给一个最小示例：每次 Claude Code 写完文件自动跑 ruff format。

在 ~/.claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "ruff format ${CLAUDE_TOOL_INPUT_file_path} 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

从此它每次改 Python 文件都会自动格式化，你根本不用管。

---

六、常见问题 FAQ

Q1: 启动报 401 Unauthorized 怎么办？

九成是 ANTHROPIC_API_KEY 没生效。验证方法：

echo $ANTHROPIC_API_KEY
# 应该输出你的 key；如果空，说明 shell 没加载环境变量

没生效就 source ~/.zshrc 或者重开终端。

Q2: 启动报 Connection error 或一直 timeout？

先确认 ANTHROPIC_BASE_URL 是否配上了：

echo $ANTHROPIC_BASE_URL
curl -I $ANTHROPIC_BASE_URL/v1/messages
# 应该返回 401 或 405，说明网络通但需要鉴权

如果返回连接错误，说明 base_url 本身网络不通——检查公司网络是否限制了出站，或者换个端点。

Q3: 怎么限制它别乱跑命令？

三道防线：

1. 启动时选 default 权限模式——每次动手都会确认
2. 在 .claude/settings.local.json 里配 permissions.deny 列表，禁掉危险命令：

{
  "permissions": {
    "deny": ["Bash(rm -rf *)", "Bash(git push --force *)", "Write(/etc/**)"]
  }
}

3. 敏感仓库直接在 CLAUDE.md 里写清楚禁区

Q4: 一次对话 context 爆了怎么办？

用 /compact 命令手动压缩，或者让它 /clear 开新会话。长任务建议拆成多个短会话，每次用 CLAUDE.md + 明确任务描述起步。

Q5: 费用怎么控制？

用 /cost 命令随时看本次会话累计用量。另外强烈建议把简单任务（批量重命名、格式化之类）用 --model claude-haiku-4-5 启动，账单能降一个量级。

---

七、今天你拿到了什么

✅ 学完本文，你应该能做到：

• 10 分钟内装好 Claude Code 并完成国内网络环境下的 API 配置
• 启动后让它读整个项目结构，跑通第一个真实任务
• 写一份 CLAUDE.md 把项目约定注入 AI，让它遵守团队规范
• 用 slash command 把重复操作一键化
• 用 hooks 让它每次改代码后自动格式化
• 处理 5 个最常见的启动/运行报错

用 Claude Code 之前 vs 之后：

	之前（纯 IDE + Copilot）	之后（Claude Code）
新接需求耗时	看代码 30min + 写 60min	一句话派活，15min review
测试覆盖	经常忘写	Hooks 强制触发，必写
Code review	自己 review 自己，漏看	本机 /review 先过一遍
学新代码库	翻文档 1 小时起步	Claude 读一遍给总结，5 分钟

---

🔗 开始使用 Claude Code

本文所有操作都在 玉兔AI 上跑通，国内开发者可以直接复用：

优势	说明
🇨🇳 国内直连	Claude Code 开箱即用，无需网络改造
💰 按量付费	用多少花多少，比官方 Pro 订阅灵活
🎁 新用户福利	注册即送体验额度，跑完本文全流程绰绰有余
⚡ 稳定可靠	P99 延迟 < 1s，Claude Code 长任务不掉线

---

参考资料

• Claude Code 官方文档
• Anthropic Messages API
• Claude Code Hooks 文档
• Claude Code Settings 参考