Claude Code 零基础起手：装通 VS Code 扩展并修复第一个真实 Bug

概述

本教程面向完全没用过 Claude Code 的开发者，目标是用一条原生安装命令把命令行工具装好，再装上官方 VS Code 扩展，然后在一个带 Bug 的小型真实代码库里完整走通「定位 → 修复 → 验证」的闭环。读完你将掌握：三平台安装、首次认证、IDE 与 CLI 的三种联动方式、计划模式与 inline diff 审阅、以及 @ 提及、# 记忆、Shift+Tab 切模式等高频提效操作。

前置条件

不需要预先安装 Node.js。2026 年官方主推的原生安装器（native installer）会自带运行时，比 npm 路线更省事，下文以此为准。

正文：分步骤上手

步骤 1：确认账号与额度

打开 console.anthropic.com 登录，确认已绑定支付方式或拥有 Pro/Max 订阅。零基础最常踩的坑不是装不上，而是额度未开通导致首跑 401。

• 预期结果：Console 仪表盘能看到余额或订阅状态为 Active。
• 常见问题：
• 报错 credit_balance_too_low：充值或确认订阅生效。
• 用的是团队/企业账号：确认自己被授予了使用权限。

步骤 2：用原生安装器装好 CLI（三平台）

打开终端，按系统复制对应命令执行。

macOS / Linux / WSL：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

包管理器（可选）：

# macOS / Linux
brew install --cask claude-code
# Windows
winget install Anthropic.ClaudeCode

安装完成后验证：

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：首次认证

在终端任意目录执行：

claude

首次启动会弹出浏览器完成 OAuth 授权；授权后终端出现交互式提示符 >。

如果你更想用 API Key（适合无浏览器环境或走第三方中转）：

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 显示在编辑器里——两全其美。

flowchart LR
    A[VS Code 窗口] --> B[图形扩展面板]
    A --> C[集成终端 CLI]
    C --> D["/ide 联动"]
    D --> E[inline diff 显示在编辑器]
    B --> E

• 建议：本教程用「终端 /ide 联动」走完，因为它同时让你熟悉命令语法和图形审阅。

步骤 6：准备一个带 Bug 的实战项目

新建空目录并初始化一个最小 Node.js 项目（也可换成 Python，流程一致）：

mkdir bug-demo && cd bug-demo
npm init -y
npm install express

新建 server.js，故意埋一个异步竞态 + 空指针的 Bug：

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）：

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); });

跑一下确认它确实挂：

node server.js &   # 另开终端
node test.js

• 预期结果：测试失败，提示 Cannot read properties of undefined (reading 'name') 或断言不通过。

步骤 7：建立项目记忆并进入计划模式

回到 Claude Code 会话（VS Code 终端里已 /ide 连上）：

> /init

/init 会扫描项目并生成 CLAUDE.md，记录技术栈、约定、常用命令，后续每次会话自动加载。接着按 Shift+Tab 把模式切到 Plan Mode（底部会显示 plan mode on）——此时 Claude 只规划不落盘，先和你对齐方案。

• 常见问题：
• /init 生成内容偏空：项目太小没东西可写，正常，可手动补充。
• 找不到 Shift+Tab 切换：每按一次在 普通 → 自动接受 → 计划 三模式间循环，多按几下。

步骤 8：让 Claude 定位 Bug 并产出修复方案

在计划模式里输入：

> 我跑了 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 修复：

> 按你的方案修复，并补一条「user 不存在返回 404」的分支。

由于之前 /ide 联动，修改会以 inline diff 形式出现在编辑器里：旧代码在上、新代码在下，绿/红标色。你可以逐处 Accept / Reject。

预期修复后片段：

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 });
});

随后让它验证：

> 重启服务并跑 node test.js，确认通过。

• 预期结果：Claude 用 Bash 工具重启 server.js、跑 node test.js，终端打印 测试通过 ✅。
• 常见问题：
• 提示要 Bash 权限：首次执行命令会请求授权，选 Yes（或用 bq 加入白名单避免重复问）。
• 端口被占：旧进程没杀干净，让它 kill 占用 3000 的进程再重启。

步骤 10：提效高频操作速查

实战案例小结

完整闭环已跑通：装 CLI → 认证 → 装 IDE 扩展 → /ide 联动 → /init 建记忆 → Plan 模式定位 → inline diff 审阅修复 → 跑测试验证。把这套流程套到你自己的真实仓库，就是日常结对编程的标准动作。

进阶可叠加：把团队代码规范做成 Skill 自动触发、给重复命令加斜杠快捷命令、用 git 让 Claude 自动起分支提 PR——这些属于后续专题，本篇先把「第一个真实 Bug」修漂亮。

工作流程全景图

flowchart TD
    A[1. 装原生 CLI<br/>curl/irm 一条命令] --> B[2. 首次认证<br/>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 — 没用过命令行的读者补基础。

训练营适用性评估

参考来源

1. Use Claude Code in VS Code — Claude Code Docs — 官方扩展功能、inline diff、@提及与快捷键的权威说明。
2. Advanced setup — Claude Code Docs — 三平台原生安装器、包管理器与系统要求。
3. Claude Code Native Installer: Skip Node.js Entirely — claudefa.st — 一条命令、免 Node.js 的安装路线详解。
4. Claude Code Cheat Sheet — ComputingForGeeks — 2.1.x 速查表，含斜杠命令与 CLI 标志（2026）。
5. Claude Code in VS Code: Complete Setup Guide 2026 — explainx.ai — 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 等场景全覆盖。