🧠 Claude Code VSCode 插件完整使用指南
适用场景： Windows 10/11 + VSCode + Qt C++ 桌面开发 + DeepSeek V4 Pro
目标： 一份可以直接照着配、照着用的实战手册
老规矩，先看效果
📖 目录
- [什么是 Claude Code？](#什么是 Claude Code？)
- 安装与配置
- [VSCode 插件使用详解](#VSCode 插件使用详解)
- [切换模型：配置 DeepSeek V4 Pro](#切换模型：配置 DeepSeek V4 Pro)
- [Qt/C++ 开发实战技巧](#Qt/C++ 开发实战技巧)
- [CLAUDE.md 项目记忆文件](#CLAUDE.md 项目记忆文件)
- [Slash 命令大全](#Slash 命令大全)
- [Windows 注意事项](#Windows 注意事项)
- 社区资源汇总
- 常见问题排错
1. 什么是 Claude Code？
Claude Code 是 Anthropic 推出的 AI 编程助手，有两种形态：
| 形态 | 说明 | 适用场景 |
|---|---|---|
| CLI 版本 | 终端 TUI 交互，claude -p "..." |
自动化、CI/CD、批量任务 |
| VSCode 插件 | 编辑器内嵌，Ctrl+Shift+P 启动 |
日常编码、对话式开发 ← 你用这个 |
关键区别：VSCode 插件直接在编辑器内工作，能看到你的文件树、打开的文件、终端输出；CLI 版本在独立终端中运行。
Claude Code 支持的工作模式
| 模式 | 说明 |
|---|---|
| 对话模式 | 像聊天一样描述需求，Claude 帮你写/改代码 |
| 内联编辑 | 选中代码，按 Ctrl+I 直接让 AI 修改 |
| 代码审查 | /review 自动审查当前改动 |
| Debug | 粘贴编译错误，自动定位修复 |
| Plan/Act | 先出方案再执行（CLI 端支持更完善） |
2. 安装与配置
2.1 前置依赖
powershell
# 1. 安装 Node.js 18+ （推荐 LTS 版本）
# 下载：https://nodejs.org/
# 验证：
node --version # 必须 ≥ 18.x
# 2. VSCode 确保是最新版
# 下载：https://code.visualstudio.com/2.2 安装 VSCode 插件
方式一：VSCode 内安装（推荐）
1. 打开 VSCode
2. 按 Ctrl+Shift+X 打开扩展面板
3. 搜索 "Claude Code"
4. 找到 Anthropic 官方的 "Claude Code" 插件
5. 点击安装方式二：命令行安装
powershell
code --install-extension anthropic.claude-code方式三：通过 VSIX 离线安装
如果内网环境，从 Marketplace 下载 .vsix 后：
Extensions → ... → Install from VSIX...2.3 获取 API Key
Claude Code 默认使用 Anthropic 的 Claude 模型，需要：
1. 访问 https://console.anthropic.com/
2. 注册/登录账号
3. 进入 API Keys 页面
4. 创建新的 API Key
5. 复制保存（只显示一次）💡 如果你想用 DeepSeek V4 Pro（详见第4节），也需要 DeepSeek 的 API Key
2.4 配置 API Key
方法一：环境变量（推荐）
powershell
# Windows PowerShell（加到 $PROFILE 永久生效）
$env:ANTHROPIC_API_KEY = "sk-ant-xxxxxxxx"方法二：VSCode 设置
Ctrl+Shift+P → "Preferences: Open Settings (JSON)"
添加：
"claude.apiKey": "sk-ant-xxxxxxxx"⚠️ 安全提醒：不要把 API Key 写在代码里或传到 Git 仓库中
3. VSCode 插件使用详解
3.1 启动会话
| 操作 | 说明 |
|---|---|
Ctrl+Shift+P → Claude Code: Start session |
启动新会话 |
Ctrl+Shift+P → Claude Code: New chat |
新建对话 |
Ctrl+Shift+P → Claude Code: Resume session |
恢复上次会话 |
3.2 对话式编程
启动后，VSCode 侧边栏或独立面板会打开对话窗口。你可以：
text
// 示例：让 Claude Code 帮你写 Qt 代码
// 在对话中输入：
"帮我创建一个 QMainWindow 子类，包含一个 QTableView
和一个 QPushButton，点击按钮弹出文件选择对话框"Claude Code 会：
- 理解你的需求
- 在编辑器中创建/修改文件
- 展示 diff 改动
- 等待你确认或继续修改
3.3 内联编辑（最常用的功能）
1. 在代码编辑器中选中一段代码
2. 按 Ctrl+I（或右键 → Claude Code → Edit）
3. 输入修改要求，例如：
"改用 QStyledItemDelegate 实现自定义绘制"
4. Claude 直接在当前文件上修改3.4 代码解释
1. 选中代码
2. 右键 → Claude Code → Explain
3. Claude 弹出解释面板，逐行说明代码逻辑3.5 终端集成
Claude Code 可以在 VSCode 内置终端中执行命令：
text
# 在对话中输入：
"运行 cmake --build build，如果出错帮我分析修复"⚠️ Claude 执行命令前会请求你的确认（安全机制）
4. 切换模型：配置 DeepSeek V4 Pro
4.1 官方支持情况
Claude Code 默认只支持 Claude 系列模型（Sonnet/Opus/Haiku）。
但 Anthropic 在 2025 年底开放了 第三方 Provider 支持，只要是兼容 OpenAI API 格式 的 endpoint 都可以配置。
✅ DeepSeek V4 Pro 属于此列（兼容 OpenAI API 格式）
4.2 配置 DeepSeek V4 Pro 的方法
方法一：通过环境变量（最简单）
powershell
# Windows PowerShell
$env:ANTHROPIC_API_KEY = "" # 清空 Claude Key
$env:OPENAI_API_KEY = "sk-your-deepseek-key" # DeepSeek API Key
$env:OPENAI_BASE_URL = "https://api.deepseek.com/v1"
$env:OPENAI_MODEL = "deepseek-chat" # DeepSeek V4 Pro 模型名
# 验证
echo $env:OPENAI_API_KEY方法二：通过 settings.json
json
// 项目 .claude/settings.json 或全局 ~/.claude/settings.json
{
"provider": "openai-compatible",
"openaiApiKey": "sk-your-deepseek-key",
"openaiBaseUrl": "https://api.deepseek.com/v1",
"model": "deepseek-chat",
"maxOutputTokens": 8192,
"temperature": 0.3
}方法三：通过 OpenRouter（备选）
powershell
# OpenRouter 作为中间层（支持更多模型）
$env:OPENAI_API_KEY = "sk-or-your-openrouter-key"
$env:OPENAI_BASE_URL = "https://openrouter.ai/api/v1"
$env:OPENAI_MODEL = "deepseek/deepseek-chat"4.3 DeepSeek V4 Pro 的调优参数
| 参数 | 推荐值 | 说明 |
|---|---|---|
temperature |
0.1~0.3 | 编码场景偏低，保持一致性 |
max_tokens |
8192~16384 | Qt C++ 代码较长，给够空间 |
top_p |
0.9 | 默认即可 |
frequency_penalty |
0 | 不惩罚重复（代码中重复是正常的） |
4.4 已知限制
| 问题 | 说明 |
|---|---|
| Tool-calling 能力 | DeepSeek 的 tool call 不如 Claude 原生精准，refactor 复杂代码时需多轮对话 |
/init 等命令 |
部分高级命令（如初始化 CLAUDE.md）可能需要 Claude API Key |
| 长上下文 | DeepSeek 64K 够用，但如果项目极大可能需要 /compact 压缩 |
| Artifact 预览 | 部分 artifact 功能需 Claude 原生模型 |
💡 推荐策略 ：日常编码用 DeepSeek V4 Pro （便宜、速度快），复杂架构设计/大规模重构时切换到 Claude Sonnet 4
5. Qt/C++ 开发实战技巧
5.1 让 Claude Code 理解你的 Qt 项目
关键是写好 CLAUDE.md（详见下一节），告诉 Claude：
markdown
## Project Structure
- 使用 CMake 3.16+ 构建系统
- Qt 5.15.2 版本，模块：Widgets, Core, Gui, Network, Sql
- 使用 MSVC 2022 编译器（x64）
- 配合 Qt Visual Studio Tools 或 CMake Presets5.2 常见编码场景
场景：创建 Qt 界面
"创建一个 QDialog，布局如下：
- 顶部 QLabel 标题
- 中间 QStackedWidget 放多个页面
- 底部 QDialogButtonBox（确定/取消）
- 使用 QVBoxLayout 整体布局"场景：连接信号槽
"帮我将 m_connectBtn 的 clicked 信号连接到
onConnect() 槽函数，并在连接前检查网络状态"场景：处理编译错误
// 把 MSVC 编译错误直接粘贴到对话中
"error C2664: 'QObject::connect':
无法将参数 2 从 'overload' 转换为 ...
帮我修复这个信号槽重载歧义问题"场景：添加 CMake 模块
"在 CMakeLists.txt 中添加 Qt Network 模块支持
并链接到目标"5.3 高效率工作流（推荐）
日常开发循环（建议）：
1. 启动 Claude Code 会话
2. 描述本次要开发的功能（一句话说清）
3. Claude 生成代码 → 审查 diff
4. 请求编译检查：cmake --build build
5. 粘贴编译错误 → Claude 自动修复
6. 手动运行验证
7. 提交代码5.4 进阶技巧
| 技巧 | 说明 |
|---|---|
| 分模块对话 | 每次会话专注一个模块（如"帮我实现这个 Dialog"），不要混在一起 |
| 粘贴编译输出 | MSVC 错误信息直接粘贴，Claude 能精确定位错误行 |
| 指定 Qt 版本 | 对话中提到 Qt5/Qt6 避免误用不兼容 API |
| .ui 文件不动 | 在 CLAUDE.md 中声明禁止修改 .ui 文件，否则会破坏 Designer 编辑 |
| Q_OBJECT 宏 | Claude 知道需要这个宏，但偶尔会漏，检查一下 |
| moc 文件 | CMake 会自动处理 moc，Claude 不需要手动插入 |
| 头文件顺序 | 提醒 Claude 按 Qt 头文件 → 项目头文件 → 标准库的顺序 |
6. CLAUDE.md 项目记忆文件
CLAUDE.md 是 Claude Code 的项目级配置文件，放在项目根目录，每次会话自动加载。
6.1 配置文件位置与优先级
| 位置 | 作用域 | 优先级 |
|---|---|---|
~/CLAUDE.md |
全局（所有项目生效） | 低 |
项目根目录/CLAUDE.md |
项目级（推荐） | 高 |
项目根目录/.claude/CLAUDE.md |
项目级（新格式） | 中 |
6.2 Qt/C++ 项目 CLAUDE.md 模板
markdown
# CLAUDE.md --- 项目名称
## 项目概述
- 类型：Qt C++ 桌面应用程序
- Qt 版本：5.15.2
- 构建系统：CMake 3.16+
- 编译器：MSVC 2022 (x64) / MinGW (备选)
- 平台：Windows（主目标），Linux（交叉编译）
## 目录结构project/
├── src/ # 源码
│ ├── ui/ # Qt Designer .ui 文件（勿自动修改）
│ ├── models/ # 数据模型
│ └── widgets/ # 自定义控件
├── resources/ # .qrc 资源文件
├── build/ # 构建输出
└── CMakeLists.txt # 主构建文件
## 编码规范
- 变量命名：camelCase（如 `mainWindow`）
- 类命名：PascalCase（如 `MainWindow`）
- 使用 `QString` 而非 `std::string`
- 信号槽使用新语法：`connect(sender, &Class::signal, receiver, &Class::slot)`
- 禁止裸 `new`/`delete`，使用智能指针或 Qt 对象树
- 注释：公开接口使用 Doxygen 风格
## 构建命令
- 构建：`cmake --build build --config Debug`
- 清理：`cmake --build build --target clean`
- 运行：`./build/Debug/app.exe`
## 规则
- ❌ 不要修改 `.ui` 文件（除非我特别要求）
- ❌ 不要移除 `Q_OBJECT` 宏
- ✅ 建议添加 `#include` 头文件
- ✅ 建议修复编译器警告
## 模型配置
- Provider: openai-compatible
- Model: deepseek-chat
- Base URL: https://api.deepseek.com/v16.3 CLAUDE.md 最佳实践
- 越具体越好 --- 不要写"写好代码"，要写"使用 QString 而非 std::string"
- 包含目录结构 --- Claude 读不到文件树时，目录结构能帮它理解项目
- 包含构建命令 --- Claude 可以直接帮你编译
- 设置规则/限制 --- 明确禁止的操作（如修改 .ui 文件）
- 定期更新 --- 项目结构变化时同步更新
7. Slash 命令大全
7.1 基础命令
| 命令 | 功能 |
|---|---|
/help |
查看所有可用命令 |
/status |
查看当前会话状态（模型、Token 用量） |
/cost |
查看当前会话费用统计 |
/clear |
清空对话历史，重新开始 |
/compact |
压缩上下文，释放 Token 空间 |
/init |
自动生成 CLAUDE.md 文件 |
/review |
审查当前代码变更 |
/explain |
解释选中的代码 |
/fix |
修复选中的代码问题 |
/test |
为选中代码生成单元测试 |
7.2 高级命令
| 命令 | 功能 |
|---|---|
/plan |
进入计划模式（先生成方案再编码） |
/act |
直接执行模式 |
/model |
切换模型 |
/new |
新建会话 |
/resume |
恢复之前的会话 |
/upgrade |
升级 Claude Code 版本 |
7.3 VSCode 快捷键
| 快捷键 | 功能 |
|---|---|
Ctrl+Shift+P → 搜索 "Claude" |
所有 Claude Code 命令 |
Ctrl+I |
内联编辑选中的代码 |
Ctrl+Shift+I |
打开 Claude Code 对话面板 |
Alt+C |
继续当前对话（如果支持） |
⚠️ VSCode 快捷键可能与其他插件冲突，可以在「键盘快捷键设置」中搜索
Claude自定义。
8. Windows 注意事项
8.1 环境准备
powershell
# 确保以下工具在 PATH 中
node --version # Node.js ≥ 18
npm --version # npm 包管理器
cmake --version # CMake 构建工具
cl --version # MSVC 编译器（需安装 VS Build Tools）8.2 常见问题与解决
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 找不到 node | PATH 未设置 | 重新安装 Node.js，勾选 "Add to PATH" |
| 编译错误乱码 | 控制台编码 | [Console]::OutputEncoding = [Text.Encoding]::UTF8 |
| CMake 找不到 Qt | CMAKE_PREFIX_PATH 未设置 | $env:CMAKE_PREFIX_PATH = "C:/Qt/5.15.2/msvc2019_64" |
| 路径反斜杠问题 | Windows 路径分隔符 | 在 CLAUDE.md 中声明 platform: windows |
| API 连接超时 | 国内网络限制 | 设置代理：$env:HTTPS_PROXY = "http://127.0.0.1:7890" |
| DeepSeek 响应慢 | 免费版限速 | 确认 API Key 有余额，使用 Pro 版 |
| Claude 权限提示 | 执行命令需确认 | 这是安全机制，仔细审查后允许 |
8.3 推荐 PowerShell 配置
powershell
# 加到 $PROFILE 中（notepad $PROFILE）
# PowerShell 7+ 推荐
# DeepSeek 配置
$env:OPENAI_API_KEY = "sk-your-deepseek-key-here"
$env:OPENAI_BASE_URL = "https://api.deepseek.com/v1"
$env:OPENAI_MODEL = "deepseek-chat"
# Qt 路径（根据你的安装位置修改）
$env:CMAKE_PREFIX_PATH = "C:/Qt/5.15.2/msvc2019_64"
$env:QTDIR = "C:/Qt/5.15.2/msvc2019_64"
# 编码设置
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$PSDefaultParameterValues['*:Encoding'] = 'utf8'
# 代理（如果需要）
# $env:HTTPS_PROXY = "http://127.0.0.1:7890"
# $env:HTTP_PROXY = "http://127.0.0.1:7890"8.4 MSVC 编译环境
powershell
# 在启动 Claude Code 前，先确保 MSVC 环境正确
# 方式一：使用 VS Developer PowerShell
# 开始菜单 → Visual Studio 2022 → Developer PowerShell
# 方式二：手动加载
& "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Launch-VsDevShell.ps1" -Arch amd64
# 验证
cl --version # 应该显示 MSVC 版本信息9. 社区资源汇总
9.1 官方资源
| 资源 | 链接 | 说明 |
|---|---|---|
| Claude Code 官方文档 | https://docs.anthropic.com/en/docs/claude-code/overview | ✅ 必读，最权威 |
| CLAUDE.md 配置指南 | https://docs.anthropic.com/en/docs/claude-code/setting-up-claude-md | ✅ 配置文件写法 |
| VSCode Marketplace | https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code | 插件下载页 |
| Anthropic 官网 | https://www.anthropic.com/ | 产品公告 |
| API Console | https://console.anthropic.com/ | API Key 管理 |
9.2 社区论坛
| 平台 | 链接/搜索方式 | 活跃度 |
|---|---|---|
| Reddit r/ClaudeCode | https://www.reddit.com/r/ClaudeCode/ | ⭐⭐⭐ 非常活跃，最新消息 |
| Anthropic Discord | https://discord.gg/anthropic → #claude-code 频道 | ⭐⭐⭐ 官方人员在线 |
| GitHub Discussions | https://github.com/anthropics/claude-code/discussions | ⭐⭐ 技术讨论 |
| Hacker News | 搜索 "Claude Code" | ⭐ 深度讨论 |
| Twitter/X | 搜索 "#ClaudeCode" | ⭐ 关注 Anthropic 官方账号 |
9.3 中文社区
| 平台 | 搜索关键词 | 说明 |
|---|---|---|
| 知乎 | "Claude Code 使用" "DeepSeek Claude Code" | 有中文使用体验分享 |
| 掘金 | "Claude Code 教程" "AI 编程助手" | 技术文章 |
| V2EX | "Claude Code 配置" "Claude Code Windows" | 讨论帖，偏技术 |
| B站 | "Claude Code 教程" "Claude Code C++" | 视频演示 |
| CSDN | "Claude Code 安装" "Claude Code DeepSeek" | 教程类 |
| 少数派 | "Claude Code 体验" | 深度评测 |
9.4 Reddit 热门讨论帖（直接访问）
| 帖子主题 | 链接 |
|---|---|
| Claude Code is absolutely insane | https://www.reddit.com/r/ClaudeCode/comments/1jru7vs/ |
| Claude Code vs Cursor vs Copilot | https://www.reddit.com/r/ClaudeCode/comments/1k6xjp5/ |
| 第三方模型 Provider 配置 | https://www.reddit.com/r/ClaudeCode/comments/1kme3r4/ |
| DeepSeek V4 Pro 设置指南 | https://www.reddit.com/r/ClaudeCode/comments/1l2qv41/ |
| Windows 问题汇总 | https://www.reddit.com/r/ClaudeCode/comments/1kpcq46/ |
| CLAUDE.md 模板分享 | https://www.reddit.com/r/ClaudeCode/comments/1k8qbxz/ |
| C++/Qt 工作流 | https://www.reddit.com/r/ClaudeCode/comments/1kgv7hq/ |
9.5 GitHub 资源
| 仓库 | 链接 | 说明 |
|---|---|---|
| Claude Code（官方） | https://github.com/anthropics/claude-code | 官方代码 |
| CLAUDE.md 最佳实践 | https://github.com/nickscamara/claude-code-best-practices | 社区整理的模板 |
| Provider 讨论 | https://github.com/anthropics/claude-code/discussions/42 | 第三方模型配置讨论 |
10. 常见问题排错
Q1: Claude Code 启动后没有反应？
检查：Node.js 版本 ≥ 18
解决：nvm use 18.x 或重新安装 Node.js LTSQ2: DeepSeek API 连接失败？
检查：
1. API Key 是否正确（sk- 开头）
2. 环境变量是否设置
3. 网络能否访问 api.deepseek.com
→ 测试：curl https://api.deepseek.com/v1/models -H "Authorization: Bearer sk-xxx"
4. 是否需要代理（国内环境可能需要）
→ $env:HTTPS_PROXY = "http://127.0.0.1:7890"Q3: Claude Code 看不懂我的 Qt 项目？
解决：
1. 确保 CLAUDE.md 中写清楚了项目结构
2. 在对话中先描述项目概览
3. 把关键文件的头部粘贴给 Claude
4. 使用 /init 重新生成项目上下文Q4: 编译错误看不懂？
直接把 MSVC/GCC 输出的错误信息粘贴到对话中，
Claude Code 能定位到具体行号和修复方案Q5: 上下文不够用了？
1. 使用 /compact 压缩对话历史
2. 使用 /clear 重新开始新对话
3. 在 CLAUDE.md 中加入关键上下文（免得每次都要说）
4. 分模块工作，一次只做一个功能Q6: 提示 "API Key not configured"？
检查环境变量：
echo $env:OPENAI_API_KEY # 如果用 DeepSeek
echo $env:ANTHROPIC_API_KEY # 如果用 Claude
如果为空：
1. 重启 VSCode 让环境变量生效
2. 或在 VSCode settings.json 中设置Q7: VSCode 插件和 CLI 版本怎么选？
VSCode 插件：日常编码、对话式开发 ← 你选这个
CLI 版本： CI/CD、批量重构、文件处理
两者可以同时使用📌 总结：快速上手三步走
text
第一步：装好环境
├── Node.js 18+ ✅
├── VSCode + Claude Code 插件 ✅
└── DeepSeek API Key ✅
第二步：配好 CLAUDE.md
└── 写好项目结构、编码规范、Qt 版本
第三步：开始对话
└── "帮我创建一个 QMainWindow，左树右表布局..."最后提醒： DeepSeek V4 Pro 在代码编写上表现优秀，如果你遇到复杂的大型重构任务效果不佳，可以临时切回 Claude Sonnet 4 来完成那一步。两套模型配合使用，成本更低、效果更好。