<!-- title: 装通Claude Code接VS Code插件读懂首个工程 -->

# 装通 Claude Code 接 VS Code 插件：IDE 内读懂你的第一个工程

## 概述

本教程面向**零基础但有一点点代码阅读经验**的开发者，目标是带你走完「安装 Claude Code → 登录 → 装 VS Code 插件 → 看懂四层配置体系 → 在 IDE 内读懂一个陌生工程」的完整链路。学完后，你将不再停留在「让 AI 帮我写个新工具」，而是掌握一项被多数新手忽略的高价值技能：**用 AI 快速读懂一个你已经接手、但还没看明白的代码库**。本路线以 VS Code 图形化插件为主、命令行为辅，对终端不熟的同学最友好。

## 前置条件

在动手前，请确认你具备以下三样东西，缺一不可：

1. **一个 Claude 付费账号**：Pro、Max、Team、Enterprise 任一订阅，或 Claude Console（控制台）账号即可。**注意：用 VS Code 插件时不需要 API Key**，首次打开插件用浏览器登录账号即可——这是 2026 年版本相对早期最大的简化。
2. **VS Code 1.98.0 或更高版本**（或 Cursor、以及基于 VS Code 的分支编辑器如 Devin Desktop、Kiro）。
3. **网络可访问 claude.ai**：能打开 `https://claude.ai` 即可。Windows 用户建议额外安装 Git for Windows，这样 Claude Code 才能用 Bash 工具；WSL 用户则无需 Git for Windows。

> 小提示：如果你只想在集成终端里敲 `claude` 命令，那还需要单独安装一次 CLI（见下一步）。VS Code 插件内置了一份 CLI 给聊天面板用，但终端里那份是独立的。

---

## 第一步：安装 Claude Code CLI

Claude Code 在 2026 年的官方推荐安装方式已经从早期的 `npm install` 迁移到了**原生安装器（Native Install）**，原因是原生安装器**会在后台自动更新**，省去手动升级的烦恼。

按你的操作系统选择一条命令执行：

**macOS / Linux / WSL（推荐原生安装）：**

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

**Windows PowerShell：**

```powershell
irm https://claude.ai/install.ps1 | iex
```

**Windows CMD（传统命令提示符）：**

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

如果你更习惯包管理器，也可以：

```bash
# macOS（Homebrew，注意：不会自动更新，需手动 brew upgrade）
brew install --cask claude-code          # 稳定通道，约落后一周
brew install --cask claude-code@latest   # 最新通道，即时更新

# Windows（WinGet，同样不会自动更新）
winget install Anthropic.ClaudeCode
```

**预期结果**：命令跑完后，终端输入 `claude --version`，应能打印出形如 `2.x.x` 的版本号。

```bash
$ claude --version
2.1.181
```

**常见问题与解决**：

| 报错信息 | 原因 | 解决办法 |
|---|---|---|
| `syntax error near unexpected token '<'` | `install.sh` 被代理/防火墙篡改 | 关闭代理重试，或换用 npm 备选方式 |
| `The token '&&' is not a valid statement separator` | 你在 PowerShell 里却用了 CMD 命令 | 换用上面的 PowerShell 命令 |
| `'irm' is not recognized` | 你在 CMD 里却用了 PowerShell 命令 | 换用上面的 CMD 命令 |
| 403 / curl 错误 | 网络环境拦截了 claude.ai | 配置允许访问的代理后再装 |

> 兼容性兜底：原生安装器之外，老牌的 `npm install -g @anthropic-ai/claude-code` 仍然可用（需要先装 Node.js 18+），但官方已不作为首选。

---

## 第二步：登录账号并启动首次会话

CLI 装好后，进入任意一个你想分析的代码目录，直接敲：

```bash
cd ~/projects/some-repo
claude
```

首次运行会触发**浏览器登录流程**：

1. 终端打印一个 `https://claude.ai/oauth/...` 链接并自动尝试打开浏览器；
2. 浏览器里确认授权，复制终端回显的验证码粘贴回去；
3. 看到 `Welcome to Claude Code!` 的欢迎横幅，即登录成功。

**预期结果**：终端进入交互式会话，左下角提示当前工作目录与模型。此时你已经可以开始提问了。

**验证登录态**（可选）：执行 `claude /status` 或在会话中输入 `/status`，会显示当前账号、订阅类型、剩余用量等。这是排查「为什么我的额度没了」的第一现场。

---

## 第三步：安装 VS Code 插件并接通

