Claude Code 在 VS Code 里用不了？先定位失败表面

Claude Code 在 VS Code 里用不了时，先不要重装 VS Code、降级扩展或改 API key。真正快的排障方式，是先看失败发生在哪个表面：官方扩展 UI、集成终端、登录或状态、Windows shell、Provider 配置、VS Code 扩展冲突、性能卡死，还是另一个 VS Code 助手。

先把证据压窄：Claude Code 版本、VS Code 版本、系统、安装方式、命令输出、Claude Status 时间、provider 路线、内存或 heapdump 证据，以及 Claude Code 日志。这样的包，比“我重装了很多东西还是不行”更有用。

先修官方扩展 UI，而不是先重装

如果 Spark 图标、侧栏面板或 Claude Code 命令消失，先留在 VS Code UI 分支。Anthropic 的官方 VS Code 文档要求 VS Code 1.98.0 或更新版本，并说明扩展可以从 Marketplace 或 Extensions 视图安装；安装后不显示时，低成本动作是重载窗口。这个检查比重装编辑器便宜，也更保留证据。

先试三个入口。打开一个真实文件，因为编辑器右上角的 Spark 图标通常需要当前有文件。再试状态栏入口，它在没有打开文件时也可能能打开 Claude。最后打开命令面板，搜索 Claude Code 命令，包括打开新标签、查看日志或 terminal 相关命令。

如果这些入口都没有，执行 Developer: Reload Window。重载后面板出现，就验证 UI 分支已恢复；如果面板出现但登录失败，转到登录和状态分支；如果禁用其他扩展后才出现，转到冲突分支；如果仍然没有，记录 VS Code 版本、扩展版本、安装来源和日志，不要先把所有配置删掉。

版本回退不是第一步。社区里确实会出现某个命令注册失败、侧栏加载失败或 Windows 上扩展不工作的报告，但这些只能在错误文本、版本和平台都匹配时使用。没有匹配证据时，回退只会让你失去当前日志。

用集成终端证明 CLI 与 PATH

集成终端能最快把扩展 UI 问题和本地二进制问题分开。在 VS Code terminal 里运行：

claude --version

如果这里找不到命令，不要继续改扩展设置。你已经进入 CLI、PATH、shell 或安装路线。先在外部 shell 里确认 claude --version 是否能跑，再从这个 shell 启动 VS Code，然后回到集成终端重试同一个命令。外部 shell 正常但 VS Code 不正常，通常是启动上下文或 profile 继承问题。

命令可见后再运行官方诊断。Claude Code 中可以用 /doctor，shell 中可以用 claude doctor。诊断不是仪式，它要给出同表面证据：之前失败的 VS Code terminal 现在 doctor 通过，或者 doctor 仍然指出某个安装、登录或权限错误。

如果二进制根本不存在，转到 Claude Code 安装指南，不要让当前页面变成完整安装教程。这里的目标是识别失败表面；安装缺失时，安装路线就是下一步。

Windows 要把 PowerShell、Git Bash、WSL 分开看

Windows 上的故障经常看起来像扩展坏了，因为错误出现在 VS Code 里。但真正归属可能是 PowerShell、Git for Windows、Git Bash、WSL、PATH，或者 VS Code 是从哪里启动的。官方安装和登录排障也把 shell、PATH 和 claude --version 当作关键证据。

做一个两列对比。外部 PowerShell 跑 claude --version，VS Code terminal 跑同样命令；Git Bash 跑一次，WSL 也跑一次。如果 PowerShell 正常但 Git Bash 不正常，就先修 Git Bash 路线。如果 WSL 正常但 Windows terminal 不正常，不要把它写成扩展故障。如果都不正常，安装或 PATH 拥有问题。

安全顺序是：确认目标 shell 已安装；从能看到 claude 的 shell 打开 VS Code；确认集成终端看到同一个路径；运行 claude doctor；最后再回 UI 分支看扩展面板是否正常。这样可以避免同时改 PATH、扩展、登录和 workspace trust，导致成功后也不知道原因。

Provider 配置也会被 Windows 启动上下文影响。如果 ANTHROPIC_API_KEY、Bedrock、Vertex、Foundry 或网关变量只在某个 shell 里存在，VS Code 可能没有继承。先证明二进制，再证明 provider 路线。

