基础篇：Claude Code 快速上手指南

本篇学习路径

第一章. 认识 Claude Code - 重新定义编程范式

2024 年底，当我第一次看到 Claude Code 的演示视频时，我的第一反应是：“这不就是个终端版的 ChatGPT 吗？” 但当我真正用它写完第一个项目后，我意识到自己错了，Claude Code 是在国内第一批火的 Coding CIL，以轻量，强大而闻名

1.1. 什么是 Claude Code？

Claude Code 是 Anthropic 推出的一款 终端原生的 Agentic 编程助手。注意这三个关键词：

终端原生：它不是 IDE 插件，不是网页应用，而是直接运行在你的命令行里。这意味着它能无缝使用你的 Git、npm、Python 环境，甚至你自定义的 Shell 别名。

Agentic：这是核心。它不是被动地等你提问，而是能 主动规划、自主执行、持续反思。你给它一个目标，它会自己拆解成多个步骤，执行每一步，检查结果，发现问题就自己修正。

编程助手：它的定位不是 “代码生成器”，而是你的 编程伙伴。它理解你的项目结构、业务逻辑、技术栈，能跨文件修改代码、运行测试、操作数据库。

让我用一个类比来解释这三者的区别：

1.2. Agentic 助手 vs 传统 Copilot

很多人会问：“我已经在用 GitHub Copilot 了，为什么还需要 Claude Code？”

答案是：它们解决的是不同层次的问题。

举个具体例子。假设你要 “为用户模块添加邮箱验证功能”：

使用 Copilot 的流程：

1. 你打开 user.service.js，开始写 validateEmail 函数
2. Copilot 补全函数体
3. 你手动去 user.controller.js 调用这个函数
4. 你手动去 user.test.js 写测试
5. 你手动运行 npm test
6. 测试失败，你回去改代码
7. 重复 5-6 直到通过

使用 Claude Code 的流程：

1. 你在终端输入：为用户模块添加邮箱验证功能，需要修改 service、controller 和测试文件
2. Claude 分析项目结构，提出修改方案
3. 你批准后，它自动修改三个文件
4. 它自动运行 npm test
5. 测试失败，它看到错误信息，自动修复代码
6. 它再次运行测试，通过后告诉你 “完成”

看出区别了吗？Copilot 是 “辅助你写代码”，Claude Code 是 “替你完成任务”。

1.3. 适用场景与局限性

Claude Code 不是银弹。在决定是否使用它之前，你需要清楚它的边界。

最适合的 5 种场景

不适合的 3 种场景

1.4. 一人公司为什么需要它

如果你是一个人在做产品，你会面临一个残酷的现实：时间是你唯一的资源，也是最稀缺的资源。

传统开发模式下，一个全栈功能的开发流程是这样的：

总计：23 小时，接近 3 个工作日。

使用 Claude Code 后：

总计：4 小时，效率提升 5.75 倍。

更重要的是，这 4 小时里，你的大部分时间是在 思考和决策，而不是在敲键盘。你的精力被解放出来，可以去做更有价值的事情：

• 思考产品方向
• 优化用户体验
• 规划下一个功能
• 甚至去喝杯咖啡

这就是为什么一人公司需要 Claude Code——它让你从 “全栈工程师” 变成 “全栈指挥官”。

第二章. 环境准备与成本优化配置

在开始之前，我必须先和你聊聊钱的问题。

很多教程会跳过这一步，直接让你 “注册官方 API，开始使用”。但对于一人公司来说，成本控制是生死线。如果你不了解各种方案的成本差异，很可能在不知不觉中烧掉几百美元。

本章我会详细讲解三种 API 接入方案，确保你在享受 AI 编程便利的同时，不会因为费用失控而焦虑。

2.1. 系统要求检查

在安装 Claude Code 之前，请确认你的系统满足以下要求：

操作系统