这是本教程区别于「纯命令行」路线的关键一步。

**安装方式（二选一）：**

1. **快捷键安装**：在 VS Code 里按 `Cmd+Shift+X`（Mac）或 `Ctrl+Shift+X`（Windows/Linux）打开扩展面板，搜索框输入 `Claude Code`，找到 Anthropic 官方发布的那一个，点 **Install**。
2. **命令安装**：在 VS Code 命令面板（`Cmd/Ctrl+Shift+P`）输入 `Extensions: Install Extensions`，搜索安装。

**首次启动插件**：

- 安装完成后，编辑器底部状态栏会出现一个**火花图标（Spark icon）**，或活动栏多出一个 Claude 图标。
- 按 `Cmd+Esc`（Mac）/ `Ctrl+Esc`（Windows）即可唤出 Claude 聊天面板。
- 首次唤出会要求你**登录同一个 Claude 账号**（浏览器跳转，与第二步流程一致）。

**接通成功的标志**：

- 聊天面板顶部显示你的账号和当前模型；
- 面板可以 `@` 提及当前工作区里的文件；
- 你在编辑器里**选中一段代码**后，Claude 面板会自动把这段选区作为上下文（这是命令行做不到的体验）。

**常见问题**：

- **插件装不上**：先确认 VS Code ≥ 1.98.0；若用的是 VS Code 分支编辑器（如 Cursor），改从 **Open VSX 注册表**安装；若编辑器本身不支持扩展安装，退回方案是装好 CLI，在 VS Code 集成终端里直接敲 `claude`，一样能干活。
- **看不到火花图标**：重启 VS Code；或检查是否被其他扩展的图标挤到折叠区。
- **`Cmd+Esc` 无反应**（Mac）：该快捷键可能被系统/输入法占用，去 VS Code 键盘快捷方式里重新绑定 Claude 的唤起命令。
- **一直不响应**：检查网络；`/status` 看是否掉线；必要时 `/login` 重新登录。

> 插件 vs CLI 的关系：插件面板自带一份 CLI；但如果你想在 VS Code 的**集成终端**里也敲 `claude`，仍需按第一步单独安装 CLI。两者账号互通、配置共享。

---

## 第四步：看懂「四层配置体系」（重点）

这是新手最容易忽略、却最能决定体验的一环。Claude Code 的所有行为偏好，都由 `settings.json` 控制；而这些配置按**作用域（scope）**分成四层，优先级从高到低为：

```mermaid
flowchart TB
    A["Managed 托管层<br/>IT 下发 / 注册表 / plist<br/>最高优先级，不可覆盖"] --> B["CLI 命令行参数<br/>临时会话覆盖"]
    B --> C["Local 本地层<br/>.claude/settings.local.json<br/>仅本机本仓库"]
    C --> D["Project 项目层<br/>.claude/settings.json<br/>随 git 提交，团队共享"]
    D --> E["User 用户层<br/>~/.claude/settings.json<br/>个人全局，所有项目"]
    style A fill:#fde2e2,stroke:#c0392b
    style E fill:#e8f5e9,stroke:#27ae60
```

| 作用域 | 位置 | 影响范围 | 是否随团队共享 |
|---|---|---|---|
| **Managed** | 服务端托管 / 系统注册表 / plist | 全组织成员或本机所有用户 | 是（IT 部署） |
| **User** | `~/.claude/` | 你自己，跨所有项目 | 否 |
| **Project** | 仓库内 `.claude/` | 该仓库所有协作者 | 是（提交进 git） |
| **Local** | `.claude/settings.local.json` | 仅你本机、本仓库 | 否（默认 gitignore） |

**关键规则一：同名字段，高优先级覆盖低优先级。** 比如你在 User 层设了 `spinnerTipsEnabled: true`，又在 Project 层设了 `false`，最终生效的是 `false`。

**关键规则二：权限规则是「合并」而非「覆盖」。** 各层 `permissions.allow / deny` 会叠加在一起共同生效，而不是上层把下层冲掉——这点和普通字段相反，务必记住。

**修改配置的两种方式：**

1. **图形化（推荐新手）**：在会话里输入 `/config`，会弹出一个带选项卡的设置界面，能直接点选修改。
2. **命令式（v2.1.181+）**：想只改一个选项而不进界面，可以 `—config key=value`，例如 `/config verbose=true`。

**一份适合「读懂工程」场景的 User 层配置示例**（放在 `~/.claude/settings.json`）：

