这是一篇面向开发者的 Claude Code VS Code 插件教程，完整讲清安装条件、扩展市场安装、首次登录、@ 文件引用、Inline Diff 审核、Plan Mode、权限确认、CLI 差异和常见问题排查。
摘要：VS Code 插件适合想在编辑器里直接审查 AI 改动的人
Claude Code 最早给很多人的印象是“终端里的 AI 编程助手”，但现在它也可以通过官方 VS Code 扩展进入编辑器界面。对不想频繁在终端、浏览器和编辑器之间切换的用户来说，VS Code 插件的价值很直接：Claude 可以看到当前文件和选中文本，可以用 @ 引用文件或行号，可以在编辑器里展示改动 diff，并且在真正写入文件前要求你确认。
这篇教程会按真实使用顺序讲清楚：安装前要满足什么条件，怎样在 VS Code 扩展市场安装 Claude Code，首次登录时要注意什么，怎样让 Claude 根据当前文件和选区回答问题，怎样审查 Inline Diff，什么时候用 Plan Mode，什么时候切回终端 CLI，以及哪些权限设置不能随便放开。
如果你还没有安装 Claude Code 本体，可以先看站内 Claude Code Mac 安装教程：终端、权限、项目目录完整设置 或 Claude Code Windows 安装教程：WSL、Git Bash、Node 环境完整配置。如果想从整体工作流理解 Claude Code，可以继续阅读 Claude Code 从入门到实战：一篇文章讲清安装、提示词和项目开发。
安装前准备
确认 VS Code 版本
Claude Code 官方 VS Code 文档要求 VS Code 1.98.0 或更高版本。打开 VS Code 后，可以通过菜单里的 About 页面查看版本，也可以在命令行中执行：
code --version如果版本过旧，先升级 VS Code。旧版本可能无法安装扩展，或者安装后看不到 Claude Code 的入口。
确认账号条件
官方文档说明，Claude Code VS Code 扩展首次打开时需要登录 Anthropic 账号。可用账号包括 Claude Pro、Max、Team、Enterprise 等付费 Claude 订阅，或 Claude Console 账号。普通免费 Claude.ai 账号通常不等于 Claude Code 可用权限。
如果你所在组织通过 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 使用 Claude，需要按第三方 provider 文档配置，而不是直接把普通 API Key 填到扩展里。
理解插件和 CLI 的关系
这是很多人最容易混淆的一点：VS Code 扩展会为图形聊天面板捆绑一份 CLI，但这不等于你的终端 PATH 里已经有 claude 命令。也就是说，你可以打开扩展面板聊天，但在 VS Code 集成终端里输入 claude 仍然可能提示 command not found。
如果你需要在终端里运行 claude、使用某些 CLI 专属功能，仍要单独安装 Claude Code CLI。官方文档也明确建议：需要 CLI-only 功能时，在 VS Code 的集成终端中运行独立 CLI。
安装 Claude Code VS Code 插件
方式一：从扩展市场安装
打开 VS Code，按下快捷键进入扩展面板：
Mac: Cmd+Shift+X
Windows / Linux: Ctrl+Shift+X搜索 Claude Code，确认发布方为 Anthropic，然后点击 Install。安装完成后，如果界面没有出现 Claude Code 入口，可以重启 VS Code，或在命令面板运行：
Developer: Reload Window方式二：从 Marketplace 页面安装
也可以打开 Visual Studio Marketplace 的 Claude Code 页面，通过浏览器唤起 VS Code 安装。无论哪种方式，建议只安装官方 anthropic.claude-code 扩展，避免使用名称相似但来源不明的插件。
Cursor、Kiro 等 VS Code Fork 能不能用
官方文档提到，Claude Code 扩展也可在一些 VS Code Fork 中安装，例如 Cursor、Devin Desktop 或 Kiro。实际可用性取决于这些编辑器对 VS Code 扩展 API、登录跳转和命令面板的支持。如果安装失败，可以退回到 Claude Code CLI，在编辑器集成终端中使用。
首次打开：找到 Claude Code 面板并登录
从 Spark 图标打开
安装后，Claude Code 会在 VS Code 中提供 Spark 图标入口。常见入口包括编辑器右上角工具栏、左侧 Activity Bar、状态栏，以及命令面板中的 Claude Code 命令。注意：编辑器右上角的图标通常要在打开文件后才更容易看到。
从命令面板打开
如果找不到图标，按下：
Mac: Cmd+Shift+P
Windows / Linux: Ctrl+Shift+P输入 Claude Code，选择打开面板或新建会话。这个方式适合排查“图标不显示”的情况。
完成登录
首次打开面板时，扩展会显示登录界面。点击 Sign in 后在浏览器中完成授权。登录成功后回到 VS Code，Claude Code 面板会进入可用状态。如果一直显示未登录，可以尝试重新加载窗口，或重新启动 VS Code。
让 AI 直接理解当前文件和选中文本
从当前文件提问
Claude Code 插件的一大优势是，它天然处在编辑器上下文中。你打开某个文件后，可以直接让它解释当前文件、定位函数职责、分析错误原因，或者要求它只读检查某段逻辑。
适合新手的第一条提示词是：
请先只读分析当前文件，不要修改代码。请说明这个文件的职责、主要函数、输入输出，以及你看到的 3 个潜在风险。使用 @ 引用文件和行号
官方文档说明，Claude Code 支持用 @ 引用文件、文件夹或具体行号。你可以选中一段代码，再按快捷键把引用插入 prompt。Mac 是 Option+K，Windows 和 Linux 是 Alt+K。
示例：
请只分析 @src/api/user.ts#20-80 这段逻辑，判断是否有鉴权遗漏。先不要修改代码。让 Claude 先给计划
真正改代码前，不建议直接说“帮我修好”。更稳的写法是让它先输出计划：
请根据当前项目结构，先给出修改计划。说明会改哪些文件、为什么改、可能影响哪些功能、需要运行哪些验证命令。先不要修改文件。
Inline Diff：接受改动前先看清楚
Claude 提出改动时会显示差异
当 Claude Code 准备修改文件时，VS Code 插件会展示原始内容和拟议改动的对比。你可以接受、拒绝，也可以继续要求 Claude 调整方案。这个 diff 审核环节是插件比纯聊天工具更适合写代码的关键原因之一。
不要只看结果，要看影响范围
审查 diff 时至少看四点：是否改了预期文件、是否误删逻辑、是否引入新依赖、是否改动配置或脚本。对于后端、支付、登录、权限、数据库迁移等敏感模块，不要只看 Claude 的解释，要自己检查实际 diff。
可以在 diff 里调整再接受
官方文档提到，如果你在接受前直接编辑拟议 diff，Claude Code 会知道你调整了内容，不会继续假设文件完全等于它原始提案。这适合做小范围措辞、变量名或边界条件修正。
Plan Mode：大改动前先审计划
什么时候用 Plan Mode
如果任务涉及多个文件、重构、迁移、测试策略或架构调整，建议先切到 Plan Mode。Plan Mode 下，Claude 会描述它准备做什么，并等待你确认后再开始改文件。
怎样审查计划
一个合格计划至少要说明：目标、涉及文件、修改步骤、验证命令、潜在风险和回滚方式。如果计划只写“我将修复问题”而没有文件和验证细节，应要求它补全。
请把计划改成可执行清单：列出每个要修改的文件、每个文件的修改点、验证命令、风险和回滚方式。不要在不可信项目里开启过度权限
VS Code 扩展提供不同权限模式。普通模式会在关键操作前询问；自动接受模式会减少确认；危险跳过权限之类的选项只适合隔离沙箱，不适合打开来自陌生来源的项目。
插件工作流：从只读分析到提交前 Review
第一步：只读了解项目
打开项目根目录后，先让 Claude Code 只读分析项目结构：
请只读分析当前工作区，不要修改文件。请输出项目技术栈、入口文件、核心目录、启动命令、测试命令和你建议优先阅读的文件。第二步：明确一个小任务
不要一次要求它“重构整个项目”。更适合的任务粒度是：修一个报错、补一个测试、改一个组件、解释一条调用链、把一个函数抽出来。
第三步：审计划和 diff
让 Claude Code 先给计划，再按计划修改。每次出现 diff，都先看文件范围和逻辑变化。必要时让它解释：
请解释这次 diff 中每个文件为什么需要修改，以及如果不改会有什么问题。第四步：运行验证命令
修改完成后，让 Claude Code 运行项目已有验证命令，例如：
npm test
npm run lint
npm run build具体命令以你的项目为准。可以把这些命令写进项目根目录的 CLAUDE.md，让 Claude Code 每次都遵守。
第五步：提交前让它 Review Diff
提交前可以让 Claude 做一次代码审查：
请 review 当前 git diff，重点检查 bug、遗漏测试、误改配置、密钥泄露、无关重构和破坏兼容性的改动。如果你想了解更多真实场景，可以看站内 Claude Code 最适合做什么？10 个真实开发场景完整演示。
VS Code 插件和 Claude Code CLI 怎么选
插件更适合编辑器内审查
如果你关注当前文件、选区、inline diff、编辑器内确认、对话窗口和代码并排查看，VS Code 插件更顺手。它适合日常开发、修小 bug、解释代码、补测试和做局部重构。
CLI 更适合终端重度工作流
如果你需要完整命令行体验、复杂 shell 操作、某些 CLI-only 功能、外部终端集成或脚本化工作流，CLI 仍然更合适。官方文档也说明，扩展不等于把 claude 放进你的 PATH；要在终端运行 claude，需单独安装 CLI。
推荐组合用法
多数开发者可以组合使用：日常在 VS Code 插件里看 diff 和对话；需要终端能力时，打开 VS Code 集成终端运行 claude。如果外部终端已经启动 Claude Code，也可以用 /ide 连接到 VS Code，以获得 IDE 上下文能力。
配置建议
开启尊重 .gitignore
官方扩展设置中有 respectGitIgnore 选项，默认会排除 .gitignore 匹配的文件搜索。建议保持开启，避免把构建产物、依赖目录或临时文件加入上下文。
把项目规则写进 CLAUDE.md
在项目根目录创建 CLAUDE.md，写明技术栈、包管理器、测试命令和禁止事项：
# Project Rules
- 修改前先阅读 README.md 和 package.json。
- 使用 npm，不要改用 yarn 或 pnpm。
- 修改后运行 npm test 和 npm run lint。
- 不要读取、打印或提交 .env。
- 不要执行数据库清空、线上部署或删除文件命令，除非用户明确确认。敏感项目先用只读模式
如果项目涉及客户数据、生产配置、密钥、支付或权限系统，先让 Claude Code 只读分析。需要修改时，把范围限定在明确文件和明确函数，避免一次性授权过大。
常见问题排查
扩展安装不上怎么办
先确认 VS Code 版本是否达到 1.98.0 以上，再确认网络是否能访问 Marketplace。如果是 VS Code Fork，尝试 Open VSX 或退回到 Claude Code CLI。
安装后看不到 Spark 图标怎么办
先打开一个代码文件，再看编辑器右上角；也可以从 Activity Bar、状态栏或命令面板搜索 Claude Code。仍然没有时，运行 Developer: Reload Window。
登录后还是提示未登录怎么办
先重新加载窗口，再尝试重新登录。如果你依赖环境变量或第三方 provider，注意 VS Code 可能没有继承 shell 环境。可以从终端用 code . 启动 VS Code，让它继承当前环境。
为什么终端里没有 claude 命令
因为扩展自带的 CLI 主要服务于图形面板，不会自动把 claude 命令安装到你的 shell PATH。要在终端运行 claude，需要单独安装 Claude Code CLI。
Claude Code 改错文件怎么办
先拒绝 diff，或者用 Git 恢复未接受的改动。下次提示时明确文件路径、函数范围和禁止修改的文件，并要求它先输出计划。
自动接受改动安全吗
只适合你信任的本地项目和低风险修改。陌生项目、生产项目、权限相关代码、数据库脚本和配置文件，不建议开启过度自动化权限。
FAQ
Claude Code VS Code 插件是官方的吗？
是。官方 Marketplace 条目为 anthropic.claude-code，安装时建议核对发布方和扩展 ID。
使用插件还需要安装 Claude Code CLI 吗？
只使用图形面板不一定需要。但如果你想在 VS Code 集成终端里运行 claude，或者使用 CLI-only 功能，就需要单独安装 CLI。
插件能直接修改代码吗？
可以。Claude Code 可以提出文件修改，并通过 VS Code 的 diff 视图让你审核。建议先看计划和 diff，再接受改动。
插件能读取整个项目吗？
它可以根据工作区和提示引用读取项目上下文，但你应避免把敏感文件、密钥文件和不相关大目录加入上下文。保持 .gitignore 和项目规则清晰很重要。
可以在 Cursor 里使用吗？
官方文档提到扩展可在一些 VS Code Fork 中安装。实际表现取决于编辑器兼容性。如果遇到异常，可以改用 CLI。
VS Code 插件适合新手吗？
适合。相比纯终端，插件可以展示 diff 和面板交互，更容易理解 Claude 要改什么。但新手仍应从只读分析、计划审查和小步修改开始。
参考来源
本文安装条件、扩展功能和 CLI 差异参考 Claude Code 官方 VS Code 文档与 Visual Studio Marketplace 官方条目：Use Claude Code in VS Code、Claude Code for VS Code。功能细节可能随版本变化，正式配置前建议以官方页面为准。
环境配置与 Docker 工作流
适合阅读安装部署、本地配置、服务器搭建和自动化流程类文章后继续转化。
