在 VS Code 中使用 Claude Code

安装并配置 VS Code 的 Claude Code 扩展。获取 AI 编码辅助，包括内联差异、@-提及、计划审查和键盘快捷键。

VS Code 扩展为 Claude Code 提供了原生图形界面，直接集成到你的 IDE 中。这是在 VS Code 中使用 Claude Code 的推荐方式。

通过该扩展，你可以在接受 Claude 的计划之前进行审查和编辑，在编辑时自动接受更改，从你的选区 @-提及特定行范围的文件，访问对话历史记录，并在独立的标签页或窗口中打开多个对话。

先决条件

安装前，请确保你具备：

• VS Code 1.98.0 或更高版本
• Anthropic 账户：任何付费 Claude 订阅（Pro、Max、Team 或 Enterprise）或 Claude Console 账户均可，无需 API 密钥。首次打开扩展时，你将使用此账户登录。如果你通过 Amazon Bedrock 或 Google Cloud 的 Agent Platform 等第三方提供商访问 Claude，请参阅使用第三方提供商了解设置说明。

安装扩展

点击对应 IDE 的链接直接安装：

• 为 VS Code 安装
• 为 Cursor 安装

或在 VS Code 中，按 Cmd+Shift+X（Mac）或 Ctrl+Shift+X（Windows/Linux）打开扩展视图，搜索"Claude Code"，然后点击安装。

该扩展也可安装在其他 VS Code 分支中，如 Devin Desktop 或 Kiro。在编辑器的扩展视图中搜索"Claude Code"，或从 Open VSX 注册表安装。如果你的编辑器无法安装该扩展，请安装 CLI并在其集成终端中运行 claude。CLI 可在任何终端中工作。

开始使用

安装后，你可以通过 VS Code 界面开始使用 Claude Code：

1

打开 Claude Code 面板

在 VS Code 中，Spark 图标表示 Claude Code：

打开 Claude 最快的方式是点击编辑器工具栏（编辑器右上角）中的 Spark 图标。该图标仅在你打开文件时显示。

其他打开 Claude Code 的方式：

• 活动栏：点击左侧边栏中的 Spark 图标打开会话列表。点击任意会话将其作为完整编辑器标签页打开，或开始新会话。此图标在活动栏中始终可见。
• 命令面板：Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows/Linux），输入"Claude Code"，然后选择"Open in New Tab"等选项
• 状态栏：点击窗口右下角的 ✱ Claude Code。即使未打开文件也能使用。

你可以拖动 Claude 面板将其重新定位到 VS Code 中的任何位置。详情请参阅自定义你的工作流。

2

登录

首次打开面板时，会出现登录界面。点击登录并在浏览器中完成授权。

如果之后看到 Not logged in · Please run /login，扩展会自动重新打开登录界面。如果未出现，请从命令面板使用 Developer: Reload Window 重新加载窗口。

如果你在 shell 中设置了 ANTHROPIC_API_KEY 但仍看到登录提示，VS Code 可能未继承你的 shell 环境。从终端使用 code . 启动 VS Code，使其继承环境变量，或者改用你的 Claude 账户登录。

登录后，会出现学习 Claude Code清单。点击Show me逐项完成，或使用 X 关闭。要稍后重新打开，请在 VS Code 设置中 Extensions → Claude Code 下取消勾选 Hide Onboarding。

3

发送提示

请 Claude 帮助处理你的代码或文件，无论是解释工作原理、调试问题还是进行更改。

Claude 会自动看到你的选中文本。按 Option+K（Mac）/ Alt+K（Windows/Linux）还可将 @-提及引用（如 @file.ts#5-10）插入到你的提示中。

以下是一个询问文件中特定行的示例：

4

审查更改

当 Claude 想要编辑文件时，它会显示原始版本和建议更改的并排对比，然后请求权限。你可以接受、拒绝或告诉 Claude 该怎么做。如果你在接受前直接在差异视图中编辑建议内容，Claude 会被告知你修改了它，因此不会假设文件与其原始建议一致。

