<!-- title: Claude Code双轨入门：CLI与IDE首跑修Bug -->

## 概述

本教程面向零基础开发者，目标是把 Claude Code 从"听说过"变成"能干活"。不同于只讲命令行 `hello world` 的传统入门，本文走 **双轨入口 + 首个真实修复任务** 的路线：先把 CLI 引擎装通，再把它分别接入 VS Code 与 JetBrains 两条 IDE 通道，最后用一个自带 Bug 的小型 Node.js 项目，让 Claude 读取编辑器诊断、定位缺陷、提交修复 Diff。学完你将具备在任何主流编辑器里驱动 Claude Code 的能力，并掌握认证、配置、双向打通的完整链路。

## 前置条件

- 一台 macOS、Linux 或 Windows（含 WSL2）的开发机
- 一个 Claude Pro / Max / Team / Enterprise 订阅，**或** 一个 Anthropic API Key（二选一）
- 终端能用、会基本的 `cd` 与 `npm`
- （可选）已装 VS Code 1.98.0+ 或任意受支持的 JetBrains IDE
- Node.js 18+（仅在选择 npm 安装或跑实战案例时需要；原生安装器不依赖它）

## 三条入口全景

很多人误以为 Claude Code 等于一个命令行工具。准确的说法是：**CLI 是引擎，IDE 插件是桥梁，Web/移动端是延伸**。引擎只有一份，桥梁可以多挂，这正是"双轨"的含义。

```mermaid
flowchart TD
    A[第一步 安装 CLI 引擎] --> B[第二步 登录认证]
    B --> C{第三步 选择入口}
    C -->|纯终端| D[CLI 交互模式 claude]
    C -->|编辑器内| E[VS Code 扩展]
    C -->|编辑器内| F[JetBrains 插件]
    C -->|浏览器| G[claude.ai/code]
    D <-->|/ide 双向打通| E
    D <-->|/ide 双向打通| F
    E --> H[第四步 配置 settings/CLAUDE.md]
    F --> H
    D --> H
    H --> I[第五步 首个修复任务]
    I --> J[Diff 审查 + 跑测试]
    J --> K[交付]
```

理解这张图后，下面的每一步都只是把对应节点填实。

## 步骤一：安装 CLI 引擎

引擎是所有 IDE 插件的底层依赖——插件本身**不捆绑** CLI，它只是在集成终端里调用 `claude` 命令。所以无论你最终用哪个编辑器，这一步都绕不开。

### 1.1 原生安装器（推荐）

原生安装器零依赖、自动后台更新，是 2026 年的官方首选：