```json
{
  "model": "default",
  "includeCoAuthoredBy": false,
  "cleanupPeriodDays": 30,
  "env": {
    "CLAUDE_CODE_DISABLE_TERMINAL_TITLE": "1"
  },
  "permissions": {
    "allow": [
      "Read(**)",
      "Bash(git log:*)",
      "Bash(git diff:*)",
      "Bash(git show:*)",
      "Bash(ls:*)",
      "Bash(cat:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/secrets/**)"
    ]
  }
}
```

上面这份配置的用意很明确——**这是一个"只读分析"模式**：把所有读操作、只读的 git 命令放进 `allow`（不再每次弹确认），把危险删除和敏感文件读访问挡在 `deny`（即使你让它读它也不会读）。对于一个只想让 AI 帮你读懂代码、不打算让它改代码的场景，这是最省心、也最安全的起点。

> 进阶提示：`Read(./.env)` 这类规则利用了路径前缀语法，可以精确到某个目录或文件名通配。完整的「权限规则语法」可在官方 Settings 文档里查到。

---

## 第五步：配置权限模式，减少打断

除了细粒度的 allow/deny 规则，Claude Code 还提供四种**权限模式（Permission Modes）**，决定它执行操作前要不要问你。在会话中按 `Shift+Tab` 可循环切换，或在配置里固定。

| 模式 | 行为 | 适用场景 |
|---|---|---|
| **default** | 读写、运行命令前都会询问（默认） | 第一次接触陌生工程 |
| **acceptEdits** | 文件编辑自动接受，命令仍询问 | 信任其编辑、但想盯着命令 |
| **plan** | 只做计划和分析，不动文件 | **读懂工程的黄金模式** |
| **bypassPermissions** | 全部放行，不再询问 | 高风险，仅隔离环境用 |

**本教程强烈建议：在"读懂工程"阶段，固定使用 `plan` 模式。** 该模式下，Claude 只会读文件、出方案、写分析，绝不改动你的代码库——既安全，又不会被频繁的权限弹窗打断思路。

固定方法：把下面这行加进你的 User 层 `settings.json`：

```json
{
  "defaultMode": "plan"
}
```

或在某个具体会话里，按 `Shift+Tab` 切到 plan，左下角会显示当前模式。

---

## 第六步：第一个项目——在 IDE 内读懂一个陌生工程

前面五步都是铺垫。现在进入本教程的核心目标：**用 Claude Code 快速读懂一个你已经接手、但还没看明白的代码库。**

下面用一个「模拟接手一个陌生小工程」的实战，演示完整流程。你可以用任何手边的小仓库替代；这里以一个三文件的 Flask API 为例（你可以新建以下文件来复现）：

```python
# app.py
from flask import Flask, jsonify, request
from db import query_user, save_log

app = Flask(__name__)

@app.route("/user/<int:uid>", methods=["GET"])
def get_user(uid):
    user = query_user(uid)
    save_log("get_user", uid)
    if not user:
        return jsonify({"error": "not found"}), 404
    return jsonify(user)

@app.route("/health")
def health():
    return jsonify({"status": "ok"})
```

```python
# db.py
import sqlite3, os

_DB = os.environ.get("APP_DB", "app.db")

def query_user(uid):
    conn = sqlite3.connect(_DB)
    row = conn.execute("SELECT id, name, email FROM users WHERE id=?", (uid,)).fetchone()
    conn.close()
    return {"id": row[0], "name": row[1], "email": row[2]} if row else None

def save_log(action, target):
    conn = sqlite3.connect(_DB)
    conn.execute("INSERT INTO logs(action, target) VALUES(?,?)", (action, target))
    conn.commit()
    conn.close()
```

```python
# run.py
from app import app
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)
```

### 6.1 提问的正确姿势：用 @ 提及，而不是让它猜

在 VS Code 插件的聊天框里，**永远优先用 `@` 显式指文件**，而不是笼统地说"看看这个项目"。前者上下文精确、省 token、结论准；后者会触发它去全仓搜索，慢且容易漏。

输入下面这段（注意 `@` 会变成可点击的文件引用）：

```
帮我理清这个项目的整体结构。重点看 @app.py @db.py @run.py，
输出：1) 入口和路由清单 2) 每个文件的职责 3) 一次 GET /user/1 请求
从进来到返回，数据经过了哪些函数。先出方案，不要改任何文件。
```

末尾那句「先出方案，不要改任何文件」是 plan 模式下的保险栓，配合 `defaultMode: plan` 双保险。

### 6.2 预期结果：一份结构化的"交接说明"

