# 在 VS Code 里首跑 Claude Code：编辑器内安装、配置与首个改造任务 ## 概述 本教程面向**零基础开发者**，带你跳过命令行的陡峭学习曲线，直接在你最熟悉的编辑器里跑通 Claude Code。学完你将掌握：VS Code 扩展的安装与登录、Spark 面板与权限模式的使用、`@`-提及与选区上下文让 AI 看懂你的代码、内联 diff 审查与 Checkpoint 回退，并完成一个真实的"修 Bug + 提交"实战任务。全程不写一行 curl，不碰 API Key。 --- ## 前置条件 | 条目 | 说明 | |------|------| | 编辑器 | **VS Code 1.98.0 或更高**（Cursor、Devin Desktop、Kiro 等 VS Code 衍生版同样适用） | | 账号 | 任意付费 Claude 订阅（Pro / Max / Team / Enterprise）或 Claude Console 账号——**无需 API Key** | | 操作系统 | macOS、Windows、Linux 任一；macOS 需注意 Tahoe 的快捷键冲突（见文末排查） | | 可选 | 若想在集成终端里运行 `claude` 命令，需额外安装独立 CLI；本教程主体不依赖它 | > 官方明确说明：VS Code 扩展**是推荐的 Claude Code 使用方式**。它内置了一份私有 CLI 供聊天面板使用，但这份 CLI **不会**加入你的 shell PATH——这是初学者最容易踩的第一个坑，后文详述。 --- ## 第一步：理解两种运行形态——扩展 vs CLI Claude Code 有两张"面孔"，理解它们的分工是后续一切操作的基础： - **VS Code 扩展（图形面板）**：你今天要用的主力。提供可视化聊天、内联 diff、`@`-提及、Checkpoint、Plan 审查。命令和技能是 CLI 的一个**子集**。 - **CLI（命令行）**：在终端里输入 `claude` 启动。功能最全——所有斜杠命令、`!` bash 快捷方式、Tab 补全都在这里。 两者**共享同一份会话历史**。你在扩展里聊到一半，可以随时在集成终端运行 `claude --resume` 接着干。这种"图形为主、终端为辅"的双形态设计，让你既能享受可视化审查，又能在需要时下沉到全功能 CLI。 ```mermaid graph LR A[你的 VS Code 编辑器] -->|选区/打开文件/诊断| B[内置 IDE MCP 服务器
命名: ide · 仅本机回环] B -->|随机端口 + 一次性 Token| C[Claude Code 引擎
扩展面板 / 集成终端 CLI] C -->|加密请求| D[(Anthropic API)] D -->|代码建议 / diff| C C -->|可视化 diff 审查| A style B fill:#e8f0fe,stroke:#4285f4 style D fill:#fce8e6,stroke:#ea4335 ``` 这张图揭示了一个常被忽略的事实：扩展激活时会**在本机启动一个名为 `ide` 的 MCP 服务器**（绑定 `127.0.0.1` 随机高端口，每次激活生成新的随机 Token，写入 `~/.claude/ide/` 下权限为 `0600` 的锁文件）。它就是让 CLI 能在 VS Code 原生 diff 视图里打开改动、读取你的选区、执行 Jupyter 单元格的"幕后桥梁"。 --- ## 第二步：安装 VS Code 扩展 **操作说明：** 1. 打开 VS Code，按 `Cmd+Shift+X`（Mac）或 `Ctrl+Shift+X`（Windows/Linux）打开扩展视图。 2. 搜索框输入 **Claude Code**。 3. 认准发布者为 **Anthropic** 的那一个，点击 **Install**。 ```bash # 或者用官方直链一步安装（在 VS Code 里点击会自动跳转） # vscode:extension/anthropic.claude-code ``` **预期结果：** 安装完成后，编辑器右上角的**编辑器工具栏**会出现一个 **✱（Spark）图标**——但前提是**你已经打开了一个文件**。仅打开文件夹不会显示该图标。 **常见问题：** - **装完看不到 Spark 图标？** 三种可能：①还没打开任何文件；②VS Code 版本低于 1.98.0；③处于 Restricted Mode（受限模式，扩展不工作）。可改点**右下角状态栏的 "✱ Claude Code"**，它不需要打开文件也能用。若仍不行，运行命令面板里的 `Developer: Reload Window` 重载窗口。 - **与其他 AI 扩展冲突？** Cline、Continue 等可能抢占快捷键，安装时先临时禁用它们。 - **用的是 Cursor / Kiro？** 同样在各自的扩展视图搜索安装；不支持时也可从 [Open VSX registry](https://open-vsx.org/extension/Anthropic/claude-code) 安装。 --- ## 第三步：首次登录与引导清单 **操作说明：** 1. 点击 Spark 图标打开 Claude 面板（首次会弹出登录界面）。 2. 点击 **Sign in**，浏览器自动打开完成 OAuth 授权。 3. 回到 VS Code，面板可用。 **预期结果：** 登录成功后会出现一份 **"Learn Claude Code"** 引导清单（毕业帽图标）。每项点 **Show me** 跟着走一遍基础操作即可。嫌烦可点 X 关闭，之后在 VS Code 设置的 `Extensions → Claude Code → Hide Onboarding` 处取消勾选即可重新调出。 **常见问题：** - **明明在 shell 里设了 `ANTHROPIC_API_KEY`，却仍弹登录？** VS Code 可能没继承你的 shell 环境。解决办法：从终端用 `code .` 启动 VS Code 让它继承环境变量；或干脆用 Claude 账号登录（推荐，省心）。 - **用 Bedrock / Vertex AI / Microsoft Foundry？** 这是企业场景。勾选 `Disable Login Prompt` 设置后，按对应 provider 指南在 `~/.claude/settings.json` 里配置——该文件在扩展和 CLI 间共享。 --- ## 第四步：认识交互界面 打开面板后，输入框是核心战场。它底部和四周藏着几个关键控件： **1. 权限模式指示器（输入框底部）** 点击可在三种模式间切换，这直接决定 Claude 行动的"刹车"力度： | 模式 | 行为 | 适用场景 | |------|------|----------| | Normal（默认） | 每个动作前征求许可 | 新手首跑，最安全 | | Plan（计划模式） | 只描述要做的事，等你批准再动手 | 复杂改造，先看方案 | | Auto-accept（自动接受） | 不询问直接改 | 信任度高的小修小补 | 你可以在设置 `claudeCode.initialPermissionMode` 里指定新会话的默认模式。 **2. 命令菜单 `/`** 输入 `/` 弹出命令菜单：附加文件、切换模型、开关扩展思考、查看用量（`/usage`）、启动 Remote Control（`/remote-control`）。其中 **Customize** 分区聚合了 MCP 服务器、Hooks、Memory、权限、插件入口。 **3. 上下文指示器** 输入框会显示当前占用了多少上下文窗口。快满时 Claude 会自动压缩（compact），你也可以手动 `/compact`。 **4. 扩展思考（Extended Thinking）** 通过命令菜单开关。开启后 Claude 会花更多时间推理复杂问题，思考过程以**折叠块**形式出现在对话里——点开可读，或按 `Ctrl+O` 展开/收起所有思考块。 **5. 多行输入** 按 `Shift+Enter` 换行而不发送。 --- ## 第五步：与代码对话——`@`-提及、选区上下文、内联 diff 这是 Claude Code 在编辑器里区别于普通 ChatBot 的"杀手锏"三件套。 ### 选区上下文：选中即看见 **操作：** 在编辑器里用鼠标选中一段代码。此时输入框页脚会显示 **"N lines selected"**——意味着 Claude 已经能"看见"你高亮的内容，无需复制粘贴。 按 `Option+K`（Mac）/ `Alt+K`（Win/Linux）可直接把当前选区插入为带行号的引用，例如 `@app.ts#5-10`。点选区指示器可切换是否把选区发给 Claude（眼睛斜杠图标=对 Claude 隐藏）。 **安全提示：** 若选中的是 `.env` 等敏感文件，可在权限里加一条 `Read` 拒绝规则，匹配该路径后，**选区文本和"已打开文件"提示都不会发到 Claude**。 ### `@`-提及：精准指路 `@` 后跟文件/文件夹名即可把对应内容喂给 Claude，支持**模糊匹配**： ```text > 解释 @auth 里的逻辑 （模糊匹配 auth.js、AuthService.ts 等） > @src/components/ 里有什么 （文件夹要带结尾斜杠） ``` 对于大 PDF，可指定页码：单页、区间（1-10）、开放区间（page 3 onward）。 **拖拽附件：** 按住 `Shift` 把文件拖进输入框即可作为附件；点附件上的 X 可移除。 ### 内联 diff：可视化审查 **操作：** 当 Claude 要改文件时，会弹出**左右并排的对比视图**（原始 vs 提议），然后请求许可。你可以： - **Accept** 接受； - **Reject** 拒绝； - 或直接在 diff 视图里改提议内容再接受——Claude 会被通知"你改过了"，从而**不会**假设文件和它原方案一致。 这种"先看再批"的机制，配合 Plan 模式（方案在 VS Code 里展开成完整 Markdown 文档，可逐行加评论反馈），把 AI 改代码的失控风险降到了最低。 --- ## 第六步：实战案例——修复一个带 Bug 的小项目 现在把前面所有知识串起来，完成一个可运行的端到端任务。 ### 场景 一个极简的 Node.js 折扣计算器，逻辑有 Bug：满 100 元打 8 折，但代码把所有订单都按 8 折算了。 **项目结构：** ``` shop-calc/ ├── package.json └── calc.js ``` **`package.json`：** ```json { "name": "shop-calc", "version": "1.0.0", "type": "module", "scripts": { "start": "node calc.js" } } ``` **`calc.js`（带 Bug）：** ```javascript // 折扣规则：满 100 元才打 8 折 export function finalPrice(price) { const discounted = price * 0.8; // Bug：未判断是否满 100 return Math.round(discounted * 100) / 100; } console.log("80元实付:", finalPrice(80)); // 期望 80，实际 64 console.log("150元实付:", finalPrice(150)); // 期望 120，实际 120 ``` ### 你的操作链路（全程在 VS Code 内完成） **① 用选区让 Claude 看懂现状** 在编辑器里**选中** `finalPrice` 整个函数（输入框页脚出现 "6 lines selected"），然后在面板输入： ```text 这段函数的折扣逻辑和注释不一致，帮我定位问题并说明原因。 ``` **预期结果：** Claude 指出"代码对所有价格都乘 0.8，缺少 `>= 100` 的判断"，并给出修复思路。 **② 让它动手修，走内联 diff** 接着输入： ```text 请修复，保证只有满 100 元才打 8 折，并补一个边界测试用例。 ``` **预期结果：** 弹出左右并排 diff： ```javascript - const discounted = price * 0.8; + const discounted = price >= 100 ? price * 0.8 : price; ``` 底部还会追加测试输出。**Accept** 接受改动。 **③ 用 `@`-提及 + 终端输出做验证** 在集成终端（`` Ctrl+` ``）运行： ```bash npm start ``` 预期输出变成： ```text 80元实付: 80 150元实付: 120 ``` 现在用 `@terminal` 引用这个输出，让 Claude 确认： ```text 看 @terminal:name 的输出，确认折扣逻辑已正确。 ``` > `@terminal:name` 中的 `name` 是终端标题。这让 Claude 直接读到命令输出，免复制粘贴。 **④ 用 Git 收尾** ```text 帮我把这次的修复提交，写一句清晰的 commit message。 ``` **预期结果：** Claude 自动 `git add`、写好 commit message 并提交。也可让它"基于改动创建一个 PR"。 **⑤ 万一改坏了？用 Checkpoint 回退** 把鼠标悬停在对话中任一条消息上，会出现**回退按钮**，三个选项： - **Fork conversation from here**：保留代码改动，从此处分叉新对话； - **Rewind code to here**：代码回退到该点，但对话历史保留； - **Fork conversation and rewind code**：分叉并回退代码。 这让"AI 改崩了"不再可怕——任何一步都能撤。 --- ## 工作流全景图 ```mermaid flowchart TD Start([打开一个文件]) --> Spark[点 Spark 图标开面板] Spark --> Login{已登录?} Login -->|否| OAuth[浏览器 OAuth 授权] OAuth --> Work Login -->|是| Work[选 Normal/Plan 模式] Work --> Select[编辑器选中目标代码
或用 @ 指定文件] Select --> Ask[描述需求] Ask --> Think{开启扩展思考?} Think -->|是| Reason[Claude 深度推理] Think -->|否| Direct[Claude 直接响应] Reason --> Diff Direct --> Diff[弹出左右并排 diff] Diff --> Review{审查} Review -->|直接接受| Apply[写入文件] Review -->|手动改后接受| Apply Review -->|拒绝/重新提需求| Ask Apply --> Run[集成终端运行验证] Run --> OK{结果正确?} OK -->|否| Rewind[Checkpoint 回退] Rewind --> Ask OK -->|是| Commit[Git 提交 / 建 PR] Commit --> Done([完成]) style Apply fill:#e6f4ea,stroke:#34a853 style Rewind fill:#fef7e0,stroke:#f9ab00 style Done fill:#e8f0fe,stroke:#4285f4 ``` --- ## 进阶配置速览 ### 多会话并行 命令面板里 **Open in New Tab** 或 **Open in New Window** 可开多个独立对话（各自独立上下文）。Tab 上的 Spark 图标小圆点表示状态：**蓝色**=有待处理的权限请求，**橙色**=你切走时 Claude 已完成。 ### 面板位置随心拖拽 抓住面板标签拖到**次侧边栏**（右侧，编码时始终可见）、**主侧边栏**（左侧）、或**编辑区**（作为 Tab 与文件并列）。Claude 会记住你的偏好。 ### 关键扩展设置 打开设置（`Cmd+,` / `Ctrl+,` → Extensions → Claude Code）： | 设置 | 默认 | 作用 | |------|------|------| | `useTerminal` | `false` | 改用终端式界面而非图形面板 | | `initialPermissionMode` | `default` | 新会话默认权限模式 | | `preferredLocation` | `panel` | 面板开在 `panel`（新 Tab）还是 `sidebar`（右侧） | | `autosave` | `true` | Claude 读写前自动保存文件 | | `useCtrlEnterToSend` | `false` | 用 Ctrl/Cmd+Enter 发送而非回车 | | `respectGitIgnore` | `true` | 文件搜索排除 .gitignore 模式 | ### 让 settings.json 带自动补全 在 `~/.claude/settings.json` 顶部加一行，VS Code 会给你所有可用设置的自动补全与内联校验： ```json { "$schema": "https://json.schemastore.org/claude-code-settings.json" } ``` ### Chrome Connect：让 Claude 操控浏览器 装上 [Claude in Chrome 扩展](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn)（1.0.36+）后，输入 `@browser` 即可让 Claude 打开 `localhost:3000` 查控制台报错、测 Web 应用——共享你的登录态，能访问任何你已登录的站点。 ```text @browser 打开 localhost:3000 并检查控制台有没有报错 ``` ### 从外部工具唤起 VS Code 标签页 扩展注册了 URI 处理器 `vscode://anthropic.claude-code/open`，支持 `prompt`（预填文本）和 `session`（恢复会话）两个参数。可做成 shell alias 或书签： ```bash open "vscode://anthropic.claude-code/open?prompt=review%20my%20changes" ``` --- ## 常见问题排查 **Q1：装了扩展，集成终端里却提示 `claude: command not found`？** A：扩展内置的 CLI **仅供聊天面板使用，不加入 PATH**。想在终端跑 `claude`（用 `!` bash、Tab 补全、全量斜杠命令），需单独安装独立 CLI。装一次后，`claude mcp add`、`claude --resume` 等命令在任何终端都可用。 **Q2：在 macOS Tahoe 上 `Cmd+Esc` 没反应？** A：Tahaco 默认把 `Cmd+Esc` 绑给了系统"游戏覆盖层"。去 系统设置 → 键盘 → 键盘快捷键 → 游戏控制器，取消"Game Overlay"勾选；或在 VS Code 键盘快捷键编辑器里给 `Claude Code: Focus input` 重绑一个键。 **Q3：外部终端开的 Claude，怎么连上 VS Code 的 diff 视图？** A：在外部终端的 Claude 会话里输入 `/ide`，即可连接到当前 VS Code，激活 diff 查看、选区共享、诊断共享等所有 IDE 集成特性。 **Q4：Claude 完全不响应？** A：①检查网络；②开个新对话试试；③切到集成终端跑 `claude` 看更详细的错误。仍不行就去 [GitHub Issues](https://github.com/anthropics/claude-code/issues) 提交。 **Q5：代码会被拿去训练吗？** A：不会。Claude Code 处理你的代码以提供服务，但不用于模型训练。对不可信代码，建议开启 VS Code 的 Restricted Mode 并用手动审批而非 auto-accept。 **Q6：用 JetBrains 系（IntelliJ/PyCharm/WebStorm）怎么办？** A：从 [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) 装"Claude Code"插件并重启 IDE。**关键差异**：JetBrains 插件**不内置 CLI**，必须先装好 `claude` 并在 PATH 里，否则会报 "Cannot launch Claude Code"。配置在 `Settings → Tools → Claude Code [Beta]`，其中 **Claude command** 可填自定义路径（WSL 用户填 `wsl -d Ubuntu -- bash -lic "claude"`）。 --- ## 训练营适用性评估 | 维度 | 评估 | |------|------| | **适合的训练营类型** | 全栈/Web 开发入门营、企业内部"AI 辅助研发"普及营、转岗工程师 AI 工具训练营。强调"所见即所得"的可视化体验，对命令行基础零要求 | | **学员基础** | 会用 VS Code 即可，完全零基础友好；不要求 Node.js 或 Git 熟练 | | **预计教学时长** | 约 **2.5–3 小时**：安装登录 30 min、界面与三件套讲解 60 min、实战案例 60 min、进阶配置与答疑 30 min | | **延伸练习建议** | 让学员各自带来一个自己的小项目，复用"选区→修复→diff 审查→终端验证→提交"链路；或引入 `/usage` 观察自己的用量构成 | | **硬件/网络要求** | 需稳定外网访问 Anthropic 服务；macOS Tahoe 学员需提前处理快捷键冲突 | --- ## 延伸阅读 - **Common Workflows**（官方）：超出本教程的进阶工作流——`code.claude.com/docs/en/common-workflows` - **权限模式详解**：Normal / Plan / acceptEdits / bypassPermissions 的取舍——`code.claude.com/docs/en/permission-modes` - **Checkpointing**：回退机制的完整能力与限制——`code.claude.com/docs/en/checkpointing` - **Settings 参考**：`~/.claude/settings.json` 全部可用项——`code.claude.com/docs/en/settings` - **Headless 与 Deep Links**：用 `claude-cli://` 和 URI 处理器做自动化——`code.claude.com/docs/en/deep-links` --- ## 参考来源 1. [Use Claude Code in VS Code — Claude Code 官方文档](https://code.claude.com/docs/en/vs-code) — 本文核心依据：扩展安装、Spark 面板、权限模式、`@`-提及、内联 diff、Checkpoint、IDE MCP 服务器、设置项与排查全流程 2. [JetBrains IDEs — Claude Code 官方文档](https://code.claude.com/docs/en/jetbrains) — 对照说明 IntelliJ/PyCharm/WebStorm 插件的安装、`/ide` 连接、`Claude command` 配置与 WSL2 排错 3. [Claude Code in VS Code: Complete Setup Guide 2026 — explainx.ai](https://www.explainx.ai/blog/claude-code-vscode-ide-extension-setup-guide-2026) — 第三方实战补充：inline diff、LSP 诊断、文件导航等具体操作截图说明 4. [How to Integrate Claude Code with VSCode and JetBrains? — apidog.com](https://apidog.com/blog/claude-code-ide-integrations/) — 面向初学者的分步集成指引与常见踩坑梳理 5. [Claude Code: IDE Integration with VS Code and JetBrains — letanure.dev](https://www.letanure.dev/blog/2025-08-05--claude-code-part-7-ide-integration-vscode-jetbrains) — 消除"IDE 与终端来回切换"的工程实践视角 > [!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 等场景全覆盖。