```bash
# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

Windows 用户若尚未安装 Git for Windows，请先装好它。原生安装器会把二进制放进 `~/.claude/bin`，并尝试把它加进 PATH。

### 1.2 npm 安装（备选）

如果你已有 Node.js 工具链，也可以走 npm：

```bash
node --version        # 必须 v18.0.0 及以上
npm install -g @anthropic-ai/claude-code
```

**绝对不要**用 `sudo npm install -g`。遇到 EACCES 权限错误，正确做法是把 npm 全局目录改到家目录：

```bash
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc  # 或 ~/.bashrc
source ~/.zshrc
```

### 1.3 验证

```bash
claude --version
```

打印出一串版本号即成功。若显示 `command not found`，新开一个终端窗口让 PATH 生效；仍失败就手动补：

```bash
export PATH="$HOME/.claude/bin:$PATH"
```

| 安装方式 | 依赖 | 更新机制 | 适用场景 |
|---------|------|---------|---------|
| 原生安装器 | 无 | 自动后台更新 | 推荐绝大多数人 |
| npm | Node.js 18+ | 手动 `npm update` | 已有 Node 工具链 |
| Web App | 无 | 自动 | 受限网络、不能装软件的机器 |

## 步骤二：登录与认证

Claude Code 支持两条认证路径，**理解它们的区别能避免意外账单**。

### 路径 A：订阅登录（默认）

直接运行 `claude`，首次启动会拉起浏览器，用你的 Claude 账号登录。登录后所有用量计入订阅额度，无需任何 Key。

**关键陷阱**：如果你同时又设了 `ANTHROPIC_API_KEY` 环境变量，Claude Code 会**优先**走 API 计费，而不是订阅。要确认自己用的是哪条路：

```bash
claude
> /config
```

`/config` 面板会显示当前账号类型（Pro / Max / API Key）和模型。看到意外 API 费用时，第一时间检查 shell 配置里有没有遗留的 `ANTHROPIC_API_KEY`。

### 路径 B：API Key

没有订阅、想按量计费时，去 `console.anthropic.com` 创建 Key（**只显示一次**，立即复制），然后：

```bash
# macOS / Linux，写入 ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-..."
```

重载 shell 后再跑 `claude`，它会自动用这把 Key 认证。

> 常见问题：装完一直跳浏览器让我登录，但我明明有 API Key。
> 解法：确认环境变量已在**当前终端**生效（`echo $ANTHROPIC_API_KEY` 有值），且写入了正确文件；WSL 用户注意别把变量只写进 Windows 侧。

## 步骤三：在 VS Code 接入扩展

引擎跑通后，VS Code 扩展在它之上叠加四项实在的增强，这也是"双轨"价值最直观的体现：

1. **内联 Diff 视图**：Claude 改文件时，VS Code 弹出标准三路 Diff——绿色增、红色删，落盘前你可整体接受、整体拒绝或逐块接受。
2. **诊断集成**：Claude 直接读到 Problems 面板里的 TypeScript、ESLint、语言服务器报错，无需你复制粘贴。
3. **点击导航**：终端输出里的 `src/app/page.tsx:42` 变成可点链接，跳转到对应行。
4. **终端面板融合**：Claude 跑在集成终端里，与你的 dev server 共享同一个工作区根目录。

### 安装步骤

1. 确认 VS Code ≥ 1.98.0。
2. `Ctrl+Shift+X`（Win/Linux）或 `Cmd+Shift+X`（Mac）打开扩展面板，搜索 **Claude Code**，认准发布者为 **Anthropic**（避开同名第三方分叉），点 Install。
3. 或在 Quick Open（`Ctrl+P` / `Cmd+P`）粘贴：`ext install anthropic.claude-code`。
4. `File → Open Folder` 打开项目根目录。
5. `Ctrl+``（Win/Linux）或 `Cmd+``（Mac）打开集成终端，确保当前目录是项目根。
6. 运行 `claude`。扩展会自动检测并连接，终端出现确认信息。
7. 若自动检测失败（常见于重启后），强制连接：`claude --ide`。

### 预期结果

侧边栏出现一个火花图标；Claude 改文件时自动弹 Diff；终端里的文件引用变成可点链接；Problems 面板的错误 Claude 能"看见"。

> 常见问题：运行 `claude` 没有出现 IDE 连接提示，Diff 也不弹。
> 解法：**完全重启** VS Code（不是 Reload Window），到扩展面板确认没有出现"Disable"按钮（说明已启用），再 `claude --ide` 强连，并确认 `claude --version` 在集成终端里能打印版本。

## 步骤四：在 JetBrains 接入插件

JetBrains 侧的逻辑完全一致：先有 CLI 引擎，再装插件。

支持 IntelliJ IDEA、PyCharm、Android Studio、WebStorm、PhpStorm、GoLand。安装路径：`Settings/Preferences → Plugins → Marketplace`，搜索 **Claude Code [Beta]**，Install 后**完全重启** IDE。

JetBrains 插件特有快捷键：

| 功能 | macOS | Windows/Linux |
|------|-------|---------------|
| 快速唤起 Claude Code | `Cmd+Esc` | `Ctrl+Esc` |
| 插入文件行号引用（如 `@src/auth.ts#L1-99`） | `Cmd+Option+K` | `Alt+Ctrl+K` |

**ESC 键冲突**：JetBrains 终端默认让 ESC 把焦点切回编辑器，这会"吃掉" Claude Code 的中断信号。修复：`Settings → Tools → Terminal`，取消勾选 *Move focus to the editor with Escape*，或删掉 *Switch focus to Editor* 快捷键。

> 安全提示：在 JetBrains 里开启 auto-edit 权限时，Claude 可能修改会被 IDE 自动执行的配置文件，从而绕过 Bash 权限提示。建议在 IDE 场景下使用**手动审批**模式编辑，只用可信 prompt。

## 步骤五：用 `/ide` 双向打通

"双轨"的精髓在于 CLI 与 IDE 可以互通：你既能在 IDE 集成终端里跑 `claude` 享受全套增强，也能在**外部终端**启动 `claude` 后，用斜杠命令反向连到 IDE：

```bash
claude          # 在外部终端
/ide            # 连接到已打开的 VS Code / JetBrains，激活 Diff、诊断、导航
```

为了让 Claude 看到与 IDE 相同的文件，**从项目根目录启动**它。`/config` 里把 diff tool 设为 `auto`（Diff 显示在 IDE）或 `terminal`（留在终端），可控制 Diff 落点。

恢复上次会话用 `claude --continue`——它会带着该项目上次的完整上下文回来，不必从头解释任务。

