<!-- title: VS Code 扩展跑通首个 Web 项目 -->

## 概述

本教程面向**完全零基础**、对命令行有畏惧心理的开发者，带你用 Claude Code 的 **VS Code 扩展**（而非终端 CLI）完成从安装、登录到跑通第一个 Web 应用的全过程。学完后你将掌握：扩展安装与首次认证、内联 diff 审查、`@`-提及文件、计划模式与自动接受，并亲手产出一个可在浏览器直接打开的待办清单应用。全程不敲一行命令行，适合非终端用户、转岗测试/产品同学、以及刚入门的前端学习者。

## 前置条件

- 一台 macOS / Windows / Linux 电脑，能联网
- 安装 **VS Code 1.98.0 或更高版本**（官方扩展的最低要求）
- 一个 **Anthropic 账户**：要么是 Claude Pro/Max 订阅（走 OAuth 登录），要么是 console.anthropic.com 的 API Key（按 token 付费）
- **无需** Node.js、无需 Python、无需任何构建工具——这是本教程刻意选择单文件 Web 项目的原因

## 第一步：为什么从 VS Code 扩展入门

很多人第一次接触 Claude Code，是从终端里敲 `claude` 开始的。但对零基础者来说，终端本身就是一道门槛：路径、环境变量、权限报错，任何一处卡住都会让人放弃。

2026 年，VS Code 扩展已经成为 Anthropic **官方推荐**的使用方式。它把 Claude Code 的全部能力装进你熟悉的编辑器里，并提供 CLI 给不了的三个东西：

1. **原生图形界面**——侧边栏面板，像聊天工具一样输入需求
2. **内联 diff（差异对比）**——Claude 改文件时，你能逐行看到"红色删除、绿色新增"，点按钮接受或拒绝
3. **计划审查**——Claude 先给你一份执行计划，你确认后再动手，避免"AI 一通乱改"

更重要的是，扩展和 CLI **共享同一份配置文件** `~/.claude/settings.json`。这意味着今天用扩展入门，将来想试终端命令行时，配置原封不动通用，学习路径不会断。

> 适用判断：如果你已经天天在终端里敲命令，CLI 入门也完全没问题；如果你看到黑色终端窗口就紧张，那就从扩展开始——这正是本教程的定位。

## 第二步：安装 VS Code 与 Claude Code 扩展

**2.1 安装 VS Code**

打开 https://code.visualstudio.com/ ，下载对应系统的安装包，一路"下一步"即可。安装后在 VS Code 菜单栏确认版本号（`Code → 关于` 或 `Help → About`）不低于 1.98.0。

**2.2 安装 Claude Code 扩展**

有两种等价方式，任选其一：

- **方式 A（图形界面）**：点左侧活动栏的"扩展"图标（或按 `Ctrl+Shift+X` / Mac 下 `Cmd+Shift+X`），搜索框输入 `Claude Code`，找到 Anthropic 官方发布的扩展，点 **Install**。
- **方式 B（命令面板）**：按 `Ctrl+Shift+P` / `Cmd+Shift+P` 打开命令面板，输入 `Extensions: Install Extensions`，回车后同样搜索 `Claude Code`。

**预期结果**：安装完成后，左侧活动栏会出现一个 Claude 图标，状态栏也可能出现 `Claude` 字样。点开图标，右侧（或侧边栏）会弹出 Claude 面板。

**常见问题**

| 现象 | 原因与解决 |
|---|---|
| 搜索不到扩展 | VS Code 版本低于 1.98.0，先升级编辑器 |
| 安装后图标不出现 | 重启 VS Code；或用命令面板搜 `Claude Code: Open` 手动唤起 |
| 企业网络拦截扩展市场 | 让管理员把 `marketplace.visualstudio.com` 加入白名单 |

## 第三步：首次登录配置

首次打开 Claude 面板，扩展会要求你认证。有两条路：

**3.1 OAuth 登录（推荐订阅用户）**

点 **Sign in with Claude**，浏览器会自动跳转到 Anthropic 登录页。用你的 Claude Pro/Max 账号登录并授权，回到 VS Code 时扩展已自动完成认证。这种方式计费走你的订阅额度，无需单独管理密钥。

**3.2 API Key 登录（推荐按量付费用户）**

到 https://console.anthropic.com/ 创建一个 API Key（形如 `sk-ant-...`），复制后在扩展的登录界面选择 **Use an API key**，粘贴进去即可。这种方式按实际 token 消耗计费，适合想精确控制成本的开发者。