有关使用 Claude Code 的更多想法，请参阅常见工作流。

使用提示框

提示框支持多种功能：

• 权限模式：点击提示框底部的模式指示器切换模式，或在 VS Code 设置中设置默认值 claudeCode.initialPermissionMode。有关指示器提供的每种模式，请参阅权限模式。
  • Manual：Claude 在每次操作前都会请求权限。
  • Plan：Claude 描述将要执行的操作，并在进行更改前等待批准。VS Code 会自动将计划作为完整 Markdown 文档打开，你可以添加内联评论以在 Claude 开始前提供反馈。
  • Edit automatically：Claude 无需询问即可进行编辑。
• 命令菜单：点击 / 或输入 / 打开命令菜单。选项包括附加文件、切换模型、开启扩展思考、查看计划使用情况（/usage）以及启动 Remote Control 会话（/remote-control）。Customize 部分提供对 MCP 服务器、hooks、memory、permissions 和 plugins 的访问。带有终端图标的项目会在集成终端中打开。
  • Settings 部分包括 Enable Remote Control for all sessions，它会设置 remoteControlAtStartup，使每个新的交互式会话自动连接 Remote Control。需要 Claude Code v2.1.203 或更高版本。
• 上下文指示器：提示框显示你使用了 Claude 上下文窗口的多少。Claude 会在需要时自动压缩，或者你可以手动运行 /compact。
• 扩展思考：让 Claude 在复杂问题上花费更多时间进行推理。通过命令菜单（/）切换。Claude 的推理过程会以折叠块的形式显示在对话中：点击块可阅读，或按 Ctrl+O 展开或折叠会话中的所有思考块。详情请参阅扩展思考。
• 多行输入：按 Shift+Enter 添加新行而不发送。这在问题对话框的"Other"自由文本输入中同样适用。

引用文件和文件夹

使用 @-提及为 Claude 提供特定文件或文件夹的上下文。当你输入 @ 后跟文件或文件夹名称时，Claude 会读取该内容，并可以回答相关问题或对其进行更改。Claude Code 支持模糊匹配，因此你可以输入部分名称来查找所需内容：

> Explain the logic in @auth (fuzzy matches auth.js, AuthService.ts, etc.)
> What's in @src/components/ (include a trailing slash for folders)

对于大型 PDF，你可以要求 Claude 读取特定页面而非整个文件：单页、1-10 页等范围，或从第 3 页开始的开放式范围。

当你在编辑器中选中文本时，Claude 可以自动看到你高亮的代码。提示框底部显示选中了多少行。按 Option+K（Mac）/ Alt+K（Windows/Linux）插入带文件路径和行号的 @-提及（例如 @app.ts#5-10）。点击选区指示器可切换 Claude 是否能看到你的高亮文本——眼睛带斜杠图标表示该选区对 Claude 隐藏。

你还可以在将文件拖入提示框时按住 Shift 将其添加为附件。点击附件上的 X 可将其从上下文中移除。

恢复过往对话

点击 Claude Code 面板顶部的 Session history 按钮访问你的对话历史。你可以按关键词搜索或按时间浏览（今天、昨天、最近 7 天等）。点击任意对话即可恢复，并保留完整的消息历史。新会话会根据你的第一条消息自动生成 AI 标题。悬停会话可显示重命名和删除操作：重命名可为其添加描述性标题，删除可将其从列表中移除。有关恢复会话的更多内容，请参阅管理会话。

从 Claude.ai 恢复云端会话

如果你使用 Claude Code 网页版，可以直接在 VS Code 中恢复这些云端会话。这需要使用 Claude.ai Subscription 登录，而非 Anthropic Console。

查看账户和使用情况

从命令菜单运行 /usage 打开 Account & usage 对话框。它显示你已登录的账户、套餐，以及当前会话和本周的使用量进度条，并显示每个限制的重置时间。

