本教程面向零基础开发者，目标是把 Claude Code 从"听说过"变成"能干活"。不同于只讲命令行 hello world 的传统入门，本文走 双轨入口 + 首个真实修复任务 的路线：先把 CLI 引擎装通，再把它分别接入 VS Code 与 JetBrains 两条 IDE 通道，最后用一个自带 Bug 的小型 Node.js 项目，让 Claude 读取编辑器诊断、定位缺陷、提交修复 Diff。学完你将具备在任何主流编辑器里驱动 Claude Code 的能力，并掌握认证、配置、双向打通的完整链路。
cd 与 npm很多人误以为 Claude Code 等于一个命令行工具。准确的说法是：CLI 是引擎，IDE 插件是桥梁，Web/移动端是延伸。引擎只有一份，桥梁可以多挂，这正是"双轨"的含义。
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[交付]
理解这张图后，下面的每一步都只是把对应节点填实。
引擎是所有 IDE 插件的底层依赖——插件本身不捆绑 CLI，它只是在集成终端里调用 claude 命令。所以无论你最终用哪个编辑器，这一步都绕不开。
原生安装器零依赖、自动后台更新，是 2026 年的官方首选：
# 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。
如果你已有 Node.js 工具链，也可以走 npm：
node --version # 必须 v18.0.0 及以上
npm install -g @anthropic-ai/claude-code
绝对不要用 sudo npm install -g。遇到 EACCES 权限错误，正确做法是把 npm 全局目录改到家目录：
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc # 或 ~/.bashrc
source ~/.zshrc
claude --version
打印出一串版本号即成功。若显示 command not found，新开一个终端窗口让 PATH 生效；仍失败就手动补：
export PATH="$HOME/.claude/bin:$PATH"
| 安装方式 | 依赖 | 更新机制 | 适用场景 |
|---|---|---|---|
| 原生安装器 | 无 | 自动后台更新 | 推荐绝大多数人 |
| npm | Node.js 18+ | 手动 npm update |
已有 Node 工具链 |
| Web App | 无 | 自动 | 受限网络、不能装软件的机器 |
Claude Code 支持两条认证路径，理解它们的区别能避免意外账单。
直接运行 claude，首次启动会拉起浏览器，用你的 Claude 账号登录。登录后所有用量计入订阅额度，无需任何 Key。
关键陷阱：如果你同时又设了 ANTHROPIC_API_KEY 环境变量，Claude Code 会优先走 API 计费，而不是订阅。要确认自己用的是哪条路：
claude
> /config
/config 面板会显示当前账号类型（Pro / Max / API Key）和模型。看到意外 API 费用时，第一时间检查 shell 配置里有没有遗留的 ANTHROPIC_API_KEY。
没有订阅、想按量计费时，去 console.anthropic.com 创建 Key（只显示一次，立即复制），然后：
# macOS / Linux，写入 ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-..."
重载 shell 后再跑 claude，它会自动用这把 Key 认证。
常见问题：装完一直跳浏览器让我登录，但我明明有 API Key。 解法：确认环境变量已在当前终端生效（
echo $ANTHROPIC_API_KEY有值），且写入了正确文件；WSL 用户注意别把变量只写进 Windows 侧。
引擎跑通后，VS Code 扩展在它之上叠加四项实在的增强，这也是"双轨"价值最直观的体现：
src/app/page.tsx:42 变成可点链接，跳转到对应行。Ctrl+Shift+X（Win/Linux）或 Cmd+Shift+X（Mac）打开扩展面板，搜索 Claude Code，认准发布者为 Anthropic（避开同名第三方分叉），点 Install。Ctrl+P / Cmd+P）粘贴：ext install anthropic.claude-code。File → Open Folder 打开项目根目录。Ctrl+``（Win/Linux）或Cmd+``（Mac）打开集成终端，确保当前目录是项目根。claude。扩展会自动检测并连接，终端出现确认信息。claude --ide。侧边栏出现一个火花图标；Claude 改文件时自动弹 Diff；终端里的文件引用变成可点链接；Problems 面板的错误 Claude 能"看见"。
常见问题：运行
claude没有出现 IDE 连接提示，Diff 也不弹。 解法：完全重启 VS Code（不是 Reload Window），到扩展面板确认没有出现"Disable"按钮（说明已启用），再claude --ide强连，并确认claude --version在集成终端里能打印版本。
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：
claude # 在外部终端
/ide # 连接到已打开的 VS Code / JetBrains，激活 Diff、诊断、导航
为了让 Claude 看到与 IDE 相同的文件，从项目根目录启动它。/config 里把 diff tool 设为 auto（Diff 显示在 IDE）或 terminal（留在终端），可控制 Diff 落点。
恢复上次会话用 claude --continue——它会带着该项目上次的完整上下文回来，不必从头解释任务。
Claude Code 的配置按优先级从低到高合并：
~/.claude/settings.json（用户级，全局默认）<项目>/.claude/settings.json（项目级，团队共享）<项目>/.claude/settings.local.json（项目本地，不入版本库）零基础起步时，先在项目级放一份最小可用配置：
{
"permissions": {
"allow": [
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(git status)",
"Bash(git diff:*)"
]
}
}
allow 列表里预先批准只读与测试命令，能大幅减少反复确认。生产环境务必慎用大范围通配（如 Bash(*)）。
在项目根放一个 CLAUDE.md，给 Claude 提供"项目说明书"。最小模板：
# 项目说明
一个 Node.js 折扣计算小工具，用于练习 Claude Code 的诊断修复流程。
## 技术栈
- Node.js 18+
- Jest（单元测试）
## 常用命令
- 安装依赖：`npm install`
- 跑测试：`npm test`
- 代码风格检查：`npm run lint`
## 约定
- 修复 Bug 前先跑一次 `npm test` 确认失败用例
- 不要自动提交，改完由我手动 commit
这份文件会被自动注入上下文。写得越准，Claude 越少跑偏。
下面用一个可复现的小项目，串起"诊断 → 定位 → 修复 → Diff 审查 → 验证"完整闭环。
mkdir -p ~/projects/discount-calc && cd ~/projects/discount-calc
npm init -y
npm install --save-dev jest
把 package.json 的 "test" 改成 "jest"，并加一条 lint：
{
"scripts": {
"test": "jest",
"lint": "node --check src/*.js"
}
}
src/discount.js：
// 计算折后价。discountPercent 取值 0~100。
function applyDiscount(price, discountPercent) {
// ❌ Bug：直接把百分比当小数乘，价格会变负
return price - price * discountPercent;
}
module.exports = { applyDiscount };
src/index.js（故意带一个 lint 可捕获的问题）：
const { applyDiscount } = require('./discount');
const unused = '这段未使用变量会被检查器标记';
console.log('100 打 20 折后价:', applyDiscount(100, 20));
test/discount.test.js：
const { applyDiscount } = require('../src/discount');
test('100 元打 20% 折扣应为 80', () => {
expect(applyDiscount(100, 20)).toBe(80);
});
test('原价不折扣应不变', () => {
expect(applyDiscount(50, 0)).toBe(50);
});
npm test
预期输出：两条用例一条通过、一条失败，applyDiscount(100, 20) 实际返回 -1900，不是 80。
在 VS Code 集成终端（或外部终端 /ide 连进来）运行：
claude
输入指令（这是关键 prompt，可照抄）：
在
src/下修复折扣计算 Bug。要求：(1) 先跑npm test确认失败用例；(2) 同时读 Problems 面板里的诊断，清掉index.js里的 lint 问题；(3) 修复后重跑测试直到全绿；(4) 不要自动 git commit。
Claude 的典型动作链：
npm test → 读到失败用例 applyDiscount(100, 20) 期望 80 实得 -1900。index.js 有未使用变量。src/discount.js → 识别 Bug，改为 price - price * (discountPercent / 100)。src/index.js 删除未使用变量。npm test → 两条用例全绿。每一步文件改动都通过 Diff 面板提交给你审。养成习惯：Diff 弹出后先读再接受，警惕 Claude 顺手做的"顺手重构"。
本例改动很小，Accept All 即可。
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 计费 |
把上述步骤压成一张可打印的速查图：
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
code.claude.com/docs）：quickstart、settings、permissions、authentication 各一页，权威且持续更新。/config、/ide、/clear、/compact 斜杠命令全表：交互模式的效率杠杆。--continue / --fork-session：长会话管理，避免越聊越慢。.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 等场景全覆盖。