**预期结果**：登录后面板顶部显示已连接状态，输入框可输入。此时你的 `~/.claude/settings.json` 已生成，里面记录了认证与配置信息——这就是前面说的"扩展和 CLI 共享"的那份文件。

**常见问题**

- **跳转浏览器后一直转圈**：检查代理/VPN 是否把 `claude.ai` 或 `console.anthropic.com` 也走了代理导致鉴权异常，尝试直连或更换节点。
- **API Key 报 401**：密钥前后的空格没去掉，或密钥已失效，重新生成一份。
- **国内访问困难**：可配置第三方中转或国产模型端点（需在 settings 中设置 `ANTHROPIC_BASE_URL` 与对应密钥），但首跑建议先用官方源把流程跑通。

## 第四步：认识扩展界面与核心操作

在动手写项目前，先花两分钟认识四个会反复用到的能力。

**4.1 唤起面板**

- 点活动栏的 Claude 图标，或用快捷键 `Ctrl+Esc` / `Cmd+Esc`（不同版本可能略有差异，以官方文档为准）唤起面板。
- 你可以同时开多个对话标签，甚至在独立窗口里开一个对话，互不干扰。

**4.2 内联 diff（审查每一处改动）**

当 Claude 要修改你的文件时，编辑器里会弹出差异视图：左边是原内容，右边是新内容。你可以：

- **Accept（接受）**：把这一处改动写入文件
- **Reject（拒绝）**：保留原样

这种"先看后批"的机制，是 AI 写代码时最让人安心的护栏——它不会偷偷改你的代码。

**4.3 `@`-提及（精准喂上下文）**

在输入框敲 `@`，会弹出当前工作区的文件列表；选中文件即把它的内容作为上下文喂给 Claude。更精细的是 `@文件名:行号`，比如 `@app.js:30` 只引用第 30 行附近，避免塞入无关代码、节省 token。

**4.4 自动接受模式**

面板里有一个 **Auto-accept**（自动接受编辑）开关。打开后，Claude 的改动会自动写入，无需逐个点确认。适合信任度高、迭代快的场景；首次学习时**建议先关闭**，亲手体会 diff 审查流程。

## 第五步：创建项目目录并初始化

**5.1 新建文件夹**

在桌面或任意位置新建一个文件夹，命名为 `my-first-web`。

**5.2 用 VS Code 打开**

两种方式：
- VS Code 菜单 `File → Open Folder`，选中 `my-first-web`
- 或在文件管理器里右键该文件夹 → "通过 Code 打开"（需安装时勾选了右键菜单集成）

**5.3 让 Claude 帮你建文件**

打开 Claude 面板，确认当前工作区显示为 `my-first-web`。接下来真正进入"对话式编程"。

## 第六步：用自然语言生成第一个 Web 应用

在 Claude 面板输入以下需求（可以直接复制，也可以用自己话改写）：

```
帮我创建一个待办清单 Web 应用，要求：
1. 单个 index.html 文件，HTML+CSS+JS 全部内嵌，零外部依赖
2. 功能：输入框 + 添加按钮，可勾选完成（划线）、删除任务
3. 用 localStorage 保存数据，刷新页面不丢失
4. 简洁美观，居中布局，最大宽度 480px
```

**预期行为**：

1. Claude 会先给出一份**简短计划**（创建哪些内容、用什么结构），部分场景下直接进入编辑。
2. 接着创建 `index.html` 文件。如果是 diff 模式，你会看到一份完整的"新增文件"差异——点 **Accept** 接受。
3. 文件树里出现 `index.html`，内容已填好。

**关键体验点**：整个过程中你**没有**敲任何 HTML/CSS/JS 代码，只描述了"我要什么"。这就是对话式编程的核心。

## 第七步：运行预览

零依赖单文件 Web 应用的运行方式最简单：

**方式 A（推荐）**：在 VS Code 扩展市场搜 `Live Server` 安装，右键 `index.html` → **Open with Live Server**。浏览器自动打开 `http://127.0.0.1:5500/index.html`，改代码会自动刷新。

**方式 B（无插件）**：直接在文件管理器里双击 `index.html`，用默认浏览器打开（`file://` 协议）。功能正常，只是改代码需手动刷新。