• macOS 10.15+
• Linux（Ubuntu 20.04+ 或其他现代发行版）
• Windows 10/11（已在最新版本中适配）

软件依赖

• Node.js：v18.0 或更高版本，详细见：NVM 版本管理：Node.js 保姆级图文下载教程 | Prorise - 博客小栈
• Git：强烈建议安装，以便 Claude Code 能够执行版本控制操作，详细见：第一章. 小白也会：Windows Git 环境搭建全流程（含 P4Merge） | Prorise - 博客小栈

网络

• 稳定的互联网连接（用于与 API 通信）
• 如果在国内，需要配置代理（稍后详细讲解）

2.2. 安装 Claude Code

确认系统要求后，我们开始安装 Claude Code。

使用 NPM 全局安装（推荐）

1

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

安装过程可能需要 1-2 分钟，取决于你的网络速度。

验证安装

安装完成后，运行以下命令验证：

1

claude --version

如果输出类似 2.0.76 (Claude Code)，说明安装成功。

方案三：低成本中转站（闲鱼 / Linux.do）

适用场景：你想用 Claude 官方模型，但预算极其有限。

什么是中转站？

中转站是一些个人或小团队搭建的 API 代理服务。他们批量购买官方 API 额度，然后以更低的价格转售。

常见的中转站来源

配置步骤

假设你从闲鱼购买了一个中转 API Key（格式类似 sk-xxx）和中转地址（如 https://api.example.com）。

创建配置文件 ~/.claude/config.json：

1
2
3
4

{
  "apiKey": "sk-xxx",
  "baseURL": "https://api.example.com/v1"
}

1. 数据泄露：你的代码会经过中转服务器，可能被记录
2. 服务中断：卖家可能随时跑路，导致服务不可用
3. 账号封禁：如果中转站滥用官方 API，可能导致你的请求被封

建议：仅在个人学习项目中使用，商业项目请使用官方或国产模型。

第三章. 你的第一个 Claude Code 会话

环境配置完成，现在是最激动人心的时刻——启动 Claude Code，完成你的第一次对话。

但在此之前，我要先教你一个最重要的技能：如何 “后悔”。

3.1. 启动与交互界面

进入项目目录

Claude Code 需要在项目根目录下运行，这样它才能理解你的项目结构。

启动 Claude Code

1

claude

启动后，你会看到一个交互式提示符：

这个 › 就是你的输入提示符，类似于 Shell 的 $ 或 >。

3.2. 第一个任务：让 Claude 理解你的项目

在让 Claude 写代码之前，最好先让它 “读一遍” 你的项目，建立上下文。

输入你的第一个指令

1

/init

Claude 会开始扫描你的项目文件，分析 package.json、README.md、目录结构等，然后给出一个摘要，摘要通常来说叫做“Claude.md”

3.3. 第一次代码修改

现在让我们给 Claude 一个具体的编码任务。

下达指令

1

› 创建一个简单的 Express 服务器，监听 3000 端口，有一个 GET /hello 接口返回 "Hello, Claude!"

Claude 的响应流程

Claude 会经历以下几个步骤：

步骤 1：规划

1
2
3
4
5
6
7

我将执行以下操作：
1. 安装 express 依赖
2. 创建 server.js 文件
3. 编写服务器代码
4. 创建启动脚本

是否继续？[y/n]

步骤 2：等待你的批准

这是 Claude Code 的核心安全机制——任何会修改文件或执行命令的操作，都需要你明确批准。

输入 y 并回车。

步骤 3：执行操作

1
2
3
4
5

✓ 执行命令：npm install express
✓ 创建文件：server.js
✓ 修改文件：package.json（添加 start 脚本）

所有操作已完成。你可以运行 npm start 启动服务器。

步骤 4：验证结果

按照 Claude 的提示，运行服务器：

1

npm start

打开浏览器访问 http://localhost:3000/hello，你应该能看到 Hello, Claude!。

生成的代码

让我们看看 Claude 生成的 server.js：

