Claude Code for VS Code 配置：从安装到项目可用
简答：Claude Code for VS Code 的最小可用路径是：确认 VS Code 版本、安装官方扩展、安装并验证 CLI、完成账号登录、打开项目后先做一次只读验证。普通账号先走这条路径；只有需要云平台或 API Key 时，再按 Bedrock、Vertex、Foundry 的官方文档分流配置。
定义：Claude Code for VS Code 是将 Claude Code 会话与 VS Code 工作区结合使用的一套配置方式，通常涉及 VS Code 扩展、Claude Code CLI、认证方式和项目级上下文文件。
先看结论：5 分钟完成最小配置
如果你的目标是在 VS Code 中让 Claude Code 阅读当前项目、提出修改计划并在确认后编辑文件，先不要配置 MCP、Hooks 或企业云平台。按“扩展—CLI—登录—工作区—只读验证”完成主流程即可。
| 项目 | 是否必需 | 作用 | 先做什么 |
|---|---|---|---|
| VS Code | 需要 | 提供编辑器、工作区和会话界面 | 确认版本满足扩展页面要求 |
| Claude Code 扩展 | 需要 | 在 VS Code 中启动和查看 Claude 会话 | 从官方 Marketplace 安装 |
| Claude Code CLI | 终端使用时需要 | 在集成终端或系统终端运行 claude | 安装后执行 claude --version |
| 登录凭据 | 需要 | 决定会话使用订阅、Console 或云平台认证 | 普通账号先使用浏览器登录 |
| CLAUDE.md | 可选 | 保存项目规范、测试命令和工作流 | 基础会话可用后再创建 |
扩展 Marketplace 页面列出的最低 VS Code 版本为 1.98.0；扩展还支持子代理、自定义斜杠命令和 MCP，但页面同时说明部分能力只能通过命令行配置。安装入口可查看 Claude Code for VS Code Marketplace 页面。
第一步：安装扩展、CLI，并选择 Windows 环境
- 安装扩展：打开 VS Code 的扩展面板，搜索 Claude Code，确认发布者与 Marketplace 页面一致后安装。
- 安装 CLI：如果你希望在 VS Code 集成终端输入
claude，按 Claude Code 官方安装文档安装 CLI。Native Install 是当前文档提供的安装路径，也可按系统使用 Homebrew、WinGet 等方式。 - 验证 CLI：重新打开终端，执行
claude --version。命令不存在时，先检查 PATH，再执行claude doctor检查安装环境。
Windows 可按使用场景选择环境：
| 环境 | 适合谁 | 配置重点 |
|---|---|---|
| Windows 原生 | 希望直接使用 PowerShell、文件路径和 VS Code Windows 工作区 | 按官方 Windows 安装方式配置 CLI；若需要 Bash 工具，再准备 Git for Windows |
| Git Bash | 习惯 Bash 命令且不想使用完整 Linux 子系统 | 确认 Git Bash 可被 VS Code 终端调用，并在同一终端验证 claude |
| WSL | 项目依赖 Linux 工具链、Shell 脚本或 Linux 环境 | 在 WSL 内安装 CLI，并从 WSL 环境启动或连接对应工作区 |
不要把 PowerShell、CMD、Git Bash 和 WSL 的安装命令混用。操作系统要求、原生 Windows 与 WSL 的差异，以及安装和验证步骤，以 Claude Code 官方 Advanced setup 文档为准。
第二步：登录普通账号，再确认 API Key 是否干扰
- 在 VS Code 中打开一个项目文件夹，而不是只打开单个文件。
- 从 Claude Code 扩展入口启动会话；首次使用时按提示在浏览器完成登录。
- 回到 VS Code 后发送只读请求，例如：
请检查当前分支，找出一个小问题并给出修改计划，暂时不要修改文件。 - 确认会话能读取工作区、输出计划，并在需要执行命令或修改文件时显示相应确认步骤。
Claude Code 官方认证文档说明，个人用户可以使用 claude.ai 账号，团队还可以使用 Claude for Teams 或 Enterprise、Claude Console，以及 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。不同认证方式不是同一条登录路径，普通用户应先完成浏览器登录，再考虑云平台。
如果机器上同时设置了 ANTHROPIC_API_KEY，认证结果可能与预期不同。官方文档说明：当订阅登录和 API Key 同时存在时，Claude Code 可能在获得批准后使用 API Key；可通过取消该变量并查看 /status确认当前凭据。不要把 Key 写进仓库、CLAUDE.md、项目共享设置或聊天内容。详细认证规则见 Claude Code Authentication，变量作用域见 Environment variables。
变量在终端可见、扩展却不可见时，先在启动 Claude Code 的同一个 Shell 中确认变量，再完全退出并重新打开 VS Code。环境变量只在当前终端设置时，通常不会自动出现在从桌面图标启动的编辑器进程中；具体继承行为取决于启动方式和系统环境。
第三步：按需求分流 Bedrock、Vertex 与 Foundry
企业云平台不应与普通账号配置混在一起。下面只列出官方文档明确支持的入口；如果你没有对应云账号、模型访问权限或组织认证，不要直接复制环境变量。
| 平台 | 前置条件 | 官方最小路径 | 验证重点 |
|---|---|---|---|
| Amazon Bedrock | AWS 账号、Bedrock 中启用 Anthropic 模型、IAM 权限和 AWS 凭据 | 运行 claude，选择第三方平台与 Amazon Bedrock，或按文档手动设置 CLAUDE_CODE_USE_BEDROCK=1 | 区域、凭据链、模型访问权限与 /status |
| Google Cloud 的 Agent Platform | Google Cloud 项目、相关 API、区域和认证条件 | 严格按官方页面配置项目、区域、认证与 Claude Code 变量，不要沿用旧教程中的变量名 | 项目 ID、区域、ADC 登录状态和模型可用性 |
| Microsoft Foundry | Foundry 资源、Claude 部署、认证方式及相应权限 | 按官方文档区分资源、端点、部署和认证，再配置 Claude Code | 部署名、端点、权限和环境变量是否属于同一资源 |
Bedrock 官方文档给出了前置条件、登录向导、AWS 凭据来源和 CLAUDE_CODE_USE_BEDROCK 等配置；Vertex 与 Foundry 也各有独立的官方部署页面。请分别查看 Claude Code on Amazon Bedrock、Claude Code on Google Cloud's Agent Platform和 Claude Code on Microsoft Foundry，不要把一个平台的变量、区域或认证方式复制到另一个平台。
第四步：配置 CLAUDE.md 与 settings.json
这两个文件的职责不同：CLAUDE.md是会话上下文，适合写项目规范；settings.json是行为设置，适合写权限、环境变量和其他 Claude Code 配置。官方文档明确说明，CLAUDE.md 是上下文而非强制执行层；要阻止某个动作，应使用权限规则或 Hook。
| 文件 | 作用域 | 适合内容 | 注意事项 |
|---|---|---|---|
~/.claude/CLAUDE.md | 当前用户的项目 | 个人编码偏好 | 不放项目秘密 |
./CLAUDE.md或./.claude/CLAUDE.md | 当前项目 | 架构说明、测试命令、团队规范 | 可提交到版本库 |
~/.claude/settings.json | 用户级 | 个人默认设置和非敏感环境变量 | 避免把 API Key 固定写入文件 |
.claude/settings.json | 项目共享 | 团队权限、Hooks 和插件配置 | 只放非敏感配置 |
.claude/settings.local.json | 当前用户的当前项目 | 个人覆盖值和本机配置 | 官方文档说明它用于个人例外，通常不提交 |
可以先创建一个短小的项目说明：
# 项目说明
## 常用命令
- 安装依赖：npm install
- 测试：npm test
## 工作规则
- 修改前先说明计划
- 优先复用现有模块
- 完成后运行相关测试
- 不读取或输出 .env 文件中的秘密
进入会话后可运行 /init生成起始文件，运行 /memory查看加载的记忆文件。相关作用域和加载顺序见 How Claude remembers your project；设置文件优先级和本地文件行为见 Settings files and precedence。
第五步：权限、MCP、Hooks 与子代理的安全配置
基础会话正常后，再增加高级能力。权限规则可放在设置文件中，示例：
{
"permissions": {
"allow": ["Bash(npm run lint)", "Bash(npm test *)"],
"deny": ["Read(./.env)", "Read(./.env.*)"]
}
}
这个示例只展示权限字段的最小写法，不代表所有项目都应使用相同规则。保存后在会话中使用 /permissions检查规则来源；规则语法、工具匹配和工作区信任行为以 Configure permissions为准。
- MCP：先确认服务器来源和权限范围。官方示例支持使用
claude mcp add添加远程或本地服务器，再用claude mcp list和会话内的/mcp查看状态。 - Hooks：适合在工具调用或会话生命周期执行检查，但脚本本身会影响本地环境，使用前应审阅命令、输入和退出码。
- 子代理：适合拆分范围明确的任务。先用只读或低风险任务验证，再授予必要工具权限。
MCP 的命令、项目作用域和连接状态见 Connect Claude Code to tools via MCP；Hooks 的配置位置、事件和失败行为见 Hooks reference；子代理文件和工具限制见 Create custom subagents。
Claude Code 扩展与 VS Code 原生 Agent 怎么选
VS Code 现在可以在同一编辑器中使用不同的 Agent harness。Claude Code 扩展与 VS Code 原生第三方 Agent 入口不是同一套配置：
| 选择 | 适合场景 | 配置思路 |
|---|---|---|
| Claude Code 扩展 | 希望使用 Claude Code 自己的会话、工具、权限和 CLI 工作流 | 按本文的扩展、CLI、账号和项目配置执行 |
| VS Code 原生第三方 Agent | 希望在 Chat 或 Agents 窗口中统一管理不同 Agent | 按 VS Code 的会话类型、账号或 BYOK 设置配置 |
| VS Code 内置 Agent | 主要依赖 VS Code 的工具、审批和自定义 Agent | 按 VS Code 自己的 Agent 设置配置 |
VS Code 官方文档建议先区分本地会话、云端合作 Agent 和内置 Agent，再选择工作流。可参考 Using third-party agents in VS Code。如果你只是想运行 Claude Code 本身，不必因为看到 VS Code 的 Agent 入口而重复安装或重复登录。
常见故障：按配置层排查
| 现象 | 优先检查 | 处理动作 |
|---|---|---|
| 扩展安装后找不到 Claude Code | 扩展是否安装完成、VS Code 版本是否满足、窗口是否刷新 | 执行 Developer: Reload Window，再从扩展页面确认启用状态 |
终端提示 claude 找不到 | CLI 是否安装、终端是否重启、PATH 是否更新 | 重新打开同一终端，执行 claude --version和 claude doctor |
| 面板要求登录或账号不对 | 浏览器登录的账号、组织策略、已有 API Key | 检查认证页面和 ANTHROPIC_API_KEY，必要时取消变量后重新登录 |
| 终端能读到变量，VS Code 读不到 | VS Code 的启动方式与 Shell 是否一致 | 从设置变量的 Shell 启动 VS Code，或重启编辑器和终端 |
| CLAUDE.md 没有生效 | 文件路径、当前工作目录和文件内容 | 确认项目根目录位置，运行 /memory查看加载结果 |
| 权限配置没有按预期工作 | JSON 格式、文件作用域、工作区信任和优先级 | 用严格 JSON 保存，再运行 /permissions核对实际规则 |
| MCP 显示连接失败 | 服务器命令、URL、认证和本地运行时 | 执行 claude mcp list查看状态，按服务器类型重新检查配置 |
遇到问题时不要先增加更多插件或环境变量。建议依次确认：版本、CLI、认证、当前目录、配置文件、权限、MCP。本文未列出的平台限制、组织策略或版本差异，应回到对应官方文档核对。
最后的最小验证清单
- 扩展已安装，VS Code 版本满足 Marketplace 要求。
claude --version可以返回版本。- 普通账号或指定云平台认证已完成。
- VS Code 打开的是项目文件夹。
- 只读请求可以返回项目相关计划。
- 修改文件和运行命令前会出现可审阅的确认步骤。
- 需要长期项目上下文时，再添加简短的
CLAUDE.md。 - 需要安全控制时，使用权限规则或 Hooks，而不是只在提示词中提醒。
本文是第三方配置整理，本站不是 Claude Code 官方站；账号资格、扩展版本、认证方式和平台支持范围请以对应官方文档为准。
如果你还要把 Claude Code 或其他开发工具接入 OpenAI 兼容 API，可前往犀速-AI 官网查看相关接入与排查资料。
常见问题
Claude Code for VS Code 一定要单独安装 CLI 吗？
如果只使用扩展提供的会话界面，应先按 Marketplace 和扩展文档操作；如果要在 VS Code 集成终端或系统终端输入 claude，则应按 Claude Code 官方安装文档安装 CLI，并用 claude --version 验证。不要把扩展入口和终端命令是否可用混为一谈。
Claude Code 普通账号和 API Key 应该怎么选？
普通用户先按 Authentication 文档使用浏览器登录；只有明确要使用 Console、API Key 或云平台时再配置对应凭据。若同时存在 ANTHROPIC_API_KEY，官方文档说明它可能影响实际认证方式，可取消变量后重新登录并用 /status 核对。
Windows 原生、Git Bash 和 WSL 选哪个？
日常 PowerShell 和 Windows 项目可选 Windows 原生；依赖 Bash 工具但不需要完整 Linux 环境时可选 Git Bash；项目依赖 Linux 工具链时可选 WSL。关键是 CLI、PATH、Shell 和 VS Code 工作区要处在同一套环境中。
CLAUDE.md 能代替权限规则吗？
不能。官方文档把 CLAUDE.md 定义为会话上下文，用于项目规范、架构说明和测试命令；它不是强制安全层。要限制读取文件、执行命令或调用工具，应使用 settings.json 中的权限规则，必要时使用 Hooks。
为什么环境变量在终端可见，VS Code 里却没有？
常见排查方向是启动方式不同：变量可能只存在当前 Shell，而 VS Code 是从桌面图标或另一个进程启动的。请在启动 VS Code 的同一环境中确认变量，完全重启 VS Code 后再验证，并用 Claude Code 的环境变量和认证文档核对变量名。
Bedrock、Vertex 和 Foundry 能直接套用同一组配置吗？
不能直接套用。三者的账号、区域、资源、模型访问权限、认证和变量要求不同。应分别阅读 Claude Code 官方的 Bedrock、Google Cloud Agent Platform 和 Microsoft Foundry 配置页面，再按对应平台完成验证。
相关阅读
参考资料
- Claude Code for VS Code - Visual Studio Marketplace（marketplace.visualstudio.com）
- Advanced setup - Claude Code Docs（code.claude.com）
- Environment variables - Claude Code Docs（code.claude.com）
- Configure permissions - Claude Code Docs（code.claude.com）
- Using third-party agents in VS Code - Visual Studio Code（code.visualstudio.com）