该对话框还会详细说明哪些行为占用了你的套餐限制。它会标记占最近使用量 10% 或以上的行为，例如缓存未命中、长上下文、大量使用子代理或高度并行的会话，每种行为都附有减少使用量的提示。归因表显示每个 skill、subagent、plugin 和 MCP 服务器产生的使用量。需要 Claude Code v2.1.174 或更高版本。

使用 Day 和 Week 切换按钮可在最近 24 小时和最近 7 天之间切换。这些数字是近似值，根据本机上的本地会话计算，因此不包括其他设备或 claude.ai 上的使用量。有关跟踪和减少使用量的更多信息，请参阅跟踪你的成本。

自定义你的工作流

启动并运行后，你可以重新定位 Claude 面板、运行多个会话或切换到终端模式。

选择 Claude 的位置

你可以拖动 Claude 面板将其重新定位到 VS Code 中的任何位置。抓住面板的标签页或标题栏，将其拖动到：

• Secondary sidebar：窗口右侧。在编码时保持 Claude 可见。
• Primary sidebar：左侧边栏，包含 Explorer、Search 等图标。
• Editor area：作为标签页与你的文件并排打开 Claude。适用于次要任务。

运行多个对话

使用命令面板中的 Open in New Tab 或 Open in New Window 启动额外对话。每个对话都维护自己的历史和上下文，允许你并行处理不同任务。

使用标签页时，Spark 图标上的小色点表示状态：蓝色表示有待处理的权限请求，橙色表示 Claude 在标签页隐藏时已完成。

切换到终端模式

默认情况下，扩展会打开图形聊天面板。如果你更喜欢 CLI 风格界面，请打开 Use Terminal 设置 并勾选该框。

你也可以打开 VS Code 设置（Mac 上 Cmd+, 或 Windows/Linux 上 Ctrl+,），前往 Extensions → Claude Code，然后勾选 Use Terminal。

管理插件

VS Code 扩展包含用于安装和管理 plugins 的图形界面。在提示框中输入 /plugins 打开 Manage plugins 界面。

安装插件

插件对话框显示两个标签页：Plugins 和 Marketplaces。

在 Plugins 标签页中：

• 已安装插件显示在顶部，带有切换开关可启用或禁用
• 来自你配置的市场的可用插件显示在下方
• 搜索可按名称或描述筛选插件
• 点击任意可用插件的 Install

安装插件时，选择安装范围：

• Install for you：在你所有项目中可用（用户范围）
• Install for this project：与项目协作者共享（项目范围）
• Install locally：仅为你自己，仅在此仓库中（本地范围）

管理市场

切换到 Marketplaces 标签页以添加或移除插件源：

• 输入 GitHub 仓库、URL 或本地路径以添加新市场
• 点击刷新图标以更新市场的插件列表
• 点击垃圾桶图标以移除市场

进行更改后，横幅会提示你重启 Claude Code 以应用更新。

有关插件系统的更多信息，请参阅 Plugins 和 Plugin marketplaces。

使用 Chrome 自动化浏览器任务

将 Claude 连接到你的 Chrome 浏览器，以测试 Web 应用、使用控制台日志调试，并在不离开 VS Code 的情况下自动化浏览器工作流。这需要 Claude in Chrome 扩展 1.0.36 或更高版本。

在提示框中输入 @browser，后跟你要 Claude 执行的操作：

@browser go to localhost:3000 and check the console for errors

你也可以打开附件菜单以选择特定的浏览器工具，如打开新标签页或读取页面内容。

Claude 会为浏览器任务打开新标签页并共享你的浏览器登录状态，因此它可以访问你已登录的任何网站。

有关设置说明、完整功能列表和故障排除，请参阅将 Claude Code 与 Chrome 配合使用。

VS Code 命令和快捷键

打开命令面板（Mac 上 Cmd+Shift+P 或 Windows/Linux 上 Ctrl+Shift+P）并输入"Claude Code"以查看 Claude Code 扩展的所有可用 VS Code 命令。