## 步骤六：配置 settings.json 与首个 CLAUDE.md

### settings.json 层级

Claude Code 的配置按优先级从低到高合并：

1. `~/.claude/settings.json`（用户级，全局默认）
2. `<项目>/.claude/settings.json`（项目级，团队共享）
3. `<项目>/.claude/settings.local.json`（项目本地，不入版本库）

零基础起步时，先在项目级放一份**最小可用**配置：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ]
  }
}
```

`allow` 列表里预先批准只读与测试命令，能大幅减少反复确认。生产环境务必慎用大范围通配（如 `Bash(*)`）。

### 首个 CLAUDE.md

在项目根放一个 `CLAUDE.md`，给 Claude 提供"项目说明书"。最小模板：

```markdown
# 项目说明
一个 Node.js 折扣计算小工具，用于练习 Claude Code 的诊断修复流程。

## 技术栈
- Node.js 18+
- Jest（单元测试）

## 常用命令
- 安装依赖：`npm install`
- 跑测试：`npm test`
- 代码风格检查：`npm run lint`

## 约定
- 修复 Bug 前先跑一次 `npm test` 确认失败用例
- 不要自动提交，改完由我手动 commit
```

这份文件会被自动注入上下文。写得越准，Claude 越少跑偏。

## 实战案例：首个真实 Bug 修复任务

下面用一个可复现的小项目，串起"诊断 → 定位 → 修复 → Diff 审查 → 验证"完整闭环。

### 1. 建项目

```bash
mkdir -p ~/projects/discount-calc && cd ~/projects/discount-calc
npm init -y
npm install --save-dev jest
```

把 `package.json` 的 `"test"` 改成 `"jest"`，并加一条 lint：

```json
{
  "scripts": {
    "test": "jest",
    "lint": "node --check src/*.js"
  }
}
```

### 2. 写一份带 Bug 的源码

`src/discount.js`：

```javascript
// 计算折后价。discountPercent 取值 0~100。
function applyDiscount(price, discountPercent) {
  // ❌ Bug：直接把百分比当小数乘，价格会变负
  return price - price * discountPercent;
}

module.exports = { applyDiscount };
```

`src/index.js`（故意带一个 lint 可捕获的问题）：

```javascript
const { applyDiscount } = require('./discount');

const unused = '这段未使用变量会被检查器标记';
console.log('100 打 20 折后价:', applyDiscount(100, 20));
```

`test/discount.test.js`：

```javascript
const { applyDiscount } = require('../src/discount');

test('100 元打 20% 折扣应为 80', () => {
  expect(applyDiscount(100, 20)).toBe(80);
});

