# Claude Code双栖工作流：终端到VS Code全实战
## 概述
本教程面向零基础到进阶用户，系统讲解Claude Code在**终端CLI**和**VS Code扩展**两种环境下的完整使用方法。你将学会安装配置、核心快捷键、双环境无缝切换策略，以及通过一个真实项目验证双栖工作流的协同威力。学完后你能在终端和IDE之间自如切换，发挥各自场景优势。
**适用人群**：初次接触Claude Code的开发者、想从终端迁移到IDE的用户、追求工作流效率的团队工程师。
## 前置条件
| 项目 | 要求 |
|------|------|
| 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10+（WSL2） |
| Node.js | v18+（推荐v20 LTS） |
| 编辑器 | VS Code 1.85+（可选，用于IDE工作流） |
| 账户 | Anthropic Console账户，已绑定付款方式 |
| 网络 | 能访问`api.anthropic.com`和`registry.npmjs.org` |
---
## 第一章：双栖架构全景理解
### 1.1 Claude Code的三种运行形态
Claude Code在2026年提供三种入口，理解它们的区别是双栖工作流的基础：
```mermaid
graph TB
subgraph "Claude Code 运行形态"
A[CLI终端模式
claude命令]
B[VS Code扩展
内嵌终端]
C[Desktop桌面应用
独立GUI]
end
subgraph "共享核心"
D[Anthropic API]
E[项目上下文
CLAUDE.md]
F[MCP服务器]
G[Skills系统]
end
A --> D
B --> D
C --> D
A --> E
B --> E
C --> E
A --> F
B --> F
C --> F
A --> G
B --> G
C --> G
style A fill:#4A90D9,color:#fff
style B fill:#007ACC,color:#fff
style C fill:#D4553A,color:#fff
```
**终端CLI模式**是完整功能集，支持所有标志位、管道模式、Hook系统。**VS Code扩展**在终端功能基础上增加了可视化Diff、一键接受/拒绝、文件跳转等IDE增强。**Desktop桌面应用**提供独立GUI，无需终端操作。
核心差异对照：
| 特性 | 终端CLI | VS Code扩展 | Desktop应用 |
|------|---------|-------------|-------------|
| 安装方式 | `npm install -g @anthropic-ai/claude-code` | VS Code Marketplace安装 | 独立dmg/exe安装 |
| 可视化Diff | 纯文本渲染 | 侧栏对比视图 | 侧栏对比视图 |
| 文件导航 | 手动路径 | Ctrl+Click跳转 | 鼠标点击跳转 |
| 管道模式 | 支持`-p`、`-c` | 不支持 | 不支持 |
| Hook触发 | 完整支持 | 完整支持 | 完整支持 |
| 多终端标签 | 原生tmux | VS Code终端 | 独立窗口 |
| 后台Agent | 支持 | 支持 | 支持 |
### 1.2 为什么需要双栖
终端擅长**批处理、自动化、管道操作**。IDE擅长**代码审查、文件浏览、可视化Diff**。一个高效的Claude Code用户不是二选一，而是根据任务性质在两种环境间无缝切换。
典型场景分配：
- **终端优先**：批量重构、CI/CD集成、自动化脚本、`-p`管道模式
- **IDE优先**：UI组件开发、多文件审查、复杂调试、代码审查
- **混合使用**：大型功能开发（IDE写代码 + 终端跑测试）
---
## 第二章：终端CLI完整安装与配置
### 2.1 安装Claude Code CLI
```bash
# 确认Node.js版本
node --version # 需要 v18+
# 全局安装Claude Code
npm install -g @anthropic-ai/claude-code
# 验证安装
claude --version
# 预期输出：Claude Code v2.x.x
```
**常见问题**：
| 问题 | 原因 | 解决方案 |
|------|------|----------|
| `EACCES: permission denied` | npm全局目录权限不足 | 使用`nvm`管理Node版本，避免`sudo` |
| `command not found: claude` | npm bin不在PATH中 | 运行`npm config get prefix`确认路径，添加到`~/.bashrc` |
| 安装卡在`node-gyp` | 缺少编译工具 | Ubuntu: `sudo apt install build-essential` |
| 速度过慢 | npm默认源在国外 | 使用镜像：`npm config set registry https://registry.npmmirror.com` |
### 2.2 首次认证
```bash
# 启动认证流程
claude
# 首次运行会提示：
# > Welcome to Claude Code!
# > Please authenticate by visiting:
# > https://console.anthropic.com/login?code=XXXX-XXXX
```
浏览器打开URL，登录Anthropic Console后自动完成认证。认证信息保存在`~/.claude/credentials.json`。
**替代认证方式**（适用于无浏览器环境）：
```bash
# 使用API Key
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
claude
# 或使用配置文件
echo '{"apiKey":"sk-ant-xxxxx"}' > ~/.claude/credentials.json
```
### 2.3 项目初始化
```bash
# 创建项目目录
mkdir my-first-claude-project && cd my-first-claude-project
# 初始化Claude Code配置
claude /init
# Claude会自动生成：
# - CLAUDE.md（项目级配置文件）
# - .claude/settings.json（本地设置）
# - .claude/目录结构
```
`/init`命令执行时会分析项目结构，生成针对性的CLAUDE.md。如果项目是空的，它会生成一个通用模板。
### 2.4 核心终端快捷键速查
掌握这些快捷键是终端高效操作的基础：
```
┌─────────────────────────────────────────────────────┐
│ Claude Code 终端快捷键 │
├──────────────────┬──────────────────────────────────┤
│ Escape │ 中断当前生成，进入输入模式 │
│ Shift + Tab │ 切换到Auto-accept模式（自动执行） │
│ Tab │ 切换到Normal模式（需确认执行） │
│ Ctrl + C │ 强制中断当前操作 │
│ Ctrl + G │ 在Diff视图中拒绝所有更改 │
│ Enter │ 确认/发送消息 │
│ @ │ 引用文件：@src/app.ts │
│ / │ 触发斜杠命令菜单 │
│ ↑ / ↓ │ 浏览历史消息 │
│ Ctrl + L │ 清屏 │
└──────────────────┴──────────────────────────────────┘
```
**模式切换**是终端工作流的核心概念。Claude Code有两种输入模式：
- **Normal模式（默认）**：Claude生成的命令和文件修改需要你按Enter确认才执行
- **Auto-accept模式（Shift+Tab）**：Claude自动执行所有操作，无需逐一确认
新手建议先用Normal模式，熟悉后再切换Auto-accept提高效率。
---
## 第三章：VS Code扩展安装与配置
### 3.1 安装扩展
```bash
# 方式一：命令行安装
code --install-extension anthropic.claude-code
# 方式二：VS Code内安装
# 1. 打开VS Code
# 2. 侧栏点击 Extensions（Ctrl+Shift+X）
# 3. 搜索 "Claude Code"
# 4. 点击 Install（发布者：Anthropic）
```
安装完成后，VS Code底部状态栏会出现Claude图标，侧栏面板出现Claude Code标签。
### 3.2 VS Code特有快捷键
```
┌─────────────────────────────────────────────────────┐
│ VS Code 扩展快捷键 │
├──────────────────┬──────────────────────────────────┤
│ Ctrl+Shift+C │ 打开Claude Code面板 │
│ Ctrl+Shift+P → │ 命令面板输入"Claude" │
│ "Claude: ..." │ 查看所有Claude命令 │
│ Alt+A │ 接受当前Diff │
│ Alt+R │ 拒绝当前Diff │
│ Ctrl+Click │ 跳转到Claude提到的文件/行号 │
│ Ctrl+Shift+Tab │ 在Diff视图中切换新旧文件 │
└──────────────────┴──────────────────────────────────┘
```
### 3.3 VS Code中的可视化Diff体验
VS Code扩展的核心优势在于**可视化Diff**。当Claude修改文件时，你会看到：
1. 左侧是原始文件，右侧是Claude修改后的版本
2. 修改部分高亮显示，删除行用红色标记，新增行用绿色标记
3. 每个修改块上方有`Accept`和`Reject`按钮
4. 点击文件名可直接跳转到编辑器中对应位置
这种体验相比终端的纯文本Diff，**审查效率提升约3倍**（社区实测数据）。
### 3.4 工作区设置
在项目根目录创建`.vscode/settings.json`，优化Claude Code体验：
```json
{
"claude-code.autoAccept": false,
"claude-code.contextFiles": [
"CLAUDE.md",
"README.md",
"package.json"
],
"claude-code.terminal.integrated": true,
"claude-code.diff.renderSideBySide": true
}
```
---
## 第四章：双栖协同工作流设计
### 4.1 共享配置层
终端和VS Code共享同一套配置体系。理解配置的加载优先级是双栖协同的关键：
```mermaid
graph TD
A[~/.claude/CLAUDE.md
全局用户指令] --> E[最终生效配置]
B[项目根/CLAUDE.md
项目级指令] --> E
C[项目根/.claude/settings.json
本地设置] --> E
D[项目根/.claude/settings.local.json
个人本地设置] --> E
F[~/.claude/settings.json
全局设置] --> E
style A fill:#4A90D9,color:#fff
style B fill:#2ECC71,color:#fff
style C fill:#E67E22,color:#fff
style D fill:#9B59B6,color:#fff
style E fill:#E74C3C,color:#fff
style F fill:#34495E,color:#fff
```
**关键点**：无论你在终端还是VS Code中修改CLAUDE.md，另一个环境下次启动都会读取最新内容。这意味着你可以用任何一种环境管理项目配置。
### 4.2 CLAUDE.md双栖模板
以下是一个适配双栖工作流的CLAUDE.md模板：
```markdown
# 项目：MyApp
## 技术栈
- Frontend: React 19 + TypeScript 5.7
- Backend: Node.js 22 + Express
- Database: PostgreSQL 16
- Testing: Vitest + Playwright
## 代码规范
- 使用函数式组件，禁止class组件
- API路由遵循RESTful规范
- 所有函数必须有TypeScript类型注解
- 测试覆盖率不低于80%
## 工作流规则
- 修改代码后必须运行相关测试
- 不要自动commit
- 优先编辑现有文件，避免创建新文件
- 终端命令使用绝对路径
## 项目结构
- src/components/ — React组件
- src/api/ — API路由和控制器
- src/models/ — 数据模型
- tests/ — 测试文件
```
### 4.3 双环境切换时机决策树
```mermaid
graph TD
A[新任务到达] --> B{任务类型？}
B -->|创建/修改UI| C[VS Code扩展
可视化Diff审查]
B -->|批量重构10+文件| D[终端CLI
Auto-accept模式]
B -->|CI/CD/自动化| E[终端CLI
-p管道模式]
B -->|代码审查/理解| F{文件数量？}
F -->|1-3个文件| G[VS Code扩展
单文件跳转]
F -->|4+个文件| H[终端CLI
全局视图]
C --> I[完成]
D --> I
E --> I
G --> I
H --> I
style C fill:#007ACC,color:#fff
style D fill:#4A90D9,color:#fff
style E fill:#E67E22,color:#fff
style G fill:#007ACC,color:#fff
style H fill:#4A90D9,color:#fff
```
### 4.4 实战切换技巧
**从终端切换到VS Code**：
```bash
# 终端中完成批量操作后，打开VS Code审查
claude "已完成批量重构，请总结所有修改"
code . # 打开VS Code手动检查
```
**从VS Code切换到终端**：
在VS Code的Claude面板中，所有操作等价于终端操作。但某些高级功能需要切换到终端：
```bash
# VS Code内置终端（Ctrl+`）中执行
claude -p "分析这个项目的测试覆盖率" < test-output.txt
# 或者使用管道模式生成报告
claude -p "生成这个项目的API文档" --output-format json > api-docs.json
```
---
## 第五章：核心斜杠命令双栖实战
斜杠命令是Claude Code的灵魂。以下是最常用的命令在两种环境中的使用方式：
### 5.1 会话管理命令
| 命令 | 功能 | 终端用法 | VS Code用法 |
|------|------|----------|-------------|
| `/init` | 初始化项目配置 | 输入`/init`回车 | 面板中输入`/init` |
| `/compact` | 压缩上下文窗口 | 输入`/compact` | 面板中输入`/compact` |
| `/clear` | 清空会话历史 | 输入`/clear` | 面板中输入`/clear` |
| `/cost` | 显示Token消耗 | 输入`/cost` | 面板中输入`/cost` |
| `/review` | 代码审查模式 | 输入`/review` | 面板中输入`/review` |
### 5.2 `/compact`：上下文管理关键命令
`/compact`是长会话的救星。Claude Code的上下文窗口约为200K token，一个2-4小时的工作会话可能耗尽上下文。
```
你：/compact
Claude：我来压缩当前上下文...
- 保留：项目结构、CLAUDE.md指令、最近10轮对话摘要
- 移除：中间步骤的详细输出、已完成的工具调用详情
- 上下文从 142,000 token 压缩到 48,000 token
- 压缩率：66%
```
**双栖策略**：
- **终端**：每完成一个大任务后执行`/compact`
- **VS Code**：面板上方有上下文使用率指示器，超过70%时主动压缩
### 5.3 `/review`：代码审查双栖对比
**终端模式**：
```bash
# 审查当前所有未提交的更改
claude "/review 我准备提交这些更改，请检查是否有问题"
# 输出是纯文本，包含文件名、行号、问题描述
```
**VS Code模式**：
```
# 在Claude面板中输入
/review 检查最近的更改
# Claude会自动打开Diff视图
# 每个问题标记在对应文件位置
# Ctrl+Click直接跳转到问题代码
# 可以逐个Accept/Reject建议的修复
```
VS Code的`/review`体验明显更优：可视化标记+一键跳转+逐条处理。
---
## 第六章：实战项目——双栖协同构建Todo应用
### 6.1 项目概述
我们将构建一个全栈Todo应用，刻意在终端和VS Code之间切换，体验双栖工作流。
**技术栈**：React + Vite + TypeScript + JSON文件存储
### 6.2 Step 1：终端创建项目骨架
```bash
# 在终端中用Claude Code创建项目
mkdir todo-app && cd todo-app
claude
# 交互式输入：
> 使用Vite创建一个React + TypeScript项目，项目名是todo-app。
> 功能需求：添加待办事项、标记完成、删除、过滤（全部/已完成/未完成）。
> 数据持久化用localStorage。样式用CSS Modules。
# Claude会执行：
# 1. npm create vite@latest . -- --template react-ts
# 2. 创建组件文件结构
# 3. 实现所有功能
```
**预期结果**：Claude自动运行`npm create vite`，创建项目结构，生成所有组件代码。
### 6.3 Step 2：VS Code审查和调整UI
```bash
# 打开VS Code
code .
```
在VS Code中：
1. **Ctrl+Shift+C** 打开Claude面板
2. 输入：`审查src/App.tsx和src/components/目录下的所有文件，改进UI样式使其更现代`
3. Claude生成修改方案，在侧栏Diff视图中逐一审查
4. 用**Alt+A**接受好的修改，**Alt+R**拒绝不满意的
5. **Ctrl+Click**跳转到具体代码行微调
### 6.4 Step 3：终端添加测试
```bash
# 回到终端（VS Code内置终端即可）
claude
> 为所有组件添加Vitest测试，覆盖以下场景：
> - 添加新待办事项
> - 标记待办事项为完成
> - 删除待办事项
> - 过滤器切换
> 目标覆盖率80%以上。
> 完成后运行测试验证全部通过。
# 使用Normal模式，逐一确认Claude创建的测试文件
```
### 6.5 Step 4：双栖联合调试
当测试失败时：
1. **终端**查看失败信息：
```
> 测试失败了，请分析原因并修复
Claude：分析测试输出...
- TodoList组件的filter逻辑在边界情况下有bug
- 修复方案：修改filter函数...
```
2. **VS Code**验证修复：
- Ctrl+Click跳转到修改的文件
- 在Diff视图中确认修复逻辑
- 手动在浏览器中验证UI表现
### 6.6 Step 5：终端生成最终报告
```bash
# 管道模式生成项目报告
claude -p "生成这个项目的技术文档，包括：项目结构、组件说明、API接口、运行方式" \
--output-format markdown > PROJECT.md
# 检查最终测试覆盖率
claude -p "运行测试并报告覆盖率"
```
### 6.7 完整工作流流程图
```mermaid
sequenceDiagram
participant T as 终端CLI
participant V as VS Code扩展
participant G as Git仓库
Note over T: Step 1: 创建项目骨架
T->>T: claude + /init
T->>T: 生成项目结构
T->>G: git init + 首次提交
Note over V: Step 2: UI审查调整
V->>V: 打开Claude面板
V->>V: Diff视图审查样式修改
V->>G: Alt+A接受 + 保存
Note over T: Step 3: 添加测试
T->>T: claude创建测试文件
T->>T: 运行vitest验证
Note over T,V: Step 4: 联合调试
T->>T: 分析测试失败原因
T->>V: 切换到VS Code验证
V->>V: Ctrl+Click跳转
V->>G: 确认修复提交
Note over T: Step 5: 生成报告
T->>T: claude -p 管道模式
T->>G: 最终提交
```
---
## 第七章：高级双栖技巧
### 7.1 同步运行双环境
一个强大的策略是**同时运行终端和VS Code的Claude Code**：
```bash
# 终端1：运行开发服务器和测试
claude "监控测试，每次文件变更自动运行相关测试"
# VS Code：同时进行代码编辑和审查
# 在Claude面板中：审查当前修改、优化代码
```
两个环境共享同一个项目上下文（CLAUDE.md），但各自维护独立的会话。这意味着你可以让一个环境做"监控"工作，另一个做"创作"工作。
**注意事项**：
- 两个环境不能同时修改同一文件
- 使用Git来协调：一个环境提交后，另一个环境`git pull`
- 会话独立意味着各自有独立的上下文窗口
### 7.2 终端独有：管道模式批量操作
```bash
# 批量代码审查
for file in src/**/*.ts; do
claude -p "审查这个文件的安全问题：$(cat $file)" --output-format json
done | jq '.issues[]' > security-report.json
# 自动生成测试
find src -name "*.tsx" ! -name "*.test.tsx" | while read f; do
test_file="${f%.tsx}.test.tsx"
claude -p "为 $f 生成测试文件" > "$test_file"
done
```
### 7.3 VS Code独有：文件上下文拖拽
在VS Code中，你可以直接从资源管理器拖拽文件到Claude面板中，自动附加文件内容作为上下文。这比终端的`@文件名`方式更直观，特别是需要同时引用多个文件时。
### 7.4 Hook系统双栖通用
Hook在终端和VS Code中同样生效。在`.claude/settings.json`中配置：
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"command": "npx eslint --fix $FILE_PATH 2>/dev/null"
}
],
"PreCommit": [
{
"command": "npm test -- --run"
}
]
}
}
```
这个Hook在Claude修改任何文件后自动运行ESLint修复，在提交前自动运行测试。无论你用终端还是VS Code，Hook都会触发。
---
## 第八章：常见问题与排障
### 8.1 双环境常见问题
| 问题 | 环境 | 原因 | 解决方案 |
|------|------|------|----------|
| VS Code中Claude面板空白 | VS Code | CLI未安装 | 先`npm install -g @anthropic-ai/claude-code` |
| 终端中文乱码 | 终端 | 编码问题 | `export LANG=en_US.UTF-8` |
| Diff视图不显示 | VS Code | 文件未保存 | 先保存文件再触发Claude |
| 上下文耗尽 | 两者 | 会话过长 | 执行`/compact`或`/clear` |
| 修改冲突 | 双环境 | 同时编辑同一文件 | 避免并行编辑，用Git协调 |
| MCP服务器不连接 | 两者 | 配置错误 | 运行`/mcp`检查状态 |
### 8.2 性能优化建议
1. **大项目**：在CLAUDE.md中用`## 项目结构`明确目录用途，减少Claude探索范围
2. **长会话**：每30-60分钟执行一次`/compact`，保持上下文新鲜度
3. **多文件修改**：用Auto-accept模式（Shift+Tab）加速，定期Git commit作为检查点
4. **网络延迟**：VS Code扩展默认使用流式响应，体验更平滑
---
## 延伸阅读
- [Claude Code官方文档](https://code.claude.com/docs/en/quickstart) — Anthropic维护的完整参考
- [Claude Code VS Code集成指南](https://code.claude.com/docs/en/vs-code) — 官方IDE设置教程
- [Claude Code上下文管理最佳实践](https://www.anthropic.com/blog/using-claude-code-session-management-and-1m-context) — Anthropic官方博客
- [Claude Code Cheat Sheet 2026](https://computingforgeeks.com/claude-code-cheat-sheet/) — 社区维护的速查表
---
## 训练营适用性评估
| 维度 | 评估 |
|------|------|
| 适合训练营类型 | AI编程入门营、全栈开发训练营、企业AI工具培训 |
| 预计教学时长 | 3-4小时（含实操练习） |
| 难度等级 | ⭐⭐（初级） |
| 实操占比 | 70%（大量动手练习） |
| 最低硬件要求 | 8GB RAM、稳定网络、Node.js环境 |
| 建议分组 | 每组2-3人，一人操作终端、一人操作IDE，交叉验证 |
---
## 参考来源
1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic官方快速入门文档，涵盖CLI安装和首次使用
2. [Use Claude Code in VS Code - Claude Code Docs](https://code.claude.com/docs/en/vs-code) — 官方VS Code扩展安装与配置指南
3. [Using Claude Code: session management and 1M context](https://claude.com/blog/using-claude-code-session-management-and-1m-context) — Anthropic官方博客，详解上下文管理策略
4. [Claude Code Cheat Sheet - Shortcuts, Commands, Tips (2026)](https://computingforgeeks.com/claude-code-cheat-sheet/) — 社区维护的完整快捷键和命令速查表
5. [Claude Code in VS Code vs Terminal: Complete Setup Guide](https://www.segevsinay.com/blog/claude-code-in-vs-code-vs-terminal-complete-setup-guide) — 终端与VS Code对比分析，含双环境协同建议
> [!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 等场景全覆盖。
