Claude Code 完整使用指南：从安装到真实项目落地

Claude Code 是目前最强的终端 AI 编程代理。本文覆盖安装、配置、日常使用技巧、高级玩法、性能调优和真实项目案例。国内用户也能直连使用。

什么是 Claude Code

Claude Code 是 Anthropic 推出的命令行 AI 编程代理（agentic coding）。它不是一个聊天机器人，而是一个能自主操作你项目的 AI 同事。

核心能力：

• 理解整个代码库的上下文（最大 200K token）
• 直接读写文件、创建目录
• 执行 shell 命令（构建、测试、部署）
• 管理 Git 工作流（分支、提交、PR）
• 多文件联动重构
• 自动修复测试失败

和其他工具的区别：

Claude Code 的优势在于代码推理能力。SWE-bench Verified 得分 79.6%，意味着它能独立解决接近 80% 的真实 GitHub Issue。

安装

各平台安装命令

# Linux / WSL（官方推荐，自动更新）
curl -fsSL https://claude.ai/install.sh | bash

# macOS (Homebrew)
brew install --cask claude-code

# Windows - PowerShell（原生支持）
irm https://claude.ai/install.ps1 | iex

# Windows - WinGet
winget install Anthropic.ClaudeCode

# npm（跨平台通用，不自动更新）
npm install -g @anthropic-ai/claude-code

验证安装：

claude --version
# 应显示类似 claude-code 2.1.x

配置 API 接入

Claude Code 官方认证需要访问 Anthropic 服务器，国内网络无法直连。解决方案是使用 OpenAI 兼容接口，通过国内可达的 API 端点调用 Claude 模型。

编辑 ~/.claude/settings.json：

{
  "effortLevel": "high",
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-your-api-key",
    "ANTHROPIC_BASE_URL": "https://openai.qiniu.com",
    "ANTHROPIC_MODEL": "claude-4.6-sonnet",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-4.5-haiku",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-4.6-sonnet",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-4.8-opus"
  }
}

API Key 获取：到七牛云（https://s.qiniu.com/2uMRza）注册，进入 AI 推理 API Key 管理页面创建即可。sk- 开头，只显示一次，立刻保存。

具体步骤：

1. 打开 https://s.qiniu.com/2uMRza 注册账号（手机号/邮箱）

2. 完成实名认证

3. 进入 API Key 管理页面：https://portal.qiniu.com/ai-inference/api-key
   

4. 点击「创建」，名称填 “claude-code”
   6. 复制 sk- 开头的 Key，粘贴到上面配置文件的 ANTHROPIC_AUTH_TOKEN

日常使用

交互模式 vs 单次命令

# 交互模式：进入持续对话
cd my-project
claude

# 单次命令：执行完就退出
claude "解释这个项目的架构"
claude "给 src/utils.ts 加一个 debounce 函数"
claude "运行测试并修复失败的用例"

交互模式适合探索性任务（理解代码、讨论方案）。单次命令适合明确的自动化任务。

推理强度控制

Claude Code 支持调整推理深度：

# 高推理（默认，适合复杂任务）
claude --effort high "重构这个模块的错误处理"

# 低推理（快速响应，适合简单问题）
claude --effort low "这个函数的返回类型是什么"

在 settings.json 里也可以全局设置：

{
  "effortLevel": "high"
}

权限控制

Claude Code 可以执行命令和修改文件，安全控制很重要。

全局设置 ~/.claude/settings.json：

{
  "permissions": {
    "allow": ["read", "write", "execute"],
    "deny": ["rm -rf", "sudo", "curl | bash"]
  }
}

项目级设置 项目根目录/.claude/settings.json：

{
  "permissions": {
    "allow": ["read", "write"],
    "deny": ["execute"]
  },
  "context": {
    "include": ["src/**", "tests/**"],
    "exclude": ["node_modules/**", ".env"]
  }
}

项目级配置会覆盖全局配置，可以针对不同项目设置不同的安全策略。

高级玩法

1. 结合 Git 工作流

# 让 Claude 基于 PR 描述自动实现功能
claude "看一下 #42 这个 issue，实现它，写测试，提交到新分支"

# 代码审查
claude "review 最近三个 commit 的改动，关注安全问题"

# 自动生成 commit message
claude "看一下 staged 的改动，写一个规范的 commit message 并提交"

2. 测试驱动开发

# 先写测试再实现
claude "给 UserService.createUser 方法写单元测试，覆盖正常流程和边界情况"
claude "现在实现 createUser 方法，确保所有测试通过"

# 修复失败的测试
claude "npm test 跑了一下有 3 个用例失败，帮我修"

3. 多文件重构

# 模块拆分
claude "把 src/app.ts 拆成 router、middleware、config 三个模块，保持功能不变"

# 技术栈迁移
claude "把这个项目从 Express 迁移到 Fastify，保持 API 接口不变"

# 类型系统升级
claude "给这个 JS 项目加 TypeScript，先从 src/utils 目录开始"

4. CLAUDE.md 项目指令

在项目根目录创建 CLAUDE.md 文件，Claude Code 每次启动都会读取它作为项目上下文：

