# Claude Code IDE 插件上手：在编辑器内跑通你的首个项目
## 概述
本教程面向**零基础开发者**，带你走通 Claude Code 最推荐的使用路径——**IDE 扩展**。你将学会：用原生安装器或包管理器装好 Claude Code，在 VS Code / Cursor / JetBrains 中安装并配置官方扩展，登录账号，认识编辑器内的 Claude 面板，并亲手用对话+内联 diff 的方式做出第一个可运行的小项目（一个个人作品集落地页）。学完你就能把"自然语言驱动编码"变成日常习惯，而不是停留在终端敲命令。
## 前置条件
- 一台 macOS、Windows 或 Linux 电脑，能联网
- 已安装 **VS Code 1.98.0 或更高版本**（Cursor、Code-OSS、WindSurf 等 VS Code 衍生版亦可；JetBrains 用户见后文对应小节）
- 一个 **Anthropic 账号**：任何付费订阅（Pro / Max / Team / Enterprise）或 Claude Console 账号均可，**无需单独申请 API Key**
- （可选）已安装 Git，方便最后一步提交代码
- 心态准备：本教程假设你能打开终端、会复制粘贴命令，但不要求你熟记任何 shell 语法
---
## 第一步：先选对"入口"——三端择一
Claude Code 在 2026 年已经是一个多端产品：终端 CLI、桌面 App、网页版、IDE 扩展。对新手而言，**IDE 扩展是官方推荐的起点**，因为它把对话、计划审查、代码 diff、文件引用全部塞进了你熟悉的编辑器，省去了"在终端和编辑器之间来回切换"的认知负担。
但 IDE 扩展依赖底层 CLI，所以第一步是**先把 CLI 装上**。安装方式有四条官方通道，按你的平台二选一即可：
| 平台 | 推荐命令 | 是否自动更新 |
| --- | --- | --- |
| macOS / Linux / WSL（原生安装器，首选） | `curl -fsSL https://claude.ai/install.sh \| bash` | ✅ 后台自动更新 |
| Windows PowerShell（原生安装器） | `irm https://claude.ai/install.ps1 \| iex` | ✅ 后台自动更新 |
| macOS（Homebrew） | `brew install --cask claude-code` | ❌ 需手动 `brew upgrade` |
| Windows（WinGet） | `winget install Anthropic.ClaudeCode` | ❌ 需手动 `winget upgrade` |
**操作说明**：打开终端（macOS 用"终端"App，Windows 用 PowerShell，Linux 用你习惯的终端），复制上表第一行命令回车执行。
**预期结果**：脚本下载并安装 CLI，完成后提示已加入 PATH。新开一个终端窗口，输入：
```bash
claude --version
```
能看到版本号（如 `2.x.x`）即代表 CLI 就绪。
**常见问题**：
- **PowerShell 报 `'irm' is not recognized`**：说明你在用 CMD 而非 PowerShell。看提示符——`PS C:\>` 是 PowerShell，`C:\>` 没有 `PS` 的是 CMD。在 CMD 里改用：`curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`
- **报 `syntax error near unexpected token '<'` 或 403**：多半是公司代理或 curl 版本过旧，参考官方"Troubleshoot installation"页换镜像或换 `apt/dnf/apk` 包管理器方式
- **Windows 原生环境**：官方建议额外装 **Git for Windows**，这样 Claude 才能用 Bash 工具；没装则会退回用 PowerShell 作为 shell 工具，WSL 则不需要
---
## 第二步：在编辑器里安装 Claude Code 扩展
以 VS Code 为例（Cursor、Devin Desktop、Kiro 等衍生版操作完全一致；Open VSX 阵营的编辑器也能搜到）。
**操作说明**：
1. 打开 VS Code。
2. 按下 `Cmd+Shift+X`（Mac）或 `Ctrl+Shift+X`（Win/Linux）打开**扩展面板**。
3. 搜索框输入 `Claude Code`，找到发布者为 **Anthropic** 的那一个（Marketplace 标识符为 `anthropic.claude-code`），点 **Install**。
4. 安装完成后，编辑器右上角（编辑器工具栏）会出现一个**火花图标（Spark icon）**——这就是 Claude Code 的入口。
**预期结果**：右上角出现火花图标；点击它，右侧（或次级侧边栏）弹出 Claude Code 面板，提示你登录。
**JetBrains 用户**（IntelliJ IDEA / PyCharm / WebStorm / PhpStorm / GoLand / Android Studio）：进入 `Settings → Plugins`，搜索 `Claude Code` 安装，重启 IDE。安装后可以用 `Cmd+Esc`（Mac）/ `Ctrl+Esc`（Win/Linux）一键唤起，或点击工具栏的 Claude Code 按钮。
**常见问题**：
- **装完看不到火花图标**：大概率是窗口没刷新。按 `Cmd+Shift+P` / `Ctrl+Shift+P` 打开命令面板，输入并执行 `Developer: Reload Window`；还不行就彻底重启 VS Code。
- **扩展装不上**：说明你的编辑器可能不在官方 Marketplace 上（如某些 Open VSX-only 发行版）。退而求其次——只要 CLI 装好了，直接在 VS Code 的**集成终端**里敲 `claude` 也能用，体验略不同但功能齐全。
---
## 第三步：登录认证
**操作说明**：第一次点开面板时，Claude 会引导你登录。它支持订阅账号和 Console 账号，**不需要 API Key**。点击登录按钮后，浏览器会自动打开一个 Anthropic 授权页，确认后回到编辑器即完成绑定。
如果你之前在终端跑过 `claude`，账号其实已经登录好了，扩展会直接复用。想切换账号时，在对话输入框里输入斜杠命令：
```
/login
```
**预期结果**：面板顶部显示你的账号与剩余用量；输入框变成可输入的"Ask Claude…"状态。
**常见问题**：
- **公司用的是 Amazon Bedrock / Google Vertex AI**：不能直接登 Anthropic 账号，需要在设置里切到第三方 Provider 模式，按官方"Use third-party providers"页填 endpoint 和凭证。
- **登录页一直转圈**：检查是否有公司代理拦截了 `claude.ai` 与 `anthropic.com` 域名；必要时配置 `HTTPS_PROXY` 环境变量。
---
## 第四步：认识编辑器内的 Claude 面板
在动手之前，先用一分钟记住几个高频交互点，后面会反复用到：
```mermaid
flowchart LR
A[Spark 火花图标
右上角工具栏] --> B[Claude 面板
对话 / 计划 / diff]
B --> C{三种'住法'}
C --> D[侧边面板
默认]
C --> E[独立标签页
多会话并行]
C --> F[终端模式
claude 原生 TUI]
B --> G[快捷键]
G --> H[Cmd/Ctrl+Esc
全局唤起]
G --> I[Cmd/Ctrl+Shift+P
命令面板]
```
- **火花图标**：Claude Code 的统一标识，点它开/关面板。
- **三种"住法"**：默认在侧边面板；想多线程可以把会话拖成**独立标签页或窗口**，每个 tab 是一条独立对话；老用户偏爱的 **Terminal 模式**（原生 TUI）也能一键切换。
- **`@`-mention**：在输入框打 `@`，会弹出当前工作区的文件列表，选中即可把文件喂给 Claude；甚至能引用**具体行**，例如 `@src/index.html#L1-40`。
- **选区与诊断共享**：你在编辑器里**选中的代码**、当前打开的标签页、以及 LSP 报出的**报错/警告**，都会自动作为上下文传给 Claude，无需手动复制粘贴。
- **计划审查 + 自动接受**：Claude 改代码前可以让你**先看计划再批准**；也可以开启"边改边接受"模式，适合信任度高的琐碎修改。
---
## 第五步：创建你的第一个项目——个人作品集落地页
选这个项目有三个理由：**零依赖、零构建、纯浏览器可看**——最适合新手，又能充分展示 IDE 扩展的 diff 与预览能力。
**操作说明**：
1. 新建一个空文件夹，比如 `~/projects/portfolio`，在 VS Code 里 `File → Open Folder` 打开它。
2. 按 `Cmd+Esc` / `Ctrl+Esc` 唤起 Claude 面板（或点火花图标）。
3. 在输入框里写下你的第一段需求（中文完全没问题）：
```
帮我从零做一个个人作品集落地页，单页 HTML + 内联 CSS + 一点原生 JS。
要求：顶部导航 + 英雄区（名字、一句话简介、头像占位）+ 三个项目卡片 +
底部的联系方式。配色用深色系，响应式，移动端可用。先建 index.html 一个文件即可。
```
4. 回车发送。Claude 会先给一份**简短计划**，你点 Approve（或开启 auto-accept）让它落地。
**预期结果**：资源管理器里出现 `index.html`，面板里能看到 Claude 的修改以**内联 diff**形式呈现——绿色是新增、红色是删除，和 Git diff 一致。`Cmd+S` 不用按，扩展会自动写入磁盘。
**常见问题**：
- **Claude 想建一堆文件/装框架**：新手期建议在设置里把"自动建文件"收敛一些，或者在需求里明确"只建 index.html"。你也可以随时拒绝某一步计划。
- **想看效果**：装个微软官方的 `Live Preview` 扩展，右键 `index.html → Show Preview`，改一行、预览即时刷新。
---
## 第六步：让 Claude 迭代代码——体验内联 diff 与计划审查
第一个版本往往不够好，这正是 Claude 的强项。继续在同一会话里追加需求，**不要新建对话**（保留上下文更准）：
```
把三个项目卡片改成带hover上浮动效，并且每个卡片加一个"查看详情"按钮，
点击后在页面底部弹出该项目的简介（用 details/summary 或轻量 modal 均可，
你选更稳的方案）。另外英雄区的标题用渐变文字。
```
**操作说明**：发送后留意面板顶部的**计划摘要**——Claude 会列出它打算改哪些文件、加哪些函数。你可以：
- 点 **Edit plan** 调整范围（比如"先别动 modal，只做 hover"）
- 点 **Approve** 让它执行
- 或开启 **Auto-accept** 让琐碎修改一路放行
**预期结果**：修改仍以 diff 展示，你能在编辑器里**逐块接受/拒绝**。配合 Live Preview，你能实时看到渐变标题和 hover 动效。
**常见问题**：
- **改坏了想回退**：见第八步的 Checkpoints（检查点回退）。
- **Claude 反复改同一处不对**：八成是上下文里混入了错误信息。用 `@` 显式引用正确文件，或在输入框 `/clear` 清空当前会话上下文重来。
---
## 第七步：@引用、选区与诊断——把"上下文"喂准
IDE 扩展相比终端 CLI 最大的优势，就是**上下文几乎不用你手动管**。三个高频技巧：
1. **引用文件+行号**：直接在输入框写 `把 @index.html#L40-60 的卡片网格改成两列布局`，Claude 只盯这段。
2. **选中即上下文**：鼠标拖选一段 CSS，然后直接问"这段在 Safari 上居中失效，怎么修？"——选区会自动随提问送出。
3. **诊断共享**：故意把某个 `` 删掉触发 LSP 报错，然后告诉 Claude"修一下当前报错"，它会读到红色波浪线对应的错误信息并定位修复。
```mermaid
sequenceDiagram
participant U as 你
participant IDE as 编辑器/扩展
participant C as Claude
U->>IDE: 选中代码 / @引用文件
U->>IDE: 输入需求并回车
IDE->>C: 自动打包 选中内容 + 打开标签 + LSP诊断 + 文件树
C->>IDE: 返回计划
U->>IDE: Approve / 调整
IDE->>C: 执行
C->>IDE: 内联 diff 落盘
IDE->>U: 编辑器实时刷新 + 预览
```
**预期结果**：你几乎不需要"复制错误信息粘贴给 AI"——选中、报错、当前文件这些状态都被扩展自动捕获。
---
## 第八步：在编辑器内用 Git 提交
项目成型后顺手提交。Claude 在 IDE 内同样能驱动 Git。
**操作说明**：在面板里说：
```
帮我把当前改动提交：先 git add -A，commit message 用规范格式，
说明新增了作品集落地页。然后告诉我接下来怎么推到一个新的 GitHub 仓库。
```
**预期结果**：Claude 执行 `git add` 与 `git commit`（涉及写操作会请求权限，确认即可），并在面板里给你一段"如何 `git remote add origin ... && git push`"的后续指引。VS Code 的源代码管理面板也会同步显示这次提交。
**进阶——检查点（Checkpoints / Rewind）**：Claude 每完成一轮较大修改会打一个检查点。如果某次改崩了，面板里有 **Rewind** 入口，能一键回到之前的状态，比手动 `git stash` + `git reset` 直观得多，**这是 IDE 扩展相对终端的杀手锏之一**。
---
## 实战案例：30 分钟作品集落地页（完整可运行版）
把前面零散步骤串成一个完整闭环。最终目录极简：
```
portfolio/
├── index.html # 单文件，内联 CSS + JS
└── README.md # 给 Claude 看的项目说明（可选）
```
**关键 `index.html` 骨架**（你可以让 Claude 生成完整版，这里给结构供对照）：
```html
我的作品集
```
**推荐对话脚本**（按顺序发给 Claude，每条等它改完再发下一条）：
1. "按上面骨架生成完整 `index.html`，深色主题，响应式。"
2. "英雄区标题用 `--accent` 渐变文字；卡片 hover 上浮 4px 并加阴影。"
3. "每张卡片加'查看详情'按钮，点击用原生 `