Claude Code 连接 JetBrains 失败时如何分层排查
command not found、No available IDEs detected 和 Diff 没有进入 IDE，看起来都像“插件坏了”，实际发生在不同层。尤其当 JetBrains 运行在 Windows，而 CLI 位于 WSL、容器或远程主机时，两个进程可能使用不同文件系统、环境变量和网络边界。本文提供一条非破坏性的排查路径：先收集证据并确定失败层，再依据当前官方文档修复；不会直接建议重装、放宽防火墙或改系统网络。
先记录环境拓扑
开始操作前写下四项信息：
| 项目 | 需要确认的内容 |
|---|---|
| IDE 位置 | Windows、macOS、Linux、本地客户端或远程后端 |
| CLI 位置 | 本机、WSL 发行版、容器或远程主机 |
| 项目路径 | IDE 与 CLI 分别看到的绝对路径 |
| 启动方式 | IDE 内置终端、外部终端或远程会话 |
只有当 IDE 集成和 CLI 位于兼容的运行环境，且指向同一个项目时，连接才有意义。不要先假设“都在一台电脑上”就等于同一环境。
第一层：CLI 是否在当前环境可用
在实际启动 Claude Code 的那个终端执行：
claude --version
如果失败，问题还没有到 IDE 层。继续确认当前 shell 找到的命令位置。
Windows PowerShell：
Get-Command claude
macOS、Linux 或 WSL：
command -v claude
记录输出的路径和错误原文。系统终端能找到命令，而 IDE 内置终端找不到，通常说明两个进程继承的环境不同。此时应对照安装方式和 JetBrains 当前配置处理 PATH，不要通过猜测可执行文件位置来绕过问题。
第二层：CLI 是否位于目标项目
命令可用后，确认当前工作目录。macOS、Linux 或 WSL 使用：
pwd
PowerShell 使用：
Get-Location
再从该目录启动：
claude
进入会话后先执行只读检查：
不要修改文件。列出当前项目顶层目录，并指出你依据的项目路径和构建配置文件。
把结果与 IDE 项目树对照。路径错误时退出会话，从正确目录重新启动；不要用后续提示词补偿错误的项目根目录。
第三层：IDE 是否能被发现
从外部终端启动时，可在 Claude Code 会话中运行：
/ide
如果返回 No available IDEs detected，依次记录以下状态：
- 目标 JetBrains IDE 和项目是否处于打开状态。
- 当前版本要求的 IDE 集成是否已安装并启用。
- 从 IDE 内置终端启动是否能改变结果。
- IDE 与 CLI 是否在不同的本机、WSL、容器或远程环境。
前两项属于安装与启用问题，第三项用于比较启动环境，第四项决定是否需要查阅专门的远程配置。具体支持范围和配置入口以 Claude Code JetBrains 官方文档 为准。
第四层：远程环境中的组件位置
JetBrains Remote Development、SSH、容器和 WSL 都可能把界面与项目执行环境分开。需要确认三个组件实际位于哪里：
- 项目文件由哪个环境读取。
claude进程在哪个环境运行。- IDE 集成按当前文档要求安装在哪一侧。
如果 CLI 读取的是 Linux 路径，而 IDE 打开的是另一个 Windows 工作副本，即使两边文件名相同，也不是同一个项目上下文。先统一工作副本和运行位置，再排查发现协议。
对于 WSL，可以在 PowerShell 记录发行版状态：
wsl -l -v
这条命令只用于确认发行版与运行状态，不证明跨环境连接已经建立。
不要把通用防火墙规则或固定子网地址直接当作解决方案。企业设备的网络策略、WSL 模式和 IDE 架构各不相同；修改前需要知道被阻断的具体进程、端口和流向，并遵循组织的安全流程。
第五层：连接成功后再查 Diff
Diff 仍在终端显示时，先确认 /ide 已连接到目标 IDE，或 Claude Code 确实从相应 IDE 的内置终端启动。连接层没有通过，调整 Diff 偏好不会建立连接。
随后用一个可撤销的小改动验证：
只在当前文件增加一处无行为变化的注释，展示 diff 后停止，不要修改其他文件。
验证结束后撤回测试改动。若 IDE 已连接但仍没有预期展示，再根据当前版本文档检查配置；不要依赖旧文章中的固定选项名称。
用症状缩小范围
| 症状 | 已知范围 | 下一项证据 |
|---|---|---|
claude 找不到 |
CLI 或当前 shell 环境 | 命令解析结果与安装记录 |
| 系统终端可用，IDE 终端不可用 | 进程环境差异 | 两边的命令位置和环境配置 |
| CLI 读取错误项目 | 工作目录或工作副本 | 两边的绝对项目路径 |
/ide 没有目标 IDE |
集成启用或运行边界 | IDE 状态、启动位置、官方支持条件 |
| IDE 可发现但选区无效 | 上下文传递 | 当前文件、独特标识符和连接状态 |
| 只有远程场景失败 | 组件安装或网络边界 | CLI、项目和集成各自的运行位置 |
| Diff 仍在终端 | 连接或当前配置 | /ide 结果与小改动验证 |
提问或提交故障单时，附上环境拓扑、命令位置、项目绝对路径、/ide 原始输出和已经完成的检查。敏感路径、令牌和内部主机名应先脱敏。
何时才考虑重装或网络变更
只有在证据指向对应层时才采取有状态的修复：
- CLI 文件缺失或安装损坏，才按官方流程重新安装 CLI。
- 集成未安装、被禁用或版本不兼容，才处理插件。
- 已证明跨环境通信被安全策略阻断，才由有权限的人评估网络规则。
- 项目工作副本不一致，先统一开发环境，不通过端口放行掩盖路径问题。
操作后重复最初的只读验证，以确认修复的是原问题，而不是偶然改变了症状。
结论与限制
Claude Code 与 JetBrains 的连接故障应按 CLI、进程环境、项目路径、IDE 发现和远程边界逐层定位。每层都保留可复述的命令输出，能避免把路径问题误判为网络问题，也能减少无依据的重装和安全策略变更。
远程开发和 WSL 的支持方式会随 IDE、操作系统和 Claude Code 版本变化。本文给出诊断顺序，不提供通用防火墙或网络配置；具体修复必须依据当前官方文档和所在组织的环境约束。