Claude 会读这三个文件，然后输出类似下面的分析（节选）：

```
## 入口与路由
- 入口：run.py → 引入 app，监听 0.0.0.0:5000
- 路由（app.py）：
  • GET /user/<int:uid>  → get_user()
  • GET /health          → health()

## 文件职责
- app.py：HTTP 层，解析参数、组装响应、记日志
- db.py：数据访问层，封装 sqlite3 连接与查询
- run.py：启动脚本，仅 app.run()

## GET /user/1 的调用链
1. Flask 路由匹配 → get_user(uid=1)
2. app.py 调 db.query_user(1) → 连 app.db，参数化查询 users 表
3. 命中则拼 dict 返回；未命中返回 None
4. 无论命中与否，调 db.save_log("get_user", 1) 写一行日志
5. None → jsonify 404；否则 jsonify(user)
```

短短几秒，你就拥有了一份比很多交接文档都清晰的"架构说明书"。

### 6.3 追问深入：把"看懂"变成"看透"

第一次分析是骨架，追问才能挖出肉。继续输入：

```
基于上面分析，回答：
1) 这套代码有哪些明显的坏味道或风险？（每条给文件:行号）
2) save_log 的写入如果失败，会影响主请求吗？
3) 如果我要加一个"按 email 查询用户"的接口，最少改哪几处？
```

预期它会指出诸如：**每次请求都新建/关闭一次 sqlite 连接**（性能风险，`db.py:6`）；`save_log` 没有事务包裹、写失败不会回滚主流程（`app.py:10`）；新增 email 查询只需在 `db.py` 加一个 `query_user_by_email`、在 `app.py` 加一个路由（最小改动面）。

这就是"读懂工程"的真正价值：你不仅知道了代码**做了什么**，还知道了它**哪里脆弱、哪里好扩展**——而这些结论，是你逐行通读可能花一下午才能得到的。

### 6.4 利用 IDE 独有能力：选区上下文

命令行做不到、而 VS Code 插件最香的一点：**用鼠标选中一段代码，直接问**。比如你选中 `db.py` 里 `query_user` 的函数体，输入：

```
这段为什么每次都 connect + close？改成连接池的话，
改动面和风险各是什么？只分析，不写代码。
```

选区会自动作为上下文喂给 Claude，你不需要再 `@` 提及或复制粘贴。配合 plan 模式，这就是最顺手的"结对阅读"体验。

---

## 实战案例：读懂一个真实 GitHub 工程的三步法

把上面的方法提炼成可复用的三步法，适用于任何你接手的陌生仓库：

```mermaid
flowchart LR
    S1["步骤1 全局速览<br/>让它读 README + 目录树<br/>出一句话定位 + 模块清单"] --> S2["步骤2 主链路追踪<br/>@ 提及核心入口文件<br/>让它画出请求/调用主链路"]
    S2 --> S3["步骤3 风险与扩展评估<br/>追问坏味道 / 改动面<br/>锁定脆弱点和扩展点"]
    style S1 fill:#e3f2fd,stroke:#1565c0
    style S2 fill:#fff3e0,stroke:#e65100
    style S3 fill:#fde2e2,stroke:#c0392b
```

**落地示例**：随便 clone 一个你感兴趣的小型仓库（建议先挑 **star 数几百到几千、主语言单一**的中小项目，太大会让单次分析失焦），在仓库根目录打开 VS Code，启动 Claude，依次问：

1. *全局速览*——「读 @README.md，并跑一下目录结构。用一句话告诉我这个项目是干嘛的，列出主要模块。」
2. *主链路追踪*——「重点看 @主入口文件，画出一次典型用户请求从入口到结果输出的完整调用链，标注每一步在哪个文件哪个函数。」
3. *风险与扩展评估*——「基于上面的链路，指出 3 个最值得改进的地方和 3 个最容易扩展的功能点，每条附 `文件:行号`。」

三步走完，你对这个陌生工程的掌握程度，往往已经超过花一天通读源码的效果。

---

## 完整工作流程图

把从安装到读懂工程的全部步骤串起来，就是下面这张总流程：