代码简洁、清晰，符合 Express 的最佳实践。

3.4. 第一次 “后悔”：Checkpoints 与 Rewind

现在是最重要的部分——学会如何 “后悔”。

假设你刚才让 Claude 修改了代码，但运行后发现不符合预期，或者你只是想尝试另一种实现方式。传统方式下，你需要手动 git reset 或者 Ctrl+Z 撤销。

但 Claude Code 提供了更强大的机制：Checkpoints（检查点）。

3.4.1. 为什么需要 “后悔药”

在 AI 编程中，你会经常遇到这些情况：

• Claude 理解错了你的需求，生成的代码完全不对
• 你想尝试两种不同的实现方案，看哪个更好
• Claude 在重构过程中不小心删除了重要代码
• 你批准了一个操作后，突然意识到不应该这样做

如果没有 “后悔药”，你只能：

1. 手动恢复文件（如果你记得改了什么）
2. 从 Git 历史中恢复（如果你提交过）
3. 重新开始整个会话

这些方法都很低效，而且容易出错。

3.4.2. 创建检查点

什么是 Checkpoint？

Checkpoint 是 Claude Code 的 “存档点”。它会保存：

• 当前所有文件的状态
• 当前的对话历史
• 当前的上下文信息

你可以随时回到任何一个 Checkpoint，就像游戏中的 “读档”。

创建你的第一个 Checkpoint

在刚才创建完 Express 服务器后，我们创建一个检查点：

1

› /checkpoint create "初始 Express 服务器"

Claude 会回复：

1
2
3
4

✓ 检查点已创建：checkpoint_001
  名称：初始 Express 服务器
  时间：2026-01-15 10:30:00
  文件数：2（server.js, package.json）

3.4.3. 回滚操作：Rewind

现在让我们故意 “搞砸” 一些东西，然后用 Rewind 恢复。

故意破坏代码

1

把 server.js 里的所有代码都删除，只保留一行注释 "// TODO"

现在 server.js 变成了：

1

// TODO

服务器当然无法运行了。

使用 Rewind 恢复

1

› /rewind

Claude 会显示可用的检查点：

1
2
3
4

可用的检查点：
1. checkpoint_001 - 初始 Express 服务器 (2026-01-15 10:30:00)

请选择要恢复的检查点编号，或输入 'cancel' 取消：

输入 1 并回车。

1
2
3
4
5
6

✓ 正在恢复到检查点：checkpoint_001
✓ 文件已恢复：server.js
✓ 文件已恢复：package.json
✓ 对话历史已恢复

恢复完成。你现在回到了"初始 Express 服务器"的状态。

打开 server.js，你会发现代码完好无损，就像刚才的破坏从未发生过。

3.4.4. Checkpoint 的高级用法

列出所有检查点

1

› /checkpoint list

删除检查点

1

› /checkpoint delete checkpoint_001

自动检查点

你可以配置 Claude Code 在每次执行重要操作前自动创建检查点。编辑 ~/.claude/settings.json：

1
2
3
4
5
6
7

{
  "autoCheckpoint": {
    "enabled": true,
    "triggers": ["edit", "bash"],
    "maxCheckpoints": 10
  }
}

这样，每次 Claude 修改文件或执行命令前，都会自动创建检查点，最多保留 10 个。

Checkpoint vs Git

3.4.5. 实战：撤销一次错误的重构

让我们通过一个真实场景，体会 Checkpoint 的价值。

场景：你想重构 server.js，将路由逻辑提取到单独的文件中。

步骤 1：创建检查点

1

› /checkpoint create "重构前的稳定版本"

步骤 2：下达重构指令

1

› 将 /hello 路由提取到 routes/hello.js 文件中，并在 server.js 中引入

步骤 3：Claude 执行重构

Claude 创建了 routes/hello.js，修改了 server.js。

步骤 4：测试发现问题