把登录、Claude Status 和 Provider 模式拆开

登录循环和无响应不该用“重装扩展”开局。如果 Claude Code 表面能输入命令，先运行 /status，然后查看 Claude Status。2026 年 5 月 2 日复核时，Claude Status 显示 5 月 2 日和 5 月 1 日没有事件；但 4 月 28-30 日附近仍有已恢复的 Claude.ai、API、认证、模型错误率和 Claude Code 登录路径事件。这个边界很重要：状态是有时间戳的分支信号，不是本地健康证明。

如果相关事件正在进行，停止本地折腾。不要在服务事件期间重装、降级、旋转凭据或随便禁用扩展。记录时间，等恢复后用同一路径重试。如果状态正常但同一路径仍失败，才继续看本地 UI、CLI、session、provider 或 VS Code 状态。

Provider 模式是另一个分支。只要涉及 ANTHROPIC_API_KEY、Bedrock、Vertex、Foundry 或兼容网关，下一步可能是凭据优先级和环境继承，而不是官方扩展 UI。需要检查变量、settings 文件或 provider 选择时，用 Claude Code API 配置指南。如果真正问题是账号或计费归属，用 API key 与订阅计费指南。

窄验证是：确认 /status，确认认证或 provider 拥有者，从带有目标环境的 shell 重启 VS Code，再执行同一个任务。成功说明是路线错配；失败则带着路线证据升级。

处理卡死、高内存和上下文反复塞满

面板能打开但卡住，和面板根本不存在不是同一个故障。Anthropic 的排障文档把 high CPU、memory usage、command hangs、auto-compaction thrashing 和 search problems 放在性能与稳定性分支：也就是 Claude Code 已经能跑，但运行状态不健康。

先做低成本动作。大任务之间新开会话或重启 Claude Code；上下文太满时运行 /compact；把大型 build 目录、生成文件和巨大日志排除在上下文之外。如果命令本身挂住，先试 Ctrl+C；仍无响应时关闭 terminal 或 Claude Code session，重启后在同一目录用 claude --resume 接回。

升级点也要明确。重启和压缩后内存仍高，再运行 /heapdump，把 heap snapshot 和 memory breakdown 作为报告证据。只有禁用其他 VS Code 扩展后才恢复，就转到冲突分支；同一路径失败时 Claude Status 正在出事件，就停止本地排障，等恢复后再测。

隔离 VS Code 冲突和 Restricted Mode

即使 Claude Code 安装正确、CLI 健康，VS Code 仍可能拥有故障。扩展冲突、特殊 profile、工作区信任和 Restricted Mode 都会改变扩展行为。官方文档提到 Restricted Mode，VS Code 自己也提供了 Troubleshoot Issue 和 Extension Bisect。

先做可逆隔离：

code --disable-extensions

如果禁用其他扩展后 Claude Code 正常，官方扩展不再是第一嫌疑。使用命令面板里的禁用扩展、Help: Troubleshoot Issue，再用 Extension Bisect 找到冲突项。不要手动卸载一半编辑器；VS Code 可以帮你二分。

工作区信任是另一类边界。仓库处于受限模式时，扩展可能拿不到需要的能力。只有在理解仓库和本地安全策略时才信任工作区。验证仍然是同一件事：信任或冲突变更后，Claude Code 命令、面板和 terminal 路线是否在同一工作区恢复。

版本回退只在精确匹配时使用

版本回归是真问题，但不是通用答案。公开社区证据里会出现 command 'claude-vscode.editor.openLast' not found、侧栏加载失败、Windows 上 CLI 正常但 VS Code 扩展失败等描述。它们有价值，因为给了症状语言和版本线索。

只有三项同时匹配，才进入回退或等待修复分支：准确命令或面板症状、扩展或 Claude Code 版本范围、平台和 shell 上下文。匹配后，收集日志、版本、VS Code 版本、系统和错误文本，再查当前版本是否已修复。临时回退可以是受控 workaround，但不要把它写成所有“用不了”的默认答案。