```mermaid
flowchart TD
    A([开始]) --> B["第1步 安装 CLI<br/>curl install.sh / irm install.ps1<br/>或 brew / winget"]
    B --> C["第2步 登录账号<br/>claude → 浏览器授权<br/>/status 验证"]
    C --> D["第3步 装 VS Code 插件<br/>扩展商店搜 Claude Code<br/>Cmd+Esc 唤出面板"]
    D --> E["第4步 配置四层体系<br/>User/Project/Local/Managed<br/>写一份只读安全配置"]
    E --> F["第5步 选权限模式<br/>读懂工程固定用 plan 模式"]
    F --> G["第6步 读懂工程<br/>@ 提及 → 出链路 → 追问风险"]
    G --> H{还想深入?}
    H -- 是 --> G
    H -- 否 --> I([产出交接说明与改动清单])
    style F fill:#fff3e0,stroke:#e65100
    style G fill:#e8f5e9,stroke:#27ae60
    style I fill:#fde2e2,stroke:#c0392b
```

---

## 常见问题汇总

- **Q：一定要付费订阅吗？能不能用 API Key？** A：VS Code 插件走的是订阅登录，不需要 API Key；CLI 同理可走订阅登录。如果你用的是 Amazon Bedrock 或 Google Cloud Agent Platform 等第三方供应商，则需要按各自的第三方接入文档配置。
- **Q：为什么我每次让它读文件都要点确认？** A：你停在 `default` 模式且没配 allow 规则。按本教程第四步把 `Read(**)` 加进 `allow`，或按 `Shift+Tab` 切到 `plan` 模式，即可安静阅读。
- **Q：插件和 CLI 的配置会打架吗？** A：不会。它们共用同一套四层配置体系，`~/.claude/settings.json` 对两者都生效。
- **Q：plan 模式下它能写文件吗？** A：不能。plan 模式只做分析与方案输出，文件保持原样，最适合"读懂工程"阶段。等你真正想改代码了，再 `Shift+Tab` 切回 `default` 或 `acceptEdits`。
- **Q：原生安装器和 Homebrew 装的有什么区别？** A：原生安装器后台自动更新；Homebrew 的不会，需要你定期 `brew upgrade claude-code`。WinGet 同理需手动升级。

---

## 延伸阅读

- **官方快速入门**（终端 CLI 全流程）：`https://code.claude.com/docs/en/quickstart`——本文安装步骤的权威出处。
- **官方 VS Code 集成文档**：`https://code.claude.com/docs/en/vs-code`——插件安装、快捷键、常见故障的官方说明。
- **官方设置文档**：`https://code.claude.com/docs/en/settings`——四层配置体系、作用域优先级、权限规则语法的完整定义。
- **官方权限文档**：`https://code.claude.com/docs/zh-CN/permissions`——四种权限模式、allow/ask/deny 工作机制。
- 进阶方向（后续可学）：CLAUDE.md 项目记忆、Skills 自定义技能、MCP 外部工具接入、`-p` 无头模式——它们都是建立在"装通 + 配好 + 读懂"之上的高级玩法。

---

## 训练营适用性评估

- **适合的训练营类型**：AI 编程入门营、新人入职 / 代码交接训练营、技术债治理与代码阅读营。不要求学员有强命令行背景，VS Code 图形化路线对转岗、跨语言接手老项目的开发者尤其友好。
- **预计教学时长**：1 个半天到 1 天（约 3–5 小时）。其中安装与登录 0.5 小时、配置体系讲解与动手 1.5 小时、读懂工程实战 2 小时、答疑与延伸 1 小时。
- **考核建议**：让每位学员自带一个陌生小仓库，按"三步法"产出一份包含「项目定位 + 主调用链 + 3 个风险点」的交接说明文档，作为结业产出。
- **衔接建议**：作为整套 Claude Code 训练营的**第 1 课**最合适——先建立"安全配置 + 读懂工程"的地基，后续再讲 Skills、MCP、自动化才有意义。

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方快速入门，安装方式（原生安装器/Homebrew/WinGet）与首次会话流程的权威出处。
2. [Use Claude Code in VS Code - Claude Code Docs](https://code.claude.com/docs/en/vs-code) — 官方 VS Code 插件文档，涵盖版本要求、安装、@-提及、计划审查与故障排查。
3. [Claude Code settings - Claude Code Docs](https://code.claude.com/docs/en/settings) — 官方设置文档，四层作用域（Managed/User/Project/Local）优先级与 `/config` 用法。
4. [配置权限 - Claude Code Docs](https://code.claude.com/docs/zh-CN/permissions) — 官方权限文档，四种权限模式与 allow/deny 规则语法。
5. [Claude Code settings.json 配置模板：env、模型、认证等实用字段速查](https://blog.vincentqiao.com/posts/claude-code-settings-misc/) — 技术博客，settings.json 常用字段速查与可复制配置示例。

> [!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)