某些快捷键取决于哪个面板处于"聚焦"状态（接收键盘输入）。当光标在代码文件中时，编辑器处于聚焦状态。当光标在 Claude 的提示框中时，Claude 处于聚焦状态。使用 Cmd+Esc / Ctrl+Esc 在两者之间切换。

从其他工具启动 VS Code 标签页

扩展在 vscode://anthropic.claude-code/open 注册了一个 URI 处理程序。使用它从你的工具中打开新的 Claude Code 标签页：shell 别名、浏览器书签或任何可以打开 URL 的脚本。如果 VS Code 尚未运行，打开 URL 会先启动它。如果 VS Code 已在运行，URL 会在当前聚焦的窗口中打开。

使用操作系统的 URL 打开器调用该处理程序。

open "vscode://anthropic.claude-code/open"

xdg-open "vscode://anthropic.claude-code/open"

Start-Process "vscode://anthropic.claude-code/open"

start "" "vscode://anthropic.claude-code/open"

该处理程序接受两个可选查询参数：

例如，要打开一个预填充"review my changes"的标签页：

vscode://anthropic.claude-code/open?prompt=review%20my%20changes

要启动终端会话而非 VS Code 标签页，请使用 CLI 的 claude-cli:// 处理程序。请参阅从链接启动会话。

配置设置

扩展有两种设置：

• VS Code 中的扩展设置：控制扩展在 VS Code 中的行为。使用 Cmd+,（Mac）或 Ctrl+,（Windows/Linux）打开，然后前往 Extensions → Claude Code。你也可以输入 / 并选择 General Config 打开设置。
• ~/.claude/settings.json 中的 Claude Code 设置：在扩展和 CLI 之间共享。用于允许的命令、环境变量、hooks 和 MCP 服务器。详情请参阅 Settings。

扩展设置

VS Code 扩展与 Claude Code CLI 的区别

Claude Code 既可作为 VS Code 扩展（图形面板）也可作为 CLI（终端中的命令行界面）使用。某些功能仅在 CLI 中可用。如果你需要 CLI 专属功能，请在 VS Code 的集成终端中运行 claude。这需要独立 CLI 安装：扩展不会将 claude 添加到你的 PATH。有关详情，请参阅在 VS Code 中运行 CLI。

使用 Checkpoints 回退

VS Code 扩展支持 checkpoints，可跟踪 Claude 的文件编辑并让你回退到之前的状态。悬停任意消息可显示回退按钮，然后选择三个选项之一：

• Fork conversation from here：从此消息开始新的对话分支，同时保留所有代码更改
• Rewind code to here：将文件更改回退到对话中的此点，同时保留完整对话历史
• Fork conversation and rewind code：开始新的对话分支并将文件更改回退到此处

有关 checkpoints 的工作原理及其限制的完整详情，请参阅 Checkpointing。

在 VS Code 中运行 CLI

要在留在 VS Code 的同时使用 CLI，请打开集成终端（Windows/Linux 上 Ctrl+` 或 Mac 上 Cmd+`）并运行 claude。CLI 会自动与你的 IDE 集成，以实现差异查看和诊断共享等功能。

安装扩展不会将 claude 添加到你的 shell PATH。扩展为其聊天面板捆绑了一个私有的 CLI 副本，但在终端中输入 claude 需要独立 CLI 安装。运行一次安装后，本页的所有命令（包括 claude mcp add 和 claude --resume）都可在任何终端中使用。如果安装后仍找不到 claude，请验证你的 PATH。

如果使用外部终端，请在 Claude Code 中运行 /ide 将其连接到 VS Code。

在扩展和 CLI 之间切换

扩展和 CLI 共享相同的对话历史。要在 CLI 中继续扩展中的对话，请在终端中运行 claude --resume。这会打开一个交互式选择器，你可以搜索并选择你的对话。

在提示中包含终端输出

使用 @terminal:name 在提示中引用终端输出，其中 name 是终端的标题。这让 Claude 无需复制粘贴即可看到命令输出、错误消息或日志。

监控后台进程

