# Claude Code 零基础起手：装通 VS Code 扩展并修复第一个真实 Bug
## 概述
本教程面向**完全没用过 Claude Code** 的开发者，目标是用一条原生安装命令把命令行工具装好，再装上官方 VS Code 扩展，然后在一个**带 Bug 的小型真实代码库**里完整走通「定位 → 修复 → 验证」的闭环。读完你将掌握：三平台安装、首次认证、IDE 与 CLI 的三种联动方式、计划模式与 inline diff 审阅、以及 `@` 提及、`#` 记忆、`Shift+Tab` 切模式等高频提效操作。
## 前置条件
| 项目 | 要求 | 说明 |
|------|------|------|
| 操作系统 | macOS 12+、Windows 10/11 或主流 Linux | Windows 推荐装 Git for Windows，以便 Bash 工具可用 |
| 账号 | Anthropic Console 账号 或 Claude Pro/Max 订阅 | 用于 OAuth 登录；也可改用 API Key |
| 编辑器 | VS Code（或 Cursor / Windsurf） | 本教程以 VS Code 为准 |
| 终端 | 系统自带终端 / PowerShell / 集成终端均可 | 原生安装器不依赖 Node.js |
| 网络 | 可访问 `claude.ai` 与 `api.anthropic.com` | 首次登录与对话都需要 |
> 不需要预先安装 Node.js。2026 年官方主推的**原生安装器**（native installer）会自带运行时，比 `npm` 路线更省事，下文以此为准。
---
## 正文：分步骤上手
### 步骤 1：确认账号与额度
打开 [console.anthropic.com](https://console.anthropic.com) 登录，确认已绑定支付方式或拥有 Pro/Max 订阅。零基础最常踩的坑不是装不上，而是**额度未开通导致首跑 401**。
- **预期结果**：Console 仪表盘能看到余额或订阅状态为 Active。
- **常见问题**：
- 报错 `credit_balance_too_low`：充值或确认订阅生效。
- 用的是团队/企业账号：确认自己被授予了使用权限。
### 步骤 2：用原生安装器装好 CLI（三平台）
打开终端，按系统复制对应命令执行。
**macOS / Linux / WSL：**
```bash
curl -fsSL https://claude.ai/install.sh | bash
```
**Windows PowerShell：**
```powershell
irm https://claude.ai/install.ps1 | iex
```
**包管理器（可选）：**
```bash
# macOS / Linux
brew install --cask claude-code
# Windows
winget install Anthropic.ClaudeCode
```
安装完成后验证：
```bash
claude --version
```
- **预期结果**：输出版本号（2026 年默认随 Opus 4.8 系），例如 `2.1.x`。
- **常见问题**：
- `command not found`：把安装目录加入 PATH。macOS/Linux 通常写入 `~/.zshrc` 或 `~/.bashrc`，执行 `source ~/.zshrc`；Windows 则重启 PowerShell。
- 公司网络拦截脚本：换用 `npm install -g @anthropic-ai/claude-code`（需 Node.js 18+）作为退路。
- 安装脚本权限不足：Linux 下先 `chmod +x` 或加 `sudo`。
### 步骤 3：首次认证
在终端任意目录执行：
```bash
claude
```
首次启动会弹出浏览器完成 OAuth 授权；授权后终端出现交互式提示符 `>`。
如果你更想用 API Key（适合无浏览器环境或走第三方中转）：
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
claude
```
- **预期结果**：看到欢迎界面与可输入的提示框，底部显示当前模型。
- **常见问题**：
- 浏览器没自动打开：复制终端里的链接手动粘贴。
- `invalid_api_key`：确认 Key 未过期、未带多余空格、账户已开通。
### 步骤 4：安装官方 VS Code 扩展
1. 打开 VS Code → 左侧扩展面板（`Ctrl+Shift+X` / `Cmd+Shift+X`）。
2. 搜索 **Claude Code**（发布者为 Anthropic），点 Install。
3. 安装后侧边栏多出 Claude 图标，命令面板（`Ctrl+Shift+P`）里出现 `Claude Code: Open` 等命令。
> 该扩展是官方推荐的图形化入口，把命令行智能体包装成 IDE 原生界面：**内联 diff（inline diff）、`@` 提及、计划审阅、键盘快捷键**一应俱全。
- **常见问题**：
- 扩展找不到：确认 VS Code 版本 ≥ 1.90，旧版可能不显示。
- 扩展装上但无反应：检查 CLI 是否真的装好（步骤 2 的 `claude --version`），扩展依赖本地 CLI。
### 步骤 5：认清楚「在 VS Code 里跑 Claude Code 的三种姿势」
这点是零基础最容易混淆的，先理清再动手：
1. **图形扩展面板**：点侧边栏图标打开，纯可视化，适合改 bug、审 diff。
2. **集成终端跑 CLI**：在 VS Code 终端里直接敲 `claude`，体验与系统终端一致。
3. **CLI ↔ IDE 联动**：在终端会话里输入 `/ide`，命令行会自动连上当前 VS Code 窗口，于是你在终端下指令，修改却以 inline diff 显示在编辑器里——**两全其美**。
```mermaid
flowchart LR
A[VS Code 窗口] --> B[图形扩展面板]
A --> C[集成终端 CLI]
C --> D["/ide 联动"]
D --> E[inline diff 显示在编辑器]
B --> E
```
- **建议**：本教程用「终端 `/ide` 联动」走完，因为它同时让你熟悉命令语法和图形审阅。
### 步骤 6：准备一个带 Bug 的实战项目
新建空目录并初始化一个最小 Node.js 项目（也可换成 Python，流程一致）：
```bash
mkdir bug-demo && cd bug-demo
npm init -y
npm install express
```
新建 `server.js`，故意埋一个**异步竞态 + 空指针**的 Bug：
```javascript
const express = require('express');
const app = express();
app.use(express.json());
// 模拟用户仓库
let users = [];
app.get('/users/:id', (req, res) => {
const id = req.params.id;
// Bug 1: 字符串 id 与数字 id 混用，永远匹配不到
const user = users.find(u => u.id === id);
res.json(user.name); // Bug 2: user 可能为 undefined
});
app.post('/users', (req, res) => {
// Bug 3: 异步写入未等待，并发会丢数据
setTimeout(() => { users.push({ id: req.body.id, name: req.body.name }); }, 10);
res.json({ ok: true });
});
app.listen(3000, () => console.log('running on 3000'));
```
测试脚本 `test.js`（暴露 Bug）：
```javascript
const assert = require('assert');
async function run() {
// 1. 创建用户
await fetch('http://localhost:3000/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ id: 1, name: 'Alice' })
});
// 2. 立即查询（大概率命中竞态 + 空指针）
const r = await fetch('http://localhost:3000/users/1');
const body = await r.text();
assert.strictEqual(body, '"Alice"', `期望 "Alice"，实际 ${body}`);
console.log('测试通过 ✅');
}
run().catch(e => { console.error('测试失败 ❌', e.message); process.exit(1); });
```
跑一下确认它确实挂：
```bash
node server.js & # 另开终端
node test.js
```
- **预期结果**：测试失败，提示 `Cannot read properties of undefined (reading 'name')` 或断言不通过。
### 步骤 7：建立项目记忆并进入计划模式
回到 Claude Code 会话（VS Code 终端里已 `/ide` 连上）：
```text
> /init
```
`/init` 会扫描项目并生成 `CLAUDE.md`，记录技术栈、约定、常用命令，后续每次会话自动加载。接着按 `Shift+Tab` 把模式切到 **Plan Mode**（底部会显示 `plan mode on`）——此时 Claude 只规划不落盘，先和你对齐方案。
- **常见问题**：
- `/init` 生成内容偏空：项目太小没东西可写，正常，可手动补充。
- 找不到 `Shift+Tab` 切换：每按一次在 普通 → 自动接受 → 计划 三模式间循环，多按几下。
### 步骤 8：让 Claude 定位 Bug 并产出修复方案
在计划模式里输入：
```text
> 我跑了 node test.js 失败，帮我分析 server.js 里 GET /users/:id 和 POST /users
的三个 Bug，给出最小修复方案，先不要改文件。
```
Claude 会读 `server.js`、`test.js`，给出类似分析：
- **Bug 1**：`req.params.id` 是字符串，`u.id` 是数字，`===` 永不成立 → 统一成 `Number(id)`。
- **Bug 2**：未判空就访问 `.name` → 加 `if (!user) return res.status(404).json({error:'not found'})`。
- **Bug 3**：`setTimeout` 异步写入导致 POST 后立即 GET 读不到 → 改为同步 push，或返回前 await。
确认方案后，再按 `Shift+Tab` 退回普通模式让它动手。
### 步骤 9：审阅 inline diff、接受、跑测试验证
让 Claude 修复：
```text
> 按你的方案修复，并补一条「user 不存在返回 404」的分支。
```
由于之前 `/ide` 联动，修改会以 **inline diff** 形式出现在编辑器里：旧代码在上、新代码在下，绿/红标色。你可以逐处 **Accept / Reject**。
预期修复后片段：
```javascript
app.get('/users/:id', (req, res) => {
const user = users.find(u => u.id === Number(req.params.id));
if (!user) return res.status(404).json({ error: 'user not found' });
res.json(user.name);
});
app.post('/users', (req, res) => {
users.push({ id: req.body.id, name: req.body.name }); // 同步写入
res.json({ ok: true });
});
```
随后让它验证：
```text
> 重启服务并跑 node test.js，确认通过。
```
- **预期结果**：Claude 用 Bash 工具重启 `server.js`、跑 `node test.js`，终端打印 `测试通过 ✅`。
- **常见问题**：
- 提示要 Bash 权限：首次执行命令会请求授权，选 Yes（或用 `bq` 加入白名单避免重复问）。
- 端口被占：旧进程没杀干净，让它 `kill` 占用 3000 的进程再重启。
### 步骤 10：提效高频操作速查
| 操作 | 快捷键/语法 | 作用 |
|------|-------------|------|
| 切换模式 | `Shift+Tab` | 普通 / 自动接受 / 计划 循环 |
| 中断当前任务 | `Esc` | 停下正在跑的命令 |
| 编辑上一条消息 | `Esc Esc` | 改完重发，省 token |
| 提及文件 | `@server.js` | 让它精准读指定文件 |
| 写入记忆 | `#约定用 tabs` | 持久化到 CLAUDE.md |
| 清空上下文 | `/clear` | 换任务时重置，防污染 |
| 压缩上下文 | `/compact` | 长会话续命 |
| 查看配置 | `/config` | 模型、权限一览 |
---
## 实战案例小结
完整闭环已跑通：**装 CLI → 认证 → 装 IDE 扩展 → `/ide` 联动 → `/init` 建记忆 → Plan 模式定位 → inline diff 审阅修复 → 跑测试验证**。把这套流程套到你自己的真实仓库，就是日常结对编程的标准动作。
进阶可叠加：把团队代码规范做成 Skill 自动触发、给重复命令加斜杠快捷命令、用 `git` 让 Claude 自动起分支提 PR——这些属于后续专题，本篇先把「第一个真实 Bug」修漂亮。
## 工作流程全景图
```mermaid
flowchart TD
A[1. 装原生 CLI
curl/irm 一条命令] --> B[2. 首次认证
OAuth 或 API Key]
B --> C[3. 装 VS Code 扩展]
C --> D[4. 终端 /ide 联动 IDE]
D --> E[5. /init 生成 CLAUDE.md]
E --> F[6. Shift+Tab 进 Plan 模式]
F --> G[7. 定位 Bug 产出方案]
G --> H[8. 退出 Plan 让其动手]
H --> I[9. inline diff 逐条 Accept]
I --> J[10. 重启 + 跑测试验证]
J --> K{测试通过?}
K -- 否 --> G
K -- 是 --> L[闭环完成 ✅]
```
## 延伸阅读
- **Claude Code 官方文档（VS Code）**：`code.claude.com/docs/en/vs-code` — 扩展能力官方权威说明。
- **Quickstart**：`code.claude.com/docs/en/quickstart` — 三平台快速起步。
- **Best Practices**：`code.claude.com/docs/en/best-practices` — 把智能体用好、写出好 CLAUDE.md 的官方心法。
- **终端新手指南**：`code.claude.com/docs/en/terminal-guide` — 没用过命令行的读者补基础。
## 训练营适用性评估
| 维度 | 评估 |
|------|------|
| 适合训练营 | 「AI 编程入门营」「全员 AI 提效训练营」「前端/后端工程师 AI 赋能 Day 1」 |
| 学员基础 | 会基本命令行与一门语言即可，完全零 AI 工具经验也能跟上 |
| 建议时长 | 讲解 + 跟练 **2 小时**；含自行修复自家项目 Bug 的练习则 **半天** |
| 评估方式 | 学员独立复刻「修首个 Bug」闭环：能解释三个 Bug、能审阅 diff、能让测试转绿 |
| 衔接下一课 | 本篇为入门，后续可接 Skill 开发、MCP 工具集成、Headless 自动化 |
## 参考来源
1. [Use Claude Code in VS Code — Claude Code Docs](https://code.claude.com/docs/en/vs-code) — 官方扩展功能、inline diff、@提及与快捷键的权威说明。
2. [Advanced setup — Claude Code Docs](https://code.claude.com/docs/en/setup) — 三平台原生安装器、包管理器与系统要求。
3. [Claude Code Native Installer: Skip Node.js Entirely — claudefa.st](https://claudefa.st/blog/guide/native-installer) — 一条命令、免 Node.js 的安装路线详解。
4. [Claude Code Cheat Sheet — ComputingForGeeks](https://computingforgeeks.com/claude-code-cheat-sheet/) — 2.1.x 速查表，含斜杠命令与 CLI 标志（2026）。
5. [Claude Code in VS Code: Complete Setup Guide 2026 — explainx.ai](https://www.explainx.ai/blog/claude-code-vscode-ide-extension-setup-guide-2026) — IDE 与 CLI 三种联动方式的实操对照。
> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