**预期结果**：浏览器出现一个居中的"我的待办清单"，有输入框和"添加"按钮。试着添加几条任务，勾选完成（文字划线变灰），删除任务。刷新页面，数据仍在——说明 localStorage 生效了。

**常见问题**

- **页面空白**：按 `F12` 打开浏览器控制台看报错；通常是 JS 有语法错误。把控制台错误截图发给 Claude，它能直接修。
- **Live Server 端口 5500 被占用**：右键时可改端口，或用方式 B 直接打开文件。

## 第八步：迭代——加功能、修样式

应用能跑后，继续和 Claude 对话加功能。这是体会 AI 编程效率的最佳环节。试试这些指令：

```
1. 给每个任务加一个"优先级"下拉（高/中/低），高优先级用红色标记
2. 顶部加一个统计："共 X 项，已完成 Y 项"
3. 加一个"清除已完成"按钮
4. 把标题颜色改成深蓝，加个柔和的阴影
```

每一条，Claude 都会以 diff 形式修改 `index.html`。**建议这一步打开 Auto-accept**，连续迭代；遇到不符合预期的改动，按 `Ctrl+Z`（VS Code 撤销）即可回退单次编辑。

如果你希望它只改某一块，用 `@`-提及：先 `@index.html` 再输入"只改样式部分，逻辑不要动"，能显著减少误伤。

## 实战案例：完整可运行的待办清单

以下是本教程产出的完整 `index.html`，复制保存即可在浏览器直接运行，无需任何安装。它综合体现了上面八个步骤的成果：

```html
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>我的待办清单</title>
  <style>
    body { font-family: system-ui, sans-serif; max-width: 480px;
           margin: 40px auto; color: #222; }
    h1 { color: #1a3a6b; text-shadow: 0 1px 2px rgba(0,0,0,.08); }
    .stats { color: #666; font-size: 14px; margin: 8px 0; }
    .done span { text-decoration: line-through; color: #999; }
    .high { color: #d33; font-weight: 600; }
    li { display: flex; align-items: center; gap: 8px; padding: 6px 0;
         border-bottom: 1px solid #eee; }
    .pri { font-size: 12px; }
    button { cursor: pointer; }
    .del { margin-left: auto; border: none; background: transparent; color:#999; }
    .clear { margin-top: 12px; }
  </style>
</head>
<body>
  <h1>我的待办清单</h1>
  <div class="stats" id="stats"></div>
  <form id="form">
    <input id="input" placeholder="输入任务..." autocomplete="off" style="width:55%">
    <select id="pri" class="pri">
      <option value="中">中</option>
      <option value="高">高</option>
      <option value="低">低</option>
    </select>
    <button type="submit">添加</button>
  </form>
  <ul id="list"></ul>
  <button class="clear" id="clearDone">清除已完成</button>

  <script>
    const KEY = 'todos';
    let todos = JSON.parse(localStorage.getItem(KEY) || '[]');
    const list = document.getElementById('list');
    const save = () => localStorage.setItem(KEY, JSON.stringify(todos));

    function render() {
      list.innerHTML = '';
      todos.forEach((t, i) => {
        const li = document.createElement('li');
        if (t.done) li.className = 'done';
        const cb = document.createElement('input');
        cb.type = 'checkbox'; cb.checked = t.done;
        cb.onchange = () => { todos[i].done = cb.checked; save(); render(); };

        const pri = document.createElement('span');
        pri.className = 'pri' + (t.pri === '高' ? ' high' : '');
        pri.textContent = `[${t.pri}]`;

        const span = document.createElement('span');
        span.textContent = t.text;

        const del = document.createElement('button');
        del.className = 'del'; del.textContent = '✕';
        del.onclick = () => { todos.splice(i, 1); save(); render(); };

        li.append(cb, pri, span, del);
        list.appendChild(li);
      });
      const done = todos.filter(t => t.done).length;
      document.getElementById('stats').textContent =
        `共 ${todos.length} 项，已完成 ${done} 项`;
    }

    document.getElementById('form').onsubmit = e => {
      e.preventDefault();
      const input = document.getElementById('input');
      const pri = document.getElementById('pri').value;
      if (!input.value.trim()) return;
      todos.push({ text: input.value.trim(), done: false, pri });
      input.value = ''; save(); render();
    };

    document.getElementById('clearDone').onclick = () => {
      todos = todos.filter(t => !t.done); save(); render();
    };

    render();
  </script>
</body>
</html>
```