你运行 npm start，发现服务器报错：

1

Error: Cannot find module './routes/hello'

原来 Claude 在 server.js 中写的路径是 ./routes/hello，但实际文件在 routes/hello.js。

步骤 5：快速回滚

与其让 Claude 修复这个小错误，不如直接回滚，重新描述需求：

1

› /rewind

选择 “重构前的稳定版本”，瞬间恢复。

步骤 6：重新下达更明确的指令

1
2

› 将 /hello 路由提取到 routes/hello.js 文件中。
注意：在 server.js 中引入时，路径必须是 './routes/hello.js'（包含 .js 后缀）

这次 Claude 生成的代码就正确了。

总结

Checkpoint 让你可以 大胆尝试，因为你知道随时可以回到安全状态。这极大地降低了使用 AI 编程的心理负担。

第四章. 核心命令与日常工作流

掌握了基础的对话和 “后悔药” 后，现在我们需要系统学习 Claude Code 的核心命令，建立高效的日常工作流。

4.1. CLI 命令速查

Claude Code 提供了丰富的命令行参数，用于不同的使用场景。

基础命令

模型选择

1
2
3
4
5
6
7
8

# 使用 Opus 模型（更强但更贵）
claude --model opus

# 使用 Sonnet 模型（默认）
claude --model sonnet

# 使用国产模型
claude --model zhipu/glm-4-flash

上下文管理

1
2
3
4
5

# 添加额外的目录到上下文
claude --add-dir ../shared-library --add-dir /etc/configs

# 启用详细日志（用于调试）
claude --verbose

非交互式模式

1
2
3
4
5
6
7
8

# 查询后直接打印结果
claude -p "这个项目用了什么技术栈？"

# 通过管道传入内容
cat README.md | claude -p "总结这份文档"

# 指定输出格式为 JSON
claude -p "分析 package.json" --output-format json

实用示例

1
2
3
4
5
6
7

# 在 CI/CD 中使用 Claude 生成 changelog
git log --oneline -10 | claude -p "根据这些 commit 生成 changelog"