test('原价不折扣应不变', () => {
  expect(applyDiscount(50, 0)).toBe(50);
});
```

### 3. 先看红

```bash
npm test
```

预期输出：两条用例一条通过、一条失败，`applyDiscount(100, 20)` 实际返回 `-1900`，不是 `80`。

### 4. 让 Claude 接手

在 VS Code 集成终端（或外部终端 `/ide` 连进来）运行：

```bash
claude
```

输入指令（这是关键 prompt，可照抄）：

> 在 `src/` 下修复折扣计算 Bug。要求：(1) 先跑 `npm test` 确认失败用例；(2) 同时读 Problems 面板里的诊断，清掉 `index.js` 里的 lint 问题；(3) 修复后重跑测试直到全绿；(4) 不要自动 git commit。

Claude 的典型动作链：

1. 跑 `npm test` → 读到失败用例 `applyDiscount(100, 20)` 期望 80 实得 -1900。
2. 读 Problems 诊断 → 看到 `index.js` 有未使用变量。
3. 打开 `src/discount.js` → 识别 Bug，改为 `price - price * (discountPercent / 100)`。
4. 改 `src/index.js` 删除未使用变量。
5. 重跑 `npm test` → 两条用例全绿。

每一步文件改动都通过 Diff 面板提交给你审。**养成习惯**：Diff 弹出后先读再接受，警惕 Claude 顺手做的"顺手重构"。

### 5. Diff 审查要点

- **Accept All**：整文件写入。
- **Reject All**：丢弃，给更具体的指令重做。
- **逐块接受**：悬停某个 hunk 单独接受，保留你认可的部分。

本例改动很小，Accept All 即可。

### 6. 验证并交付

```bash
npm test        # 全绿
git status      # 看改了哪些文件
git diff        # 人眼复核
git add src/    # 手动暂存（呼应 CLAUDE.md 里"不自动提交"的约定）
```

至此，你完成了一次**真实任务的闭环**——不是 hello world，而是一个从测试红到绿的修复。

## 常见问题与解决方案

| 症状 | 根因 | 解法 |
|------|------|------|
| `command not found` | PATH 未生效 | 新开终端；手动 `export PATH="$HOME/.claude/bin:$PATH"` |
| `EACCES` 权限错误 | 用了 sudo | 改 npm prefix 到 `~/.npm-global`，或换原生安装器 |
| Node 版本太旧 | < 18 | `nvm install 18 && nvm use 18` |
| WSL 报平台不匹配 | WSL 用了 Windows 侧 Node | 在 WSL 内用 nvm 装 Node |
| JetBrains "No available IDEs detected"（WSL2） | NAT/防火墙拦截 | 加 Windows 防火墙规则放行 WSL 子网，或切 mirrored 网络 |
| Diff 不弹 | 装了第三方同名扩展 / CLI < 1.x | 确认发布者 Anthropic、`claude --version` ≥ 1.x，`claude --ide` 强连 |
| 诊断读不到 | 报错文件没在编辑器打开 | 先在 VS Code 打开该文件，等语言服务器分析完再问 Claude |
| 意外 API 计费 | 同时设了 `ANTHROPIC_API_KEY` 与订阅 | 删掉该环境变量，或确认你确实想走 API 计费 |

## 工作流全景

把上述步骤压成一张可打印的速查图：

```text
flowchart LR
    subgraph 引擎层
      A1[原生安装器] --- A2[claude --version OK]
    end
    subgraph 认证层
      B1[订阅登录] --- B2[/config 确认]
      B3[API Key] -.备选.- B2
    end
    subgraph 入口层
      C1[CLI 交互]
      C2[VS Code 扩展]
      C3[JetBrains 插件]
    end
    subgraph 任务层
      D1[npm test 见红]
      D2[Claude 读诊断]
      D3[Diff 审查]
      D4[npm test 转绿]
    end
    A2 --> B2 --> C1 & C2 & C3
    C2 & C3 -. /ide .-> C1
    C1 & C2 & C3 --> D1 --> D2 --> D3 --> D4
```

## 延伸阅读

- **Claude Code 官方文档**（`code.claude.com/docs`）：quickstart、settings、permissions、authentication 各一页，权威且持续更新。
- **JetBrains 插件页**（Marketplace plugin 27310）：版本与已知问题。
- **CLAUDE.md 深度写法**：把项目说明书从模板升级为团队契约。
- **`/config`、`/ide`、`/clear`、`/compact` 斜杠命令全表**：交互模式的效率杠杆。
- **上下文窗口与 `--continue` / `--fork-session`**：长会话管理，避免越聊越慢。

## 训练营适用性评估

- **企业内训 / 1 天速成营**：高度适配。整套流程在干净机器上 45 分钟可跑通，实战案例自带可复现 Bug，讲师只需准备 Claude 账号或共享 API Key。建议教学时长 **1.5 小时**（含答疑）。
- **高校 / 在校生入门营**：适配。前置仅需 npm 基础，可与"软件工程测试"模块结合，把"让 AI 修 Bug"作为趣味入口。建议 **2 课时**，第一课时装通双轨，第二课时跑实战并讨论 Diff 审查习惯。
- **面向运维 / 网络工程师的非开发营**：部分适配。IDE 双轨环节可裁剪，聚焦 CLI 引擎 + Web App 入口；实战案例换成本专业更贴近的脚本（如日志解析）效果更佳。
- **不适用**：纯理论学习营、无任何动手环节的讲座——本教程价值在于跑通，离开终端意义减半。

## 参考来源

1. [JetBrains IDEs — Claude Code Docs](https://code.claude.com/docs/en/jetbrains) — 官方插件安装、快捷键、WSL/远程开发与安全说明。
2. [Claude Code in VS Code: Complete Setup Guide 2026 — explainx.ai](https://www.explainx.ai/blog/claude-code-vscode-ide-extension-setup-guide-2026) — VS Code 扩展五步安装与四大增强特性详解。
3. [Installing Claude Code: CLI, VS Code, JetBrains, Web & Mobile — Inbounter](https://inbounter.com/learn/claude/foundations/install-claude-code) — 全终端安装、认证两条路径与常见安装故障排查。
4. [Claude Code settings — Claude Code Docs](https://code.claude.com/docs/en/settings) — settings.json 全局/项目分层与权限配置参考。
5. [The Complete .claude Directory Guide for Claude Code [2026] — ComputingForGeeks](https://computingforgeeks.com/claude-code-dot-claude-directory-guide/) — `.claude` 目录结构与 CLAUDE.md 模块化规则实践。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)