# 项目说明

这是一个 Next.js 14 + TypeScript 项目。

## 技术栈
- 前端：React 18 + TailwindCSS
- 后端：Next.js API Routes
- 数据库：PostgreSQL + Prisma
- 测试：Vitest + Testing Library

## 代码规范
- 使用函数式组件
- 状态管理用 Zustand
- 错误处理统一用 Result 模式
- 每个新功能必须有对应的测试

## 常用命令
- `pnpm dev` 启动开发服务器
- `pnpm test` 运行测试
- `pnpm lint` 代码检查

有了 CLAUDE.md，Claude Code 每次都能按照项目规范来写代码，不需要反复交代。

5. 配合 tmux 使用

# 开一个 tmux session 专门跑 Claude Code
tmux new -s claude

# 在项目目录启动
cd ~/projects/my-app
claude

# 另一个 pane 里看实时日志
# Ctrl+B % 分割窗口
tail -f logs/dev.log

长时间运行的任务（大型重构、跑测试修 bug 循环），用 tmux 可以后台运行，断开 SSH 也不影响。

模型选择策略

Claude Code 支持多个模型，不同任务用不同模型能省钱又高效：

切换模型：

# 命令行指定
claude --model claude-4.6-opus "重构整个认证模块"

# 或修改 settings.json 的 ANTHROPIC_MODEL

我的策略： 默认用 Sonnet 4.6，遇到它搞不定的复杂任务再切 Opus。Haiku 留给"帮我看看这个变量名叫什么好"这类轻量问题。

性能调优

减少 token 消耗

// .claude/settings.json（项目级）
{
  "context": {
    "include": ["src/**", "tests/**", "package.json"],
    "exclude": ["node_modules/**", "dist/**", "*.lock", "coverage/**"]
  }
}

排除无关文件可以大幅减少上下文消耗，省钱且响应更快。

利用 Prompt Cache

Claude 模型支持 prompt cache。反复发相同的系统提示和项目上下文时，缓存后输入价格降到 $0.30/M（原价 $3/M，打一折）。

实际表现：日常编码中约 40-60% 的输入会命中缓存。

批量任务优化

# 不好：每个文件单独一次请求
for f in src/*.ts; do claude "给 $f 加类型注解"; done

# 好：一次请求处理多个文件
claude "给 src/ 目录下所有 .ts 文件加上严格的类型注解"

一次请求让 Claude Code 自主遍历文件，比多次请求效率高且便宜。

真实项目案例

案例 1：给遗留项目加测试

cd legacy-express-app
claude "分析项目结构，找出核心业务逻辑模块，按优先级给前 5 个最重要的函数写单元测试"

Claude Code 会：

1. 扫描项目结构
2. 识别核心模块（通常是被引用最多的）
3. 分析函数签名和业务逻辑
4. 生成测试文件，覆盖正常流程和边界情况
5. 运行测试验证通过

案例 2：API 接口重构

claude "把 routes/user.js 从 callback 风格改成 async/await，加上统一的错误处理中间件，保持所有现有 API 测试通过"

案例 3：Debug 生产问题

claude "用户反馈登录偶尔返回 500。看一下 src/auth/ 目录的代码，分析可能的竞态条件或未处理的异常，给出修复方案并实现"

常见问题

Claude Code 免费吗？

不免费。国内用户通过 API 按量付费，充 100 元即可开始用。日常编码用 Sonnet 每天约 ¥10-30。

Windows 能用吗？

原生支持。PowerShell 一行命令：irm https://claude.ai/install.ps1 | iex，或用 WinGet：winget install Anthropic.ClaudeCode。也支持 WSL。

和 Cursor 选哪个？

不冲突，互补的。Claude Code 适合明确的自动化任务（“重构这个模块”、“修复所有测试”）。Cursor 适合需要 GUI 的探索式编辑。我是 Claude Code 做重活，Cursor/Zed 做轻活。

上下文窗口不够大怎么办？

Claude Code 最大支持 200K token 上下文。对于超大项目：

• 用 .claude/settings.json 的 context.exclude 排除无关目录
• 用 CLAUDE.md 写清楚项目结构，让 Claude 按需读取文件
• 分模块操作，每次只聚焦一个子系统

小贴士

• CLAUDE.md 是最重要的配置，花 10 分钟写好能省几小时的沟通
• 在项目根目录启动，Claude 会自动读取 package.json、tsconfig.json 等配置
• 用 --model 按任务切换模型，别什么都用 Opus
• 长任务用 tmux 跑，断网也不怕
• 定期更新 Claude Code（原生安装会自动更新）
• 敏感项目务必配好权限控制的 deny 列表

延伸阅读

1. Claude Code 官方文档：https://docs.anthropic.com/claude-code
2. CLAUDE.md 最佳实践：https://docs.anthropic.com/claude-code/claude-md
3. Anthropic 模型卡：https://docs.anthropic.com/models
4. 国内 API 服务（七牛云）：https://s.qiniu.com/2uMRza
5. 模型价格对比：https://modelink.ai/en-US/models