# 批量处理文件
for file in src/*.js; do
  claude -p "检查 $file 是否有安全问题" >> security-report.txt
done

4.2. 交互模式核心功能

进入交互模式后，有一些快捷键和技巧能大幅提升效率。

快捷键速查

多行输入

默认情况下，按 Enter 会立即发送消息。如果你想输入多行内容，有两种方式：

方式一：使用反斜杠（通用，所有终端都支持）

1
2
3
4

› 请帮我写一个函数：\
  1. 接收用户列表\
  2. 过滤出年龄大于 18 的用户\
  3. 返回他们的邮箱

方式二：使用 Shift + Enter（需要配置）

运行 /terminal-setup 命令配置终端，之后就可以用 Shift + Enter 换行。

编辑已发送的消息

有时候你发送消息后，发现有错别字或者想补充内容。传统方式下，你只能重新输入。但 Claude Code 允许你编辑已发送的消息。

连按两次 ESC 键，会进入编辑模式，显示你上一条消息的内容。修改后按 Enter 重新发送。

粘贴图片（实验性功能）

如果你配置了图片支持，可以用 Ctrl + V 粘贴剪贴板中的截图，让 Claude 分析。

1
2

› 我粘贴了一张设计稿，请帮我用 HTML + CSS 实现
[Ctrl+V 粘贴图片]

4.3. 斜杠命令（/ Commands）

斜杠命令是 Claude Code 的 “内置工具箱”。输入 / 后按 Tab 键，会显示所有可用命令。

核心斜杠命令

上下文管理命令详解

/clear - 清空对话历史

当你准备开始一个全新的任务时，使用此命令清空所有历史记录和上下文。

1

› /clear

/add-dir - 添加额外目录

默认情况下，Claude 只能访问当前项目目录。如果你需要引用其他目录的文件，使用此命令。

1
2

› /add-dir ../shared-utils
› /add-dir /usr/local/lib/my-library

/compact - 压缩对话历史

当对话历史变得很长，但你又不想完全清空时，此命令会智能地总结之前的对话，保留关键信息。

1

› /compact

Claude 会生成一个摘要，类似于：

1
2
3
4
5

已压缩对话历史。保留的关键信息：
- 项目是一个 Express API 服务
- 使用 PostgreSQL 数据库
- 已实现用户注册和登录功能
- 当前任务：添加邮箱验证

高级技巧：你可以将压缩后的摘要保存为自定义命令，方便后续调用。

/memory - 编辑项目记忆

这个命令会打开 CLAUDE.md 文件（项目的 “宪法”），让你编辑项目的长期记忆。

1

› /memory

会在默认编辑器中打开 CLAUDE.md。保存后，Claude 会重新加载这些规则。

快捷方式：在输入内容的开头使用 #，该行文本会自动追加到 CLAUDE.md。

1

› # 所有 API 接口必须返回统一的 JSON 格式：{ data, error, meta }

这行内容会被添加到 CLAUDE.md 的末尾。

4.4. 权限管理入门

权限管理是 Claude Code 的核心安全机制。理解它的工作原理，能让你在享受自动化的同时，保持对项目的完全控制。

4.4.1. 三种权限模式

Claude Code 支持三种执行模式：

切换模式

1
2
3
4
5
6
7
8

# 切换到自动模式
› /config set permission-mode auto

# 切换回手动模式
› /config set permission-mode manual

# 切换到规划模式
› /config set permission-mode plan

4.4.2. 理解权限提示

当 Claude 需要执行操作时，会显示一个权限提示：

1
2
3
4
5
6
7
8
9
10

我将执行以下操作：

1. [edit] 修改文件：src/server.js
   - 添加新的路由 /api/users
   - 修改端口配置

2. [bash] 执行命令：npm install express-validator
   - 安装输入验证库

是否继续？[y/n/d]

选项说明

查看详情（d 选项）

如果你不确定 Claude 要做什么，输入 d 查看详细信息：

1
2
3
4
5
6
7
8
9
10
11
12

操作 1 详情：
文件：src/server.js
变更：
  - 第 15 行：添加 `const userRoutes = require('./routes/users');`
  - 第 30 行：添加 `app.use('/api/users', userRoutes);`

操作 2 详情：
命令：npm install express-validator
工作目录：/Users/你的用户名/my-project
预计耗时：10-30 秒

是否继续？[y/n]

4.4.3. 常见权限场景

场景一：Claude 想删除文件

1
2
3
4
5
6

我将执行以下操作：

1. [bash] 执行命令：rm -rf node_modules
   - 删除 node_modules 目录以重新安装依赖

是否继续？[y/n/d]

你应该怎么做？

输入 d 查看详情，确认这是你想要的操作。如果只是想重新安装依赖，更安全的做法是：

1

› 不要删除 node_modules，直接运行 npm install 更新依赖

场景二：Claude 想执行 Git 操作

1
2
3
4
5
6
7

我将执行以下操作：

1. [bash] 执行命令：git add .
2. [bash] 执行命令：git commit -m "feat: add user validation"
3. [bash] 执行命令：git push origin main

是否继续？[y/n/d]

你应该怎么做？

如果你还没有检查代码，不要批准。输入 n，然后：

1

› 只执行 git add 和 git commit，不要 push

场景三：Claude 想修改配置文件

1
2
3
4
5
6

我将执行以下操作：

1. [edit] 修改文件：.env
   - 添加 DATABASE_URL=postgresql://localhost/mydb

是否继续？[y/n/d]

你应该怎么做？

.env 文件通常包含敏感信息。输入 d 查看详情，确认数据库 URL 是否正确。如果不对，输入 n 并重新描述：

1

› 修改 .env，但数据库 URL 应该是 postgresql://localhost:5432/production_db