如果错误实际是 API Error: 500，转到 Claude Code API error 500 指南。如果是 overloaded 或 529，看 Claude Code overloaded error 指南。如果是共享额度或限制耗尽，看 Claude Code usage limits 指南。

另一个助手坏了，就离开 Claude Code 分支

“Claude 在 VS Code 里不行”有时只是归属错误。失败的面板可能属于 Continue、Cline、Roo Code、Copilot Chat 或其他 VS Code 助手。这些工具可以通过自己的 provider 设置调用 Claude 模型，但它们的 UI、model dropdown、API key 字段或 base URL 错误，不由 Claude Code 文档解决。

退出规则很简单：如果面板、命令或设置页不是官方 Claude Code 扩展，就停止使用 Claude Code 命令。检查那个扩展自己的模型、key、base URL、workspace 权限和日志。如果它直接调用 Anthropic API，故障可能属于该应用的 provider 配置或 Anthropic API 状态，而不是 Claude Code 的 VS Code 集成。

这个区分会避免破坏性修复。删除官方 Claude Code 扩展不会修好 Continue 的 provider 设置；旋转 API key 也不会让官方 Spark 图标出现。先匹配归属，恢复才会快。

用升级反馈包结束排障

好的验证是一次只改一个分支动作，然后重复同一个表面。坏的验证是同时改版本、shell、auth、provider、workspace 和任务形状，最后无法解释结果。

同一路线仍失败时，整理这些字段：

• Claude Code 版本和扩展版本
• VS Code 版本
• OS 与 shell，包括 PowerShell、Git Bash、WSL 或启动上下文
• 安装方式，以及 VS Code terminal 中 claude --version 是否成功
• /status、claude doctor 或 /doctor 输出，去掉 secret
• Claude Status 时间戳和当时是否有事件
• provider 路线，例如订阅登录、ANTHROPIC_API_KEY、Bedrock、Vertex、Foundry 或网关
• Claude Code 日志和准确命令或面板错误

停止规则也清楚：服务事件就等；terminal 看不到二进制就修安装或 PATH；provider 路线拥有问题就修变量优先级；另一个助手拥有 UI 就离开 Claude Code；官方扩展在这些分支都干净后仍失败，才带证据升级。

常见问题

Claude Code 为什么不显示在 VS Code 里？

先走官方扩展 UI 分支。打开一个文件，试状态栏和命令面板，再执行 Developer: Reload Window。仍然没有时，确认 VS Code 1.98.0+、查看 Claude Code 日志，并检查 Restricted Mode 或扩展冲突。

外部终端能用，VS Code terminal 找不到 claude 怎么办？

通常是 VS Code 没从同一个 shell 上下文启动，或者没有继承相同 PATH。从能跑 claude --version 的 shell 启动 VS Code，再在集成终端重试。Windows 上要分别比较 PowerShell、Git Bash、WSL 和 Git for Windows。

需要重装 VS Code 吗？

通常不需要。先重载窗口、确认命令面板和状态栏入口、验证 claude --version、运行 doctor、隔离扩展冲突。早重装会丢掉证据，而且经常碰不到真实分支。

Claude Status 正常，扩展还会失败吗？

会。状态页只能排除当时的服务事件分支，不能证明本地 VS Code 扩展、shell PATH、Provider 环境、workspace trust 或第三方助手设置健康。

VS Code 里的 Claude Code 一定需要 API key 吗？

普通订阅登录路线不一定需要 API key。只有你使用 Provider 模式、直接 Anthropic API、Bedrock、Vertex、Foundry 或网关时，key 和 provider 设置才拥有问题。环境里存在 ANTHROPIC_API_KEY 时，先确认当前路线。

Claude Code 能打开但卡死或内存很高怎么办？

把它当作性能与稳定性问题，而不是“扩展没装好”。先新开会话、重启 Claude Code、运行 /compact、排除大型输出；这些都无效且内存仍高时，再用 /heapdump 收集证据。

什么时候值得回退扩展版本？

只有准确命令或面板错误、平台和版本范围都匹配已知回归时。先完成 reload、日志、CLI 证明、状态和扩展隔离；回退也要记录版本证据，并在修复版本发布后更新。