把这段代码完整保存为 `index.html`，双击打开——添加任务、勾选、删除、清除已完成、刷新保留，全部可用。这就是你的第一个 Claude Code 驱动的 Web 项目。

## 工作流程全景

```mermaid
flowchart TD
    A[安装 VS Code 1.98+] --> B[市场搜索并安装 Claude Code 扩展]
    B --> C{首次认证}
    C -->|OAuth| D[浏览器登录 Claude Pro/Max 账户]
    C -->|API Key| E[粘贴 console.anthropic.com 密钥]
    D --> F[生成 ~/.claude/settings.json]
    E --> F
    F --> G[新建 my-first-web 文件夹并打开]
    G --> H[快捷键唤起 Claude 面板]
    H --> I[自然语言描述需求 + @-提及文件]
    I --> J[Claude 给出计划 / 内联 diff]
    J --> K{审查 diff}
    K -->|接受| L[代码写入 index.html]
    K -->|拒绝/修改| I
    L --> M[Live Server 预览运行]
    M --> N[迭代加功能 / 修 bug]
    N --> I
```

## 常见问题速查

- **扩展和 CLI 配置会冲突吗？** 不会，两者共享 `~/.claude/settings.json`，认证、权限、自定义命令一次配置两边通用。
- **为什么我看到的快捷键和教程不一样？** 扩展在持续更新，快捷键以你本机 `Ctrl+Shift+P` 搜索 `Claude` 看到的命令和官方文档为准。
- **diff 太多看不过来怎么办？** 打开 Auto-accept 让它连续改，事后用 `Ctrl+Z` 逐步回退你不满意的部分。
- **能不能升级成更"现代"的技术栈？** 当然。等单文件玩熟了，可以让 Claude 用 `@`-提及或终端帮你 `npm create vite` 初始化 React + Vite 项目，扩展同样能驱动。
- **数据存哪了？** 本案例存在浏览器的 localStorage，换浏览器/清缓存会丢。进阶可以让 Claude 改造成调用后端 API 持久化。

## 延伸阅读

- 官方 VS Code 集成文档：`code.claude.com/docs/zh-CN/vs-code`——快捷键、`@`-提及、计划审查的权威说明
- 官方快速开始：`code.claude.com/docs/zh-CN/quickstart`——CLI 与扩展的总入口
- JetBrains 插件市场页：`plugins.jetbrains.com/plugin/27310`——IntelliJ/PyCharm/WebStorm 用户对应的 Beta 插件
- 进阶可读「Claude Code 五端选型（CLI / VS Code / JetBrains / Desktop / Web）」，理解不同入口的取舍后再决定主力端

## 训练营适用性评估

| 维度 | 评估 |
|---|---|
| 适合训练营类型 | **零基础 / 通识型 / 前端入门** 营，也适合企业内部"全员 AI 编程扫盲"营 |
| 学员基础要求 | 会用浏览器和 VS Code 即可，**无需**命令行/前端基础 |
| 预计教学时长 | **1.5–2 小时**：安装登录 30 分钟，生成+运行 30 分钟，迭代+答疑 45 分钟 |
| 产出物 | 一个可运行、可带走的单文件待办清单，学员有强成就感 |
| 后续衔接 | 顺理成章衔接"CLI 入门""计划模式""多文件重构"等进阶主题 |
| 风险点 | 国内网络登录可能卡顿，需提前准备代理或国产模型中转方案 |

## 参考来源

1. [在 VS Code 中使用 Claude Code — 官方文档](https://code.claude.com/docs/zh-CN/vs-code) — 扩展前置条件、内联 diff、`@`-提及与快捷键的权威说明
2. [快速开始 — Claude Code Docs](https://code.claude.com/docs/zh-CN/quickstart) — 安装、首次认证与基础工作流的官方总入口
3. [Claude Code 原生安装指南 — 博客园 Carvers](https://www.cnblogs.com/carver/articles/19836937) — `curl -fsSL https://claude.ai/install.sh` 一键安装与 `~/.local/bin/claude` 路径细节
4. [Claude Code 保姆级入门教程，不学命令行版 — Ben 的博客](https://benx.ai/blog/posts/claude-code-vscode-tutorial-2026-03/) — VS Code 扩展零终端入门的社区实践参考
5. [2026 年 Claude Code 完全使用教程 — SimilarLabs](https://similarlabs.com/zh/blog/claude-code-tutorial-guide) — 安装配置、核心命令与工作流的系统梳理

> [!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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)