当 Claude 运行长时间命令时，扩展会在状态栏中显示进度。然而，与 CLI 相比，后台任务的可见性有限。如需更好的可见性，请让 Claude 输出命令，以便你可以在 VS Code 的集成终端中运行它。

通过 MCP 连接外部工具

MCP（Model Context Protocol）服务器让 Claude 访问外部工具、数据库和 API。

要添加 MCP 服务器，请打开集成终端（Ctrl+` 或 Cmd+`）并运行 claude mcp add。以下示例添加了 GitHub 的远程 MCP 服务器，它使用作为 header 传递的 personal access token 进行认证：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

配置完成后，请 Claude 使用这些工具（例如"Review PR #456"）。

要在不离开 VS Code 的情况下管理 MCP 服务器，请在聊天面板中输入 /mcp。MCP 管理对话框可让你启用或禁用服务器、重新连接服务器以及管理 OAuth 认证。请参阅 MCP 文档 了解可用服务器。

使用 git

Claude Code 与 git 集成，可直接在 VS Code 中帮助处理版本控制工作流。让 Claude 提交更改、创建拉取请求或跨分支工作。

创建提交和拉取请求

Claude 可以暂存更改、编写提交消息，并根据你的工作创建拉取请求：

> commit my changes with a descriptive message
> create a pr for this feature
> summarize the changes I've made to the auth module

创建拉取请求时，Claude 会根据实际代码更改生成描述，并可添加有关测试或实现决策的上下文。

使用 git worktrees 进行并行任务

使用 --worktree（-w）标志在独立的 worktree 中启动 Claude，拥有自己的文件和分支：

claude --worktree feature-auth

每个 worktree 在共享 git 历史的同时保持独立的文件状态。这可以防止 Claude 实例在处理不同任务时相互干扰。有关更多详情，请参阅使用 Git worktrees 运行并行会话。

使用第三方提供商

默认情况下，Claude Code 直接连接到 Anthropic 的 API。如果你的组织使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 访问 Claude，请将扩展配置为改用你的提供商：

安全与隐私

你的代码保持私密。Claude Code 会处理你的代码以提供帮助，但不会将其用于训练模型。有关数据处理的详情以及如何退出日志记录，请参阅数据与隐私。

启用自动编辑权限后，Claude Code 可以修改 VS Code 可能自动执行的配置文件（如 settings.json 或 tasks.json）。为降低处理不受信任代码时的风险：

• 为不受信任的工作区启用 VS Code Restricted Mode
• 对编辑使用手动批准模式而非自动接受
• 在接受前仔细审查更改

内置 IDE MCP 服务器

当扩展处于活动状态时，它会运行一个本地 MCP 服务器，CLI 会自动连接。这就是 CLI 如何在 VS Code 的原生差异查看器中打开差异、读取你的当前选区以进行 @-提及，以及——当你在 Jupyter 笔记本中工作时——请求 VS Code 执行单元格。

该服务器名为 ide，在 /mcp 中隐藏，因为无需配置。但是，如果你的组织使用 PreToolUse hook 来允许 MCP 工具，你需要知道它的存在。

选区和打开文件上下文。 连接时，CLI 会将你当前的编辑器选区和活动文件的路径作为每次发送的提示的上下文。当这种情况发生时，transcript 会显示 ⧉ Selected N lines from <file> 行。要排除敏感文件（如 .env），请为其路径添加 Read 拒绝规则。匹配的拒绝规则会阻止该文件的选中文本和打开文件通知到达 Claude。

传输和认证。 服务器绑定到 127.0.0.1 的随机高端口，其他机器无法访问。每次扩展激活都会生成一个新鲜的随机认证令牌，CLI 必须出示该令牌才能连接。令牌以 0600 权限写入 ~/.claude/ide/ 下的锁文件，目录权限为 0700，因此只有运行 VS Code 的用户才能读取它。

暴露给模型的工具。 服务器托管十几个工具，但只有两个对模型可见。其余是 CLI 用于自身 UI 的内部 RPC——打开差异、读取选区、保存文件——在工具列表到达 Claude 之前被过滤掉。

Jupyter 执行始终先询问。 mcp__ide__executeCode 无法静默运行任何内容。每次调用时，代码会作为新单元格插入活动笔记本的末尾，VS Code 将其滚动到视图中，然后原生 Quick Pick 会要求你选择 Execute 或 Cancel。取消——或用 Esc 关闭选择器——会向 Claude 返回错误且不会运行任何内容。当没有活动笔记本、未安装 Jupyter 扩展（ms-toolsai.jupyter）或内核不是 Python 时，该工具也会直接拒绝。

修复常见问题

扩展无法安装

• 确保你拥有兼容的 VS Code 版本（1.98.0 或更高）
• 检查 VS Code 是否有安装扩展的权限
• 尝试直接从 VS Code Marketplace 安装

Spark 图标不可见

Spark 图标在你打开文件时出现在编辑器工具栏（编辑器右上角）中。如果你看不到它：

1. 打开文件：该图标需要打开文件。仅打开文件夹是不够的。
2. 检查 VS Code 版本：需要 1.98.0 或更高版本（Help → About）
3. 重启 VS Code：从命令面板运行"Developer: Reload Window"
4. 禁用冲突扩展：暂时禁用其他 AI 扩展（Cline、Continue 等）
5. 检查工作区信任：该扩展在 Restricted Mode 中无法工作

或者，点击状态栏（右下角）中的"✱ Claude Code"。即使没有打开文件也能使用。你也可以使用命令面板（Cmd+Shift+P / Ctrl+Shift+P）并输入"Claude Code"。

macOS 上 Cmd+Esc 无响应

在 macOS Tahoe 及更高版本上，系统 Game Overlay 快捷键默认绑定到 Cmd+Esc，会在按键到达 VS Code 之前拦截它。要释放该快捷键：

1. 打开系统设置
2. 前往 Keyboard，然后 Keyboard Shortcuts，然后 Game Controllers
3. 清除 Game Overlay 复选框

或者，将扩展重新绑定到其他键：打开 VS Code Keyboard Shortcuts editor（Cmd+K Cmd+S），搜索 Claude Code: Focus input，然后分配新的绑定。

Claude Code 无响应

如果 Claude Code 没有响应你的提示：

1. 检查你的网络连接：确保你有稳定的互联网连接
2. 开始新对话：尝试开始新对话以查看问题是否持续
3. 尝试 CLI：从终端运行 claude 以查看是否获得更详细的错误消息

如果问题持续，请在 GitHub 上提交 issue 并提供错误详情。

卸载扩展

要卸载 Claude Code 扩展：

1. 打开扩展视图（Mac 上 Cmd+Shift+X 或 Windows/Linux 上 Ctrl+Shift+X）
2. 搜索"Claude Code"
3. 点击卸载

在 VS Code 集成终端中运行 claude 会自动重新安装扩展。要保持卸载状态，请在 /config 中关闭 Auto-install IDE extension，或将 autoInstallIdeExtension 设置为 false。你也可以将 CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL 环境变量设置为 1。

要同时删除扩展数据并重置所有设置，请删除你平台的扩展存储目录。

在 macOS 上：

rm -rf ~/Library/"Application Support"/Code/User/globalStorage/anthropic.claude-code

在 Linux 上：

rm -rf ~/.config/Code/User/globalStorage/anthropic.claude-code

在 Windows 上，使用 PowerShell：

Remove-Item -Recurse -Force "$env:APPDATA\Code\User\globalStorage\anthropic.claude-code"

如需额外帮助，请参阅故障排除指南。

下一步

现在 Claude Code 已在 VS Code 中设置完成：

• 探索常见工作流 以充分利用 Claude Code
• 设置 MCP 服务器 以通过外部工具扩展 Claude 的能力。使用 CLI 添加服务器，然后在聊天面板中使用 /mcp 管理它们。
• 配置 Claude Code 设置 以自定义允许的命令、hooks 等。这些设置在扩展和 CLI 之间共享。