Claude Code 完整安装指南：从零开始到成功运行

课程信息
预计学时：2-3小时（原生安装更简单！）
难度等级：⭐ 零基础入门
更新日期：2026年2月
适用版本：Claude Code v2.1+
重要更新：已切换到原生安装，无需Node.js！

📚 本课学习目标

完成本课学习后，你将能够：

理解Claude Code的核心价值：掌握Claude Code与传统AI编程工具的本质区别
了解原生安装优势：为什么官方废弃了npm，改用原生安装器
配置Anthropic服务：获取并正确配置API密钥
完成Claude Code安装：掌握一行命令的原生安装方式（无需Node.js！）
集成到主流IDE：VS Code、Cursor、JetBrains等编辑器配置
验证环境可用性：通过Hello World测试确认所有组件正常工作
掌握故障排查技能：独立解决90%的常见安装问题
了解从npm迁移：如果你之前用npm安装过，如何迁移到原生版本

🗺️ 学习路径导航（先看这里！）

💡 根据你的情况选择学习路径：这是一篇3000+行的长教程，不用全看！根据你的目标选择路径。

路径A：快速上手（⏱️ 30分钟）

适合人群：急着体验Claude Code，想快速跑起来

只看这些章节（其他跳过）：

✅ 术语表（3分钟） - 快速了解关键概念
✅ 第3部分：API Key配置（10分钟）
✅ 第4部分：Claude Code原生安装（5分钟） - 一行命令搞定！
✅ 第5部分：启动与验证（12分钟）

30分钟后你能达到：成功启动Claude Code，运行Hello World示例

路径B：完整学习（⏱️ 2-3小时）

适合人群：想深入理解每个细节，掌握所有功能

学习顺序：从头到尾所有章节

建议分段学习：

第1阶段（1小时）：第1-4部分（理解+API Key+安装）
第2阶段（1小时）：第5-6部分（验证+IDE集成）
第3阶段（30分钟）：第7-8部分（故障排查+FAQ）

路径C：问题排查（⏱️ 10分钟）

适合人群：安装过程遇到问题，需要快速解决

直接跳到这些章节：

🔧 第7部分：故障排查 - 按错误类型查找解决方案
🔧 第8部分：FAQ - 学员最常问的问题
🔧 附录：从npm迁移 - 如果你之前用npm装过

使用方法：

按 Ctrl + F 搜索你的错误信息关键词
找到对应的Q&A
按步骤解决

路径D：专项学习（⏱️ 30-60分钟/主题）

适合人群：已经装好Claude Code，想学习某个特定功能

想学什么	看哪几节	预计时间
IDE集成	第6部分	30分钟
权限配置	第5.5节（危险参数）+ 第6.3节	20分钟
从npm迁移	附录：迁移指南	15分钟

术语表（小白必读）

⚠️ 2026年重要更新：Claude Code已切换到原生安装，不再需要Node.js和npm！下表中带⚠️的术语仅为历史参考。

在开始之前，先了解这些关键术语：

术语	英文全称	通俗解释
CLI	Command Line Interface	命令行界面，就是那个黑色/白色的文字输入窗口，通过打字来操作电脑
原生安装器 ⭐	Native Installer	Claude Code官方提供的独立安装程序，不需要其他依赖
Node.js ⚠️	-	~~JavaScript运行环境~~（旧版本需要，新版原生安装不需要了）
npm ⚠️	Node Package Manager	~~Node.js的包管理器~~（已废弃，官方不再推荐此安装方式）
LTS	Long Term Support	长期支持版本，稳定、bug少、官方持续维护，适合正式使用
API	Application Programming Interface	应用程序接口，软件之间"对话"的方式
API Key	-	API密钥，类似"通行证"，证明你有权使用某个服务
Token	-	计费单位，AI处理文字的最小单元，约等于0.75个英文单词或1-2个汉字
环境变量	Environment Variable	操作系统级别的配置项，程序可以读取但不会写在代码里
PATH	-	系统环境变量之一，告诉电脑去哪里找可执行程序
终端/Terminal	-	运行命令行的程序窗口
全局安装	Global Install	安装后在电脑任何位置都能使用的安装方式

第一部分：Claude Code 简介

1.1 什么是 Claude Code

Claude Code 是 Anthropic 公司开发的命令行AI编程助手。与传统代码编辑器插件不同，它是一个独立运行的CLI工具，通过终端与开发者交互。

核心特征：

本地优先架构：代码在你的电脑上处理，不上传到云端
全能AI助手：基于Claude模型，理解复杂技术需求
工具整合能力：可调用文件操作、终端命令、Web搜索等工具
对话式开发：用自然语言描述需求，AI帮你生成和修改代码

简单理解：

把Claude Code想象成一个24小时在线的高级程序员。你用中文或英文告诉他需求，他能帮你写代码、改bug、搜资料、运行测试。最大特点是通过命令行工作，可以直接操作你的代码文件、运行系统命令，完全脚本化和自动化。

1.2 核心优势：为什么值得学习

优势1：隐私与安全

传统在线AI工具需要你把代码上传到服务器分析。Claude Code不同：

✅ 代码文件留在本地，AI只读取你授权的文件
✅ 可在企业内网环境使用（配合私有Claude部署）
✅ 敏感项目（如金融、医疗系统）也能安全使用

优势2：真正的编程助手

实际案例：

你：帮我把项目中所有console.log改成更规范的日志系统

Claude Code：
1. [扫描] 找到37个console.log调用
2. [询问] 是否使用Winston日志库？
3. [执行] 安装依赖、创建配置、批量替换代码
4. [验证] 运行测试确认改动正确

优势3：多语言多框架支持

不限于特定技术栈：

前端：React、Vue、Next.js
后端：Node.js、Python、Go
移动端：React Native、Flutter
基础设施：Docker、Kubernetes配置

1.3 与主流工具对比

CLI工具 vs IDE集成工具对比：

对比项	Claude Code（CLI）	Cursor（IDE集成）
运行方式	命令行独立运行	VS Code编辑器内置
文件操作	✅ 直接读写	✅ 直接读写
项目理解	✅ 全项目上下文	✅ 全项目上下文
脚本自动化	✅ 完美支持	⚠️ 有限
CI/CD集成	✅ 原生支持	❌ 困难
远程服务器	✅ 完美支持	❌ 需要图形界面
隐私性	✅ 本地优先	⚠️ 云端处理
学习曲线	中等（需要CLI基础）	低（图形界面）

推荐使用场景：

选Claude Code（CLI）适合：

✅ 重构遗留项目、批量代码处理
✅ CI/CD自动化、脚本集成
✅ 远程服务器开发、无图形界面环境
✅ 企业级开发（私有部署、安全要求高）
✅ 高级开发者（熟悉命令行、需要自动化）

选Cursor（IDE集成）适合：

✅ 日常开发、快速原型
✅ 学习新框架、初学者友好
✅ 需要图形界面和可视化
✅ 实时代码补全和建议

1.4 适合谁学习

强烈推荐：

有1年+编程经验的开发者：能充分利用AI加速工作流
技术Leader/架构师：需要快速审查和重构代码
独立开发者：一个人维护多个项目，需要AI协作
开源贡献者：快速理解陌生代码库

需要慎重考虑：

编程零基础：建议先学基础语法和终端操作（建议学习时长：3-6个月）
只用图形界面：Claude Code需要熟悉命令行
网络受限：需要访问Anthropic API（国内需代理）

课前准备检查清单

⚠️ 2026年重大更新：原生安装无需Node.js！检查清单大大简化！

在开始安装前,请确认以下内容已完成:

检查项	状态	如果未完成
操作系统兼容	[ ] 确认	Windows 10+ / macOS 10.15+ / Linux
ANTHROPIC_API_KEY	[ ] 已配置	中转站或官网获取(见第三部分)
终端可用	[ ] 能打开	macOS用终端，Windows用PowerShell
网络连接	[ ] 可访问外网	国内用户需代理(见附录)

如果所有项都已完成,让我们开始吧!

💡 老金提示：相比旧版本，你现在省去了安装Node.js的40分钟！原生安装器自带所有依赖，一条命令搞定！

第二部分：系统要求快速检查

💡 本节目的：快速确认你的电脑能不能运行Claude Code，3分钟搞定！

2.1 快速检查清单（核心3项）

在开始安装前，确认以下3项核心要求：

检查项	最低要求	如何检查	不符合怎么办
操作系统	Windows 10 / macOS 10.15+ / Linux	查看系统版本	升级系统或换电脑
内存	4GB RAM	右键"此电脑"→属性	不足4GB无法运行
网络	能访问外网	打开 google.com 试试	国内用户需要配置代理（见附录B）

快速验证命令：

所有平台通用：

bash

# 检查能否访问Anthropic API
ping api.anthropic.com
# 能ping通 → ✅ 网络OK
# ping不通 → ⚠️ 需要配置代理

如果3项全部✅ → 恭喜，你的电脑满足要求，继续往下！

如果有❌ → 跳到附录A查看详细要求和解决方案。

2.2 详细要求说明（可选阅读）

⚠️ 小白注意：这部分是详细技术说明，如果上面快速检查都通过了，可以跳过直接看第三部分！

操作系统详细兼容性：

操作系统	最低版本	推荐版本	说明
Windows	Windows 10	Windows 11	64位系统
macOS	10.15 Catalina	macOS 13+	Intel/Apple Silicon都支持
Linux	内核3.10+	5.x+	Ubuntu/Debian/Fedora等主流发行版

硬件推荐（非强制）：

CPU：双核+（i3或同等性能即可）
内存：8GB更佳（4GB也能用，大项目会慢点）
存储：SSD更快（机械硬盘也行）

💡 老金建议：别被这些要求吓到！只要你电脑能正常开发写代码，就肯定能跑Claude Code。这些是"推荐配置"不是"必需配置"。
详细性能对比和配置建议 → 见附录A

第三部分：原生安装说明（⭐ 重要更新）

💡 2026年重大变化：Claude Code已切换到原生安装器！
好消息：你不再需要安装Node.js了！官方从npm安装迁移到原生安装，安装过程从40分钟缩短到5分钟！
⏱️ 预计时间：5分钟完成安装

3.1 为什么切换到原生安装？

背景说明：

2025年10月31日，Anthropic官方在社交媒体宣布：

"Claude Code的原生安装器现已正式发布。它更简单、更稳定，不需要Node.js。我们建议所有Claude Code用户今后都使用这种默认安装方式。"

原生安装 vs npm安装对比：

对比项	原生安装 ⭐	npm安装（已废弃）
需要Node.js	❌ 不需要	✅ 必须安装
安装时间	⏱️ 5分钟	⏱️ 40分钟
自动更新	✅ 后台自动	❌ 需手动运行
PATH配置	✅ 自动完成	⚠️ 经常出错
跨平台支持	✅ 完美	⚠️ 平台差异大
稳定性	✅ 生产级	⚠️ 依赖环境

简单理解：

以前安装Claude Code像组装家具（需要很多工具和零件），现在像买成品（拿来即用）！

3.2 原生安装的工作原理

它是什么？

原生安装器是一个独立的可执行程序，由Anthropic官方编译和签名。它包含：

✅ Claude Code核心程序
✅ 所有必需的依赖库
✅ 自动更新机制
✅ 安全签名验证

安装到哪？

操作系统	安装位置
Windows	`C:\Users\你的用户名\AppData\Local\claude-code\`
macOS/Linux	`~/.local/bin/claude`

3.3 自动更新机制

原生安装器的一大优势：自动更新！

✅ 后台自动检查更新（无需手动操作）
✅ 增量更新（只下载变化部分，省流量）
✅ 可配置更新策略（见高级配置）

如何禁用自动更新？（可选）

bash

# 如果你想手动控制更新，可以设置环境变量
export CLAUDE_AUTO_UPDATE=false

💡 老金建议：大多数人保持默认开启就好，自动更新让你始终使用最新最安全的版本。

3.4 如果你之前用npm安装过？

别担心！官方提供了迁移命令。

如果你之前通过 npm install -g @anthropic-ai/claude-code 安装过，运行：

bash

claude install

这会：

下载并安装原生版本
保留你的所有配置
删除旧的npm版本

详细迁移步骤 → 见附录：从npm迁移指南

第四部分：Anthropic 账号准备

💡 为什么现在就要准备API Key？
小白常见疑问："我还没装Claude Code，为什么先要API Key？"
答案很简单：
Claude Code是AI助手，需要连接Anthropic的AI服务才能工作
API Key就像"通行证"，证明你有权使用AI服务
提前准备好Key的好处：装完Claude Code立即就能用，不用再等待
生活类比：
Claude Code = 你新买的手机
API Key = SIM卡
先办好SIM卡，手机到手插卡就能用！

💡 选择提示：可选择使用中转站（更便宜、更稳定），或官方账号。
中转站优势：价格低（约官方1/3-1/2）、无需科学上网、支付方便
官方账号优势：更稳定、有免费额度、支持订阅
本课程同时讲解两种方式的配置方法。

4.1 注册 Anthropic 账号

注册流程：

访问注册页面：https://console.anthropic.com/
点击"Sign Up"（注册）
选择注册方式（三种任选其一）：
- Google账号登录（推荐，最快）
- 邮箱+密码注册
- GitHub账号登录
完善账号信息：
- 姓名：真实姓名或开发者昵称
- 使用场景：选择"Personal Use"（个人使用）或"Business"（商业）
- 主要编程语言：可多选
手机验证（可能需要）：
- 支持中国大陆号码（+86）
- 会收到6位数验证码短信
- 如果未收到，可选择语音验证

注意：国内手机号注册成功率约80%。如果多次失败，可尝试使用Google Voice虚拟号码、香港/台湾号码，或联系Anthropic支持。

4.2 API Key 获取步骤

什么是API Key？

API Key是一串密钥，作用类似密码，用于：

证明你有权使用Claude AI服务
追踪API调用次数（计费依据）
控制访问权限

格式示例：

sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

获取步骤：

进入API Keys页面
登录后点击左侧菜单：Settings → API Keys
或直接访问：https://console.anthropic.com/settings/keys
创建新Key
点击"Create Key"按钮，填写：
- Key名称：例如"claude-code-laptop"（方便区分多个key）
- 权限：选择"Full Access"（完全访问）
复制并保存Key
⚠️ 关键警告：
- Key只显示一次！关闭窗口后无法再看到
- 必须立即复制并保存到安全位置
- 不要分享给任何人
保存方法：
1. 创建文本文件 anthropic-key.txt
2. 粘贴完整key
3. 保存到电脑安全位置（如Documents文件夹）

验证Key有效性

bash

# macOS/Linux
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: 你的API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# 如果返回JSON响应(而不是错误),说明Key有效

Windows PowerShell测试：

powershell

$headers = @{
    "x-api-key" = "你的API_KEY"
    "anthropic-version" = "2023-06-01"
    "content-type" = "application/json"
}
$body = '{"model":"claude-sonnet-4-5-20250929","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'
Invoke-RestMethod -Uri "https://api.anthropic.com/v1/messages" -Method POST -Headers $headers -Body $body

4.3 环境变量配置

什么是环境变量？

环境变量是操作系统级别的配置，让程序可以读取敏感信息（如API Key），而不需要写在代码里。

好处：

✅ 安全：不会意外提交到GitHub
✅ 灵活：不同电脑可用不同Key
✅ 标准：所有开发工具都支持

Windows配置方法

推荐方法：PowerShell 7（最佳选择）

powershell

# 永久添加用户环境变量（PowerShell 7）
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-api03-你的key', 'User')

# 验证配置
$env:ANTHROPIC_API_KEY

# 重启PowerShell后生效

临时配置（仅当前终端有效）：

powershell

# PowerShell（包括PowerShell 5和7）
$env:ANTHROPIC_API_KEY="sk-ant-api03-你的key"

# CMD（不推荐，功能有限）
set ANTHROPIC_API_KEY=sk-ant-api03-你的key

永久配置方法2：通过图形界面

右键"此电脑" → 属性
点击"高级系统设置"
点击"环境变量"
在"用户变量"区域点击"新建"
变量名：ANTHROPIC_API_KEY
变量值：sk-ant-api03-你的完整key
点击"确定"保存
重启所有终端窗口

提示：图形界面方法适合不熟悉命令行的用户，但PowerShell 7方法更快捷。

macOS/Linux配置方法

bash

# 确定使用的Shell
echo $SHELL

# 如果是bash,编辑~/.bashrc
# 如果是zsh(macOS默认),编辑~/.zshrc

# 添加以下行（替换为真实Key）
export ANTHROPIC_API_KEY="sk-ant-api03-你的key"

# 保存后重新加载
source ~/.zshrc  # 或 source ~/.bashrc

# 验证
echo $ANTHROPIC_API_KEY

使用nano编辑器示例：

bash

# 打开配置文件
nano ~/.zshrc

# 添加Key配置
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"

# 保存：Ctrl+O → 回车 → Ctrl+X退出

安全注意事项

✅ 正确做法：

只在本地配置环境变量
不要提交 .env 文件到Git
定期轮换API Key

❌ 错误做法：

把Key直接写在代码里：const key = "sk-ant-..."
在GitHub Issues/论坛公开Key
与他人共享Key

泄露后的处理：

立即到Console删除泄露的Key
创建新Key
更新环境变量
检查API使用记录是否异常

4.3.1 API中转站配置（可选）

💡 什么是API中转站？ 中转站是第三方提供的API代理服务，将你的请求转发到Anthropic官方API。对于国内用户来说，中转站可以解决网络访问问题，通常价格也更低。

中转站 vs 官方API对比：

对比项	官方API	中转站
价格	官方定价	通常为官方的 1/3 ~ 1/2
网络要求	需要科学上网	无需科学上网
支付方式	信用卡（Visa/Master）	支付宝/微信
稳定性	最稳定	取决于中转站质量
免费额度	新用户有 $5 额度	通常无免费额度

配置方法：

中转站会提供一个自定义的 API 地址（Base URL），你需要同时配置 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL 两个环境变量。

Windows（PowerShell）：

powershell

# 设置中转站API Key（中转站提供的Key）
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', '你的中转站Key', 'User')

# 设置中转站API地址
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://你的中转站地址/v1', 'User')

# 重启终端后验证
$env:ANTHROPIC_BASE_URL

macOS/Linux：

bash

# 在 ~/.zshrc 或 ~/.bashrc 中添加
export ANTHROPIC_API_KEY="你的中转站Key"
export ANTHROPIC_BASE_URL="https://你的中转站地址/v1"

# 使配置生效
source ~/.zshrc

验证中转站是否生效：

bash

# 启动Claude Code后，观察是否能正常连接
claude

# 如果连接成功，说明中转站配置正确
# 如果报错，检查URL末尾是否需要 /v1

⚠️ 安全提醒：选择中转站时注意甄别，优先选择口碑好、运营时间长的服务商。中转站可以看到你的API请求内容，避免传输高度敏感的数据。

4.4 计费与订阅

Claude Code需要付费吗？

两层计费：

Claude Code工具本身
- ✅ 免费开源
- 无需购买License
Claude API使用费
- ⚠️ 按调用量计费
- 类似手机话费（用多少付多少）

Token是什么？

Token是AI处理文本的最小单位，用于计费：

1 token ≈ 0.75个英文单词
1 token ≈ 1-2个汉字
1000 tokens ≈ 750字短文

💡 成本说明：
Claude Code的使用成本取决于你的API调用量。具体计费方式和价格请查看：
官方价格页面：https://www.anthropic.com/pricing
Console账单页面：https://console.anthropic.com/ → Settings → Billing
建议在实际使用中监控自己的消耗情况，根据需求调整使用频率。

第五部分：Claude Code 原生安装（⭐ 核心重点）

💡 本部分目标：一行命令完成安装，5分钟搞定！ ⏱️ 预计时间：3-5分钟

5.1 安装方式概览

原生安装提供3种方式，任选其一即可：

安装方式	适用平台	命令	推荐度
脚本安装 ⭐	macOS/Linux/WSL	`curl ...	bash`
PowerShell	Windows	`irm ...	iex`
Homebrew	macOS/Linux	`brew install --cask`	⭐⭐⭐⭐
WinGet	Windows 10/11	`winget install`	⭐⭐⭐⭐

💡 老金推荐：
Windows用户：用PowerShell（最简单）
Mac用户：用脚本安装或Homebrew（都很快）
Linux用户：用脚本安装

5.2 方式1：脚本安装（推荐 - 跨平台）

macOS / Linux / WSL 安装

打开终端，复制粘贴以下命令：

bash

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

一行命令解释：

部分	作用
`curl -fsSL`	下载安装脚本（-f失败继续，-s静默，-S显示错误，-L跟随重定向）
`https://claude.ai/install.sh`	Anthropic官方安装脚本地址
`	bash`

安装过程：

[终端显示]
Downloading Claude Code...
Installing to /home/你的用户名/.local/bin/claude
✓ Installation complete!
✓ Added to PATH

Run 'claude --version' to verify.

验证安装：

bash

claude --version
# 预期输出：Claude Code v2.1.x (native)

Windows PowerShell 安装

步骤1：打开PowerShell

按 Win 键
输入 PowerShell
按 Ctrl + Shift + Enter（以管理员身份运行）

步骤2：执行安装命令

powershell

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

命令解释：

部分	作用
`irm`	`Invoke-RestMethod` 的别名，下载内容
`https://claude.ai/install.ps1`	Windows安装脚本地址
`	iex`

安装过程：

[PowerShell显示]
Downloading Claude Code...
Installing to C:\Users\你的用户名\AppData\Local\claude-code\
✓ Installation complete!
✓ Added to PATH

Run 'claude --version' to verify.

验证安装：

powershell

claude --version
# 预期输出：Claude Code v2.1.x (native)

5.3 方式2：Homebrew安装（macOS/Linux）

如果你是Mac用户且已经安装了Homebrew，这是最简单的方式：

bash

brew install --cask claude-code

优势：

✅ Homebrew自动管理依赖
✅ 方便更新：brew upgrade claude-code
✅ 方便卸载：brew uninstall claude-code

注意： Homebrew安装不会自动更新，需要手动运行更新命令。

5.4 方式3：WinGet安装（Windows）

Windows 10/11用户可以使用WinGet包管理器：

powershell

winget install Anthropic.ClaudeCode

优势：

✅ Windows原生包管理器
✅ 系统级安装
✅ 方便更新：winget upgrade Anthropic.ClaudeCode

5.5 验证安装成功

无论用哪种方式，安装完成后验证：

bash

# 检查版本
claude --version
# 预期输出：Claude Code v2.1.x (native)

# 检查帮助
claude --help
# 应该显示完整帮助信息

# 检查安装位置
where claude     # Windows
which claude     # macOS/Linux

成功的标志：

✅ 显示版本号（带 native 标识）
✅ 命令可以直接运行（不提示找不到命令）
✅ --help 能显示帮助信息

5.6 安装失败排查

问题1：命令找不到

claude: command not found

原因：PATH环境变量未更新

解决方案：

bash

# macOS/Linux: 重新加载配置
source ~/.zshrc   # 或 source ~/.bashrc

# Windows: 重启PowerShell或CMD
# 或者手动添加到PATH：
# macOS/Linux: ~/.local/bin
# Windows: C:\Users\你的用户名\AppData\Local\claude-code\bin

问题2：权限被拒绝

bash

Error: EACCES: permission denied

解决方案：

bash

# macOS/Linux: 不需要sudo了！原生安装会安装到用户目录
# 如果还是提示权限，检查目录所有权
ls -la ~/.local/bin

# Windows: 以管理员身份运行PowerShell

问题3：网络连接失败

Error: Failed to download

解决方案：

bash

# 配置代理（如果使用代理）
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

# 然后重新运行安装命令
curl -fsSL https://claude.ai/install.sh | bash

问题4：Windows SmartScreen拦截

Windows已保护你的电脑

解决方案：

点击"更多信息"
点击"仍要运行"
原因：原生安装器由Anthropic签名，SmartScreen可能不认识新签名

5.7 卸载 Claude Code

如果你需要卸载：

macOS/Linux:

bash

# 删除可执行文件
rm ~/.local/bin/claude

# 删除配置和数据（可选）
rm -rf ~/.claude

Windows:

powershell

# 删除安装目录
Remove-Item -Recurse -Force $env:LOCALAPPDATA\claude-code

# 删除配置（可选）
Remove-Item -Recurse -Force ~/.claude

Homebrew卸载：

bash

brew uninstall --cask claude-code

WinGet卸载：

powershell

winget uninstall Anthropic.ClaudeCode

第六部分：首次启动与验证

6.1 启动 Claude Code 的三种方式

方式1：标准交互模式（最常用）

bash

# 在任意目录启动
claude

# 启动流程：
# 1. 检测当前目录
# 2. 加载CLAUDE.md（如果存在）
# 3. 进入交互式对话界面

方式2：单次命令模式

bash

# 执行单个命令后退出
claude "你的问题或指令"

# 示例：
claude "What is 2 + 2?"
claude "List files in current directory"
claude "Explain this code: app.js"

方式3：打印模式（脚本友好）

bash

# 只输出AI响应,不显示格式
claude -p "你的问题"

# 示例：
claude -p "hello" > output.txt
echo "分析这段代码" | claude -p

6.2 首次启动的初始化流程

当你第一次运行 claude 时，会经历一个交互式配置向导。

配置步骤1：选择主题

? Choose your theme:
  ❯ Light (浅色主题,适合白天)
    Dark (深色主题,适合夜晚)
    System (跟随系统设置,推荐)

使用 ↑/↓ 箭头键选择，按回车确认。

主题说明：

主题	特点	适用场景
Light	浅色背景，深色文字	光线充足的环境
Dark	深色背景，浅色文字	长时间编程，护眼
System	自动跟随系统	推荐选择

配置步骤2：安全须知确认

╭─────────────────────────────────────────────────────────╮
│                     Safety Notice                       │
├─────────────────────────────────────────────────────────┤
│  Claude Code will operate in the current directory:    │
│  /Users/yourname/projects/my-app                        │
│                                                         │
│  This means Claude can:                                 │
│  ✓ Read files in this directory and subdirectories     │
│  ✓ Create new files                                    │
│  ✓ Modify existing files (with your confirmation)      │
│  ✓ Run commands (with your confirmation)               │
│                                                         │
│  Claude will NOT:                                       │
│  ✗ Access files outside this directory                 │
│  ✗ Access your personal data                           │
│  ✗ Execute commands without permission                 │
╰─────────────────────────────────────────────────────────╯

? Do you understand and accept these conditions?
  ❯ Yes, I understand and accept
    No, exit and reconsider

重要理解 - Claude Code的权限模型：

沙盒隔离 - 只能访问当前目录
确认机制 - 危险操作需要你确认
只读优先 - 默认只读，修改需授权
审计日志 - 所有操作都有记录

配置步骤3：目录信任确认

? Trust this directory?
  /Users/yourname/projects/my-app

  ❯ Yes, trust this directory
    No, exit
    Trust this directory and all parent directories

不要信任以下目录：

配置步骤4：认证方式选择

? How would you like to authenticate?

  ❯ API Key (recommended for API users)
    Use environment variable: ANTHROPIC_API_KEY
    Most flexible and secure

    Claude App Login (for Pro/Max subscribers)
    Login via browser
    Uses your subscription quota

    Manual Entry
    Enter API key now
    Stored in config file

认证方式对比：

方式	优点	缺点	推荐度
环境变量	最安全，跨项目共享	需要提前配置	⭐⭐⭐⭐⭐
App登录	使用订阅配额	需要Pro/Max订阅	⭐⭐⭐⭐
手动输入	方便	不安全，易泄露	⭐⭐

配置步骤5：完成初始化

╭─────────────────────────────────────────────────────────╮
│            Setup Complete! 🎉                           │
├─────────────────────────────────────────────────────────┤
│  Configuration summary:                                 │
│  ✓ Theme: System                                        │
│  ✓ Authentication: API Key (environment variable)      │
│  ✓ Trusted directory: /Users/yourname/projects/my-app  │
│  ✓ Model: claude-sonnet-4 (default)                    │
│                                                         │
│  Quick start:                                           │
│  • Type your message to chat with Claude               │
│  • Use /help to see available commands                 │
│  • Use /exit to quit                                    │
╰─────────────────────────────────────────────────────────╯

Claude Code v2.1.52
Working directory: /Users/yourname/projects/my-app

You: █

6.3 配置文件结构

Claude Code的配置分为全局和项目两级：

~/.claude/                      ← 全局配置目录
├── config.json                 ← 全局配置文件
├── auth-token.json             ← 认证令牌
├── trusted-directories.json    ← 信任的目录列表
├── cache/                      ← 缓存目录
└── logs/                       ← 日志目录

项目目录/.claude/              ← 项目级配置
├── config.json                 ← 项目配置（覆盖全局）
├── commands/                   ← 自定义命令
├── skills/                     ← 自定义技能
└── hooks/                      ← 自定义钩子

第6.5部分：Claude Code启动方式详解

💡 本节重点：掌握2种启动Claude Code的方式，理解权限参数的作用

6.5.1 启动方式概览

Claude Code有2种启动方式：

启动方式	适用场景	优点	缺点
终端命令启动	独立使用Claude Code	快速、灵活、支持参数	需要记命令
IDE扩展启动	在编辑器内使用	可视化、方便	需要安装扩展

💡 推荐：初学者先学终端启动，掌握后再用IDE扩展（更灵活）

6.5.2 方式一：终端命令启动（基础必学）

这是什么？ 在命令行（终端）里输入 claude 命令，直接启动Claude Code的对话界面。

为什么要学这个？

✅ 最基础的启动方式，适用所有场景
✅ 可以添加参数控制行为
✅ 支持脚本自动化

基础启动命令

最简单的启动方式：

bash

# 在任意目录下运行
claude

运行后会看到：

╭─────────────────────────────────────────────────────────╮
│                                                         │
│  Welcome to Claude Code v2.1                           │
│                                                         │
│  • Type /help to see available commands                │
│  • Use /exit to quit                                    │
╰─────────────────────────────────────────────────────────╯

Claude Code v2.1.52
Working directory: /你的当前目录

You: █

看到这个界面 → ✅ 启动成功！

带参数的启动命令

常用启动参数：

参数	作用	什么时候用
`claude`	默认启动（会询问权限）	日常使用
`claude --dangerously-skip-permissions`	跳过权限询问	信任的项目，快速开发
`claude -p "你的问题"`	直接提问模式	快速查询，不需要对话
`claude --headless`	无界面模式	脚本自动化

--dangerously-skip-permissions 详解（重要！）

这是什么？ 这个参数会让Claude Code跳过权限询问，直接执行所有操作（读文件、写文件、运行命令）。Anthropic官方称之为**"Safe YOLO mode"**（You Only Live Once模式）。

为什么叫"dangerously"（危险）？

因为Claude Code是AI助手，它可能会：

修改你的代码文件
删除文件
运行系统命令
安装/卸载软件包

如果跳过权限询问，AI做错了你可能来不及阻止！

真实风险数据（eesel AI研究）：

🚨 震惊数据：
32%的开发者使用此参数时遇到过文件误修改
9%遇到过数据损失或损坏
数据来源：https://www.ksred.com/claude-code-dangerously-skip-permissions

生活类比：

不加参数 = 保姆做事前都问你"这样行吗？"（安全）
加这个参数 = 保姆直接干，不问你（快但危险）

什么时候该用？

✅ 推荐使用场景：

你自己的个人项目（信任的代码）
快速开发，频繁修改（避免反复确认）
只读操作（查询、分析，不修改代码）
你已经很熟悉Claude Code的行为

❌ 绝对不要用：

公司项目、开源项目（不是你一个人的代码）
第一次用Claude Code（还不了解它会干什么）
生产环境代码（一个错误可能造成事故）
包含敏感数据的项目（财务、用户隐私）

安全使用建议（Anthropic官方）：

容器隔离：在Docker容器中使用（无网络访问）

白名单限制：配置 .claude/config.json

json

{
  "allowedTools": [
    "Read",
    "Grep",
    "Glob",
    "Bash(npm test)",
    "Bash(git status)"
  ]
}

Git保护：确保代码已提交，随时可回滚

使用示例：

bash

# ✅ 场景1：只读查询（安全）
claude --dangerously-skip-permissions -p "分析这个项目的依赖关系"

# ⚠️ 场景2：信任的个人项目（谨慎）
cd ~/my-toy-project
claude --dangerously-skip-permissions

# ❌ 场景3：公司项目（绝对不要）
cd ~/company-critical-project
claude --dangerously-skip-permissions  # 💀 别这么干！

⚠️ 老金的血泪建议：
新手阶段（前1个月）：绝对不要加这个参数！让AI每次操作都问你，你能学到它在做什么，还能避免误操作。
熟练阶段（1个月后）：自己的学习项目可以加，但：
✅ 代码先提交到Git
✅ 不包含重要数据
✅ 随时能删重来
专业阶段：公司项目、开源项目永远别加！老金我见过太多人用这个参数把项目搞炸了，数据来源可不是瞎说的（32%误修改率）！
参考：
官方最佳实践：https://www.anthropic.com/engineering/claude-code-best-practices
风险分析：https://claudelog.com/mechanics/dangerous-skip-permissions

启动验证清单

启动成功后，确认以下内容：

□ 看到Claude Code的欢迎界面
□ 显示正确的工作目录路径
□ 显示版本号（v2.1+）
□ 能看到 "You: █" 光标闪烁
□ 输入 /help 能看到帮助信息

全部打勾 → 🎉 启动成功！

6.5.3 方式二：IDE扩展启动（进阶）

这是什么？ 在VS Code或Cursor编辑器内安装扩展/插件，通过点击按钮或快捷键启动Claude Code，不用手敲命令。

为什么要用这个方式？

✅ 可视化界面，更直观
✅ 和编辑器深度集成
✅ 不用切换窗口

适用工具：

VS Code（需要安装Claude Code扩展）
Cursor（可以通过Tasks集成，见第7章）

VS Code扩展安装（官方扩展已发布）

✅ 2026年2月最新：Claude Code官方VS Code扩展已正式发布（Beta版）！

扩展信息：

名称：Claude Code for VS Code
发布者：Anthropic
要求：VS Code 1.98.0+
市场地址：https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code

安装步骤：

打开扩展市场
- 按 Ctrl/Cmd + Shift + X
搜索并安装
- 搜索：Claude Code
- 找到Anthropic官方扩展
- 点击"Install"
验证安装
- 左侧活动栏出现 ⚡火花图标
- 点击图标打开Claude Code面板

扩展功能（vs 终端CLI）：

✅ 侧边栏专用面板（代码和对话分离）
✅ 实时内联差异显示（修改高亮）
✅ Checkpoint自动保存（按Esc两次回滚）
✅ @提及文件/函数（智能引用）

参考文档：https://code.claude.com/docs/en/vs-code

Cursor集成方式（需要手动安装）

重要提示：Cursor虽然基于VS Code，但Claude Code扩展不能自动检测Cursor为兼容IDE。

解决方案（社区验证100%成功）：手动安装VSIX文件

步骤：

找到VSIX文件
- 位置：本地Claude Code安装目录
- 或从VS Code Marketplace下载VSIX

手动安装到Cursor

bash

# 方法1：命令行安装
cursor --install-extension /path/to/claude-code.vsix

# 方法2：拖拽安装
# 把VSIX文件拖到Cursor的扩展面板

验证安装
- 重启Cursor
- 左侧应出现Claude Code图标

详细教程：https://www.cursor-ide.com/blog/claude-code-cursor-extension-guide

替代方案：Tasks集成（推荐新手）

如果扩展安装失败，可以用Tasks方式（见第7.1节配置）：

配置 tasks.json
通过命令面板运行任务
效果类似但更稳定

6.5.4 启动方式选择建议

你的情况	推荐方式	原因
刚开始学习	终端命令启动	理解基础，灵活
熟悉后日常使用	终端 + IDE快捷键	效率最高
只想快速体验	终端命令启动	最简单
需要自动化	终端 + 参数	支持脚本

老金的建议： 先用终端命令启动，等你熟悉了Claude Code的行为，再配置IDE快捷键。这样基础扎实，以后遇到问题好排查！

6.6 Hello World 快速验证

💡 重要：启动成功后，立即做这个快速验证，确保Claude Code能正常工作！这样后面配置IDE时心里有底。

6.6.1 基础功能测试（5分钟）

快速7项测试，确认核心功能正常：

bash

# 测试1：版本检查
claude --version
# 预期输出：Claude Code v2.1.x (native)

# 测试2：简单问答
claude -p "What is 2 + 2?"
# 预期输出：4

# 测试3：中文支持
claude -p "你好,请用一句话介绍你自己"
# 预期输出：中文回复（确认中文正常）

# 测试4：帮助命令
claude --help
# 预期输出：显示所有可用命令

如果以上4项全部成功 → ✅ Claude Code工作正常，继续往下！

如果有失败 → ⚠️ 跳到第8部分故障排查

6.6.2 Hello World 项目实战（15分钟）

这是什么？ 创建一个完整的小项目，测试Claude Code的文件操作、代码生成、测试生成等核心功能。

为什么要做？ 快速测试能发现99%的配置问题，避免后续出错。

操作步骤：

bash

# 步骤1：创建项目目录
mkdir ~/claude-hello-world
cd ~/claude-hello-world

# 步骤2：初始化Git仓库
git init

# 步骤3：让Claude创建项目结构
claude -p "请创建一个Python Hello World项目，包含：
1. hello.py - 打印 'Hello, Claude Code!'
2. README.md - 项目说明
3. .gitignore - Python标准忽略文件"

# 步骤4：验证文件是否创建
ls -la
# 预期看到：hello.py, README.md, .gitignore

# 步骤5：运行程序
python hello.py
# 预期输出：Hello, Claude Code!

预期项目结构：

claude-hello-world/
├── .git/
├── .gitignore
├── hello.py
└── README.md

验证成功标志：

✅ 文件自动创建成功
✅ Python程序能正常运行
✅ Claude理解你的中文指令

6.6.3 完整验证清单

启动和验证都成功后，最后确认：

验证项	命令	预期结果	状态
版本信息	`claude --version`	v2.1.x+ (native)	[ ]
帮助文档	`claude --help`	显示命令列表	[ ]
API Key	`echo $ANTHROPIC_API_KEY`	显示完整Key	[ ]
网络连通	`ping api.anthropic.com`	有响应	[ ]
文件操作	Hello World项目	成功创建文件	[ ]
代码执行	`python hello.py`	正常输出	[ ]

全部打勾 → 🎉 恭喜！Claude Code安装和配置完全成功！

现在你可以：

✅ 继续学习第7部分（IDE集成配置）
✅ 跳过第7部分，直接开始用Claude Code写项目
✅ 查看第9部分FAQ了解更多技巧

第七部分：IDE 集成配置

⚠️ 重要提示：这部分是可选的高级配置！
前置条件：第6部分的Hello World验证必须成功，否则别急着配置IDE！
适合人群：
✅ 已经成功启动Claude Code并完成Hello World测试
✅ 想在VS Code/Cursor里更方便地使用Claude Code
✅ 愿意花30分钟配置快捷键和任务
如果你只想用终端命令：可以跳过这部分，直接用 claude 命令就够了！

7.1 VS Code 完整集成方案

💡 这一节讲什么：配置VS Code/Cursor编辑器，让它能完美运行Claude Code命令。配置后你就能在编辑器里一键调用AI助手了。

步骤1：VS Code基础配置

首先确保VS Code已安装最新版本：

bash

# 检查VS Code版本
code --version

# 如果未安装，访问：https://code.visualstudio.com/

⚠️ Cursor用户注意：Cursor是基于VS Code魔改的编辑器，所有VS Code的配置在Cursor里都能用！如果你用Cursor，把下面的"VS Code"理解成"Cursor"就行。

步骤2：配置集成终端

这是什么？ "集成终端"就是编辑器下方那个黑框框（或白框框），用来运行命令的地方。配置它就是告诉编辑器："用哪个翻译器来执行我的命令"。

为什么要配置？ 不配置的话，编辑器可能用错误的"翻译器"（Shell），导致命令运行失败或报错。

操作方法： 打开设置（Ctrl/Cmd + ,），点击右上角"打开设置(JSON)"，添加：

json

{
  // ==========================================
  // 终端配置（告诉编辑器用哪个"翻译器"）
  // ==========================================

  // Windows用户 → 用PowerShell（Windows推荐的命令行工具）
  "terminal.integrated.defaultProfile.windows": "PowerShell",

  // Mac用户 → 用zsh（Mac 2019年后的默认Shell，比bash更现代）
  "terminal.integrated.defaultProfile.osx": "zsh",

  // Linux用户 → 用bash（Linux通用Shell）
  "terminal.integrated.defaultProfile.linux": "bash",

  // ==========================================
  // PowerShell 7配置（Windows推荐）
  // ==========================================
  // 指定用PowerShell 7而不是老版PowerShell 5.1
  // PowerShell 7功能更强大，跨平台，推荐使用
  "terminal.integrated.profiles.windows": {
    "PowerShell": {
      "source": "PowerShell",
      "icon": "terminal-powershell",
      "path": "pwsh.exe"  // pwsh.exe = PowerShell 7
    }
  },

  // ==========================================
  // 终端外观配置（让终端更好看）
  // ==========================================
  "terminal.integrated.fontFamily": "Menlo, Monaco, 'Courier New', monospace",
  "terminal.integrated.fontSize": 13,  // 13号字体，比默认稍大，更舒适

  // ==========================================
  // Claude Code专用配置
  // ==========================================
  // 让CLAUDE.md文件有Markdown语法高亮
  "files.associations": {
    "CLAUDE.md": "markdown"
  },

  // ==========================================
  // 自动保存（强烈推荐！）
  // ==========================================
  "files.autoSave": "afterDelay",  // 编辑后自动保存，不怕忘记保存丢失改动
  "files.autoSaveDelay": 1000      // 延迟1秒（1000毫秒）保存
}

💡 配置说明（小白版）：
配置项人话翻译为啥要配
defaultProfile.windows Windows用PowerShell 确保命令能正常运行
defaultProfile.osx Mac用zsh Mac最新系统的默认Shell
defaultProfile.linux Linux用bash Linux通用Shell
profiles.windows 用PowerShell 7 比老版更强大
fontSize: 13 终端字体13号比默认大一点，看着舒服
CLAUDE.md 识别Claude配置文件有语法高亮，好编辑
autoSave 自动保存不怕忘记保存丢失改动
生活类比：把电脑想象成一家国际餐厅
中文服务员 = zsh（Mac专用）
英文服务员 = PowerShell（Windows专用）
通用服务员 = bash（大家都能用）
这个配置就是在告诉餐厅："我需要中文服务员/英文服务员来服务"。

配置项	人话翻译	为啥要配
`defaultProfile.windows`	Windows用PowerShell	确保命令能正常运行
`defaultProfile.osx`	Mac用zsh	Mac最新系统的默认Shell
`defaultProfile.linux`	Linux用bash	Linux通用Shell
`profiles.windows`	用PowerShell 7	比老版更强大
`fontSize: 13`	终端字体13号	比默认大一点，看着舒服
`CLAUDE.md`	识别Claude配置文件	有语法高亮，好编辑
`autoSave`	自动保存	不怕忘记保存丢失改动

验证配置是否生效：

按 Ctrl + ` （Esc键下面那个键）打开终端
运行验证命令：

Windows用户：

powershell

# 查看PowerShell版本
$PSVersionTable.PSVersion
# 预期输出：显示版本号，比如 7.4.0

Mac/Linux用户：

bash

# 查看当前Shell类型
echo $SHELL
# 预期输出Mac：/bin/zsh
# 预期输出Linux：/bin/bash

如果显示正确 → ✅ 配置成功！

步骤3：创建VS Code任务（可选但推荐）

这是什么？ "任务（Task）"就是把常用命令做成一键按钮。比如"启动Claude Code"、"审查当前文件"这些操作，不用每次手敲命令，点一下就能执行。

为什么要创建？ 类比：不用任务 = 每次都要手动打开微信；用任务 = 桌面有微信图标，一键打开。

操作方法： 在项目根目录创建 .vscode/tasks.json：

json

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Claude Code: 启动交互模式",
      "type": "shell",
      "command": "claude",
      "problemMatcher": [],
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": true,
        "panel": "dedicated",
        "clear": true
      }
    },
    {
      "label": "Claude Code: 审查当前文件",
      "type": "shell",
      "command": "claude \"Review ${relativeFile} and suggest improvements\"",
      "problemMatcher": []
    },
    {
      "label": "Claude Code: 解释当前文件",
      "type": "shell",
      "command": "claude \"Explain what ${relativeFile} does\"",
      "problemMatcher": []
    },
    {
      "label": "Claude Code: 生成测试",
      "type": "shell",
      "command": "claude \"Generate unit tests for ${relativeFile}\"",
      "problemMatcher": []
    }
  ]
}

使用任务：

方法1：命令面板（推荐）

按 Ctrl/Cmd + Shift + P（打开命令面板）
输入：Tasks: Run Task
选择你要运行的任务，比如"Claude Code: 启动交互模式"

方法2：菜单操作 点击菜单 Terminal → Run Task...

💡 任务说明：
任务名称作用使用场景
启动交互模式一键启动Claude Code 开始编程前
审查当前文件让Claude检查代码质量写完代码想优化时
解释当前文件让Claude解释代码逻辑看不懂别人代码时
生成测试自动生成单元测试需要写测试时

任务名称	作用	使用场景
启动交互模式	一键启动Claude Code	开始编程前
审查当前文件	让Claude检查代码质量	写完代码想优化时
解释当前文件	让Claude解释代码逻辑	看不懂别人代码时
生成测试	自动生成单元测试	需要写测试时

步骤4：配置快捷键（可选）

这是什么？ 给刚才创建的"任务"绑定键盘快捷键，比如按 Ctrl+Shift+C 就能启动Claude Code，连菜单都不用点。

为什么要配置？ 更快！按一个键盘快捷键 vs 打开菜单找任务，哪个快？当然是快捷键！

操作方法： 创建或编辑 .vscode/keybindings.json：

json

[
  {
    "key": "ctrl+shift+c",  // 快捷键：Ctrl+Shift+C
    "command": "workbench.action.tasks.runTask",
    "args": "Claude Code: 启动交互模式"  // 执行哪个任务
  },
  {
    "key": "ctrl+shift+r",  // 快捷键：Ctrl+Shift+R
    "command": "workbench.action.tasks.runTask",
    "args": "Claude Code: 审查当前文件"
  },
  {
    "key": "ctrl+shift+e",  // 快捷键：Ctrl+Shift+E
    "command": "workbench.action.tasks.runTask",
    "args": "Claude Code: 解释当前文件"
  }
]

💡 快捷键说明：
快捷键执行任务记忆方法
Ctrl+Shift+C 启动Claude Code C = Claude
Ctrl+Shift+R 审查当前文件 R = Review
Ctrl+Shift+E 解释当前文件 E = Explain
⚠️ Mac用户：把 ctrl 改成 cmd 即可

快捷键	执行任务	记忆方法
`Ctrl+Shift+C`	启动Claude Code	C = Claude
`Ctrl+Shift+R`	审查当前文件	R = Review
`Ctrl+Shift+E`	解释当前文件	E = Explain

7.2 Cursor 编辑器集成

Cursor是什么？ Cursor是基于VS Code魔改的AI编辑器，自带AI助手。和Claude Code配合使用，效果更好！

Cursor独特优势：

✓ 内置AI对话面板（不用切换工具）
✓ AI代码补全（边写边提示）
✓ 与Claude Code互补而非冲突（两个AI工具不打架）

💡 重要提示：Cursor的所有配置和VS Code完全相同！上面第7.1节的配置，在Cursor里一字不差地照搬就行。

唯一不同：打开设置文件的方法

Cursor界面和VS Code略有不同，打开设置JSON文件的方法如下：

方法 A：用命令面板打开（最推荐）

步骤：

在 Cursor 按 Ctrl + Shift + P（打开命令面板）
输入：open user settings（不区分大小写）
选择：Preferences: Open User Settings (JSON) 或中文：首选项: 打开用户设置(JSON)
自动打开 settings.json 文件

打开快捷键配置同理：

输入：open keyboard shortcuts
选择：Preferences: Open Keyboard Shortcuts (JSON) 或中文：首选项: 打开键盘快捷方式(JSON)

方法 B：直接打开文件路径（万能方法）

如果方法A找不到菜单（Cursor版本不同可能有差异），用这个方法100%有效：

步骤：

在 Cursor 按 Ctrl + P（快速打开文件）
粘贴下面对应你系统的路径，按回车：

Windows系统：

C:\Users\你的用户名\AppData\Roaming\Cursor\User\settings.json

Mac系统：

~/Library/Application Support/Cursor/User/settings.json

⚠️ 注意：把"你的用户名"改成你电脑的实际用户名！比如你的用户名是 admin，路径就是 C:\Users\admin\AppData\...

配置完成后，Cursor就能完美运行Claude Code了！

Cursor的配置与VS Code完全相同，如果上面VSCode中配置过，可以直接复用上面的配置：

bash

# 将VS Code配置复制到Cursor
# macOS/Linux:
cp -r ~/project/.vscode ~/project/.cursor

# Windows:
xcopy /E /I %USERPROFILE%\project\.vscode %USERPROFILE%\project\.cursor

推荐工作流：

场景	使用工具	原因
快速代码补全	Cursor内置AI	快速，无需切换
复杂逻辑重构	Claude Code	更强推理能力
代码审查	Claude Code	更全面上下文理解
生成测试	Claude Code	更完整测试覆盖

7.3 JetBrains IDEs 集成

适用于WebStorm、PyCharm、IntelliJ IDEA等。

步骤1：配置External Tools

打开设置：
- Windows/Linux: File → Settings → Tools → External Tools
- macOS: Preferences → Tools → External Tools
点击 + 添加新工具：

Tool 1：Claude Code交互模式

字段	值
Name	Claude Code
Program	claude
Arguments	（留空）
Working directory	$ProjectFileDir$

Tool 2：审查当前文件

字段	值
Name	Claude: Review File
Program	claude
Arguments	`"Review $FilePath$ and suggest improvements"`
Working directory	$ProjectFileDir$

步骤2：配置快捷键

Settings → Keymap
搜索 External Tools
右键 → Add Keyboard Shortcut
设置快捷键（如 Ctrl+Shift+C）

第八部分：故障排查

8.1 平台特定问题

Windows平台

问题1：PowerShell执行策略限制

powershell

# 错误信息（原生安装时可能遇到）
claude : 无法加载文件，因为在此系统上禁止运行脚本。

原因：Windows默认安全策略禁止运行未签名脚本

解决方案：

powershell

# 方法1：修改执行策略（管理员PowerShell）- 推荐
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# 方法2：使用CMD而不是PowerShell
# Win+R → cmd

# 方法3：每次临时允许执行
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

问题2：Windows Defender误报

bash

# 症状：安装过程中文件被删除
# 原因：Windows Defender将claude.exe识别为潜在威胁

# 解决方案
# 1. 添加claude-code目录到排除列表
#    Windows安全 → 病毒和威胁防护 → 排除项
#    添加：C:\Users\<用户名>\AppData\Local\claude-code

# 2. 临时禁用实时保护（不推荐）

问题3：命令找不到

bash

# 症状
'claude' 不是内部或外部命令

原因：原生安装目录未添加到PATH

解决方案：

bash

# 原生安装应该自动配置PATH
# 如果遇到此问题，手动添加：
# Win+R → sysdm.cpl → 高级 → 环境变量
# 用户变量的Path中添加：
# C:\Users\<用户名>\AppData\Local\claude-code

macOS平台

问题1：命令找不到但已安装

bash

# 症状
claude: command not found

# 原因：PATH未更新（原生安装应该自动配置）

# 解决方案：检查原生安装位置
ls ~/.local/bin/claude
# 或
ls /usr/local/bin/claude

# 如果文件存在，添加到PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

问题2：macOS Gatekeeper阻止

bash

# 症状
"claude" cannot be opened because the developer cannot be verified

# 解决方案
# 方法1：移除隔离属性
sudo xattr -r -d com.apple.quarantine ~/.local/bin/claude

# 方法2：在系统设置中允许
# 系统设置 → 隐私与安全性 → 点击"仍要打开"

8.2 原生安装常见问题

问题1：安装脚本下载失败

bash

# 症状
curl: (7) Failed to connect to claude.ai port 443

原因：网络无法访问claude.ai

解决方案：

bash

# 方案1：配置代理
export https_proxy=http://127.0.0.1:7890
curl -fsSL https://claude.ai/install.sh | bash

# 方案2：使用包管理器（Homebrew/WinGet）
brew install --cask claude-code
# 或
winget install Anthropic.ClaudeCode

# 方案3：手动下载安装包
# 访问 https://claude.ai/download 下载对应平台的安装包

问题2：安装版本不是最新

bash

claude --version
# 显示版本较旧

解决方案：

bash

# 原生安装支持自动更新，运行：
claude update

# 或重新运行安装脚本
curl -fsSL https://claude.ai/install.sh | bash

问题3：检测到旧的npm安装

bash

claude --version
# 显示 (npm) 而不是 (native)

解决方案：

bash

# 运行迁移命令
claude install

# 这会自动：
# 1. 检测到npm版本
# 2. 下载原生版本
# 3. 卸载npm版本
# 4. 配置PATH

8.3 网络连接问题

问题：无法访问api.anthropic.com

bash

ping api.anthropic.com
# 请求超时

解决方案：

bash

# 方案1：配置代理（推荐）
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
# Windows PowerShell：
$env:https_proxy="http://127.0.0.1:7890"
$env:http_proxy="http://127.0.0.1:7890"

# 方案2：修改DNS
# Windows：设置DNS为8.8.8.8或114.114.114.114
# macOS/Linux：编辑/etc/resolv.conf添加nameserver 8.8.8.8

# 方案3：使用API中转服务
# 设置自定义API端点（见第三部分API Key配置）

问题2：SSL证书错误

症状：

bash

claude
# Error: unable to verify the first certificate

解决方案：

powershell

# Windows：通过Windows Update更新根证书
Start-Process ms-settings:windowsupdate

# macOS：系统自动维护，确保系统保持最新
# 系统设置 → 通用 → 软件更新

# Linux：更新CA证书
sudo apt update && sudo apt upgrade ca-certificates
# 或
sudo yum update ca-certificates

问题3：API连接超时


### 8.4 API Key 配置问题

**问题：环境变量未生效**

```bash
echo $ANTHROPIC_API_KEY
# 显示为空

解决方案：

bash

# macOS/Linux：确认配置文件
cat ~/.zshrc | grep ANTHROPIC
# 应该看到：export ANTHROPIC_API_KEY="sk-ant-..."

# 如果没有，手动添加
echo 'export ANTHROPIC_API_KEY="你的key"' >> ~/.zshrc
source ~/.zshrc

Windows：

powershell

# 检查是否配置
[System.Environment]::GetEnvironmentVariable('ANTHROPIC_API_KEY', 'User')

# 如果为空，重新配置
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-api03-你的key', 'User')

# 重启PowerShell

问题：Key无效或过期

json

{
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

解决方法：

登录 console.anthropic.com
Settings → API Keys
检查Key是否被删除或禁用
如果无效，创建新Key
更新环境变量

问题3：Key格式错误

症状：Key看起来不完整或有空格

正确格式检查（PowerShell 7）：

powershell

# Key应该满足：
# 1. 以"sk-ant-api03-"开头
# 2. 后面跟长串字母数字
# 3. 总长度约95字符
# 4. 无空格、无换行

# 验证长度
$env:ANTHROPIC_API_KEY.Length
# 应该输出：95左右

# 验证格式
$env:ANTHROPIC_API_KEY -match '^sk-ant-api03-[A-Za-z0-9_-]+$'
# 应该输出：True

常见格式错误：

bash

❌ sk-ant-XXXXX （缺少api03）
❌ sk-XXXXX （缺少ant-api03）
❌ 有空格或换行符
❌ 复制时多复制/少复制字符

8.5 终端相关问题

问题：中文乱码（Windows）

bash

# 临时切换到UTF-8
chcp 65001

# 永久设置
reg add HKCU\Console /v CodePage /t REG_DWORD /d 65001 /f

PowerShell中文显示：

powershell

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

问题3：复制粘贴不工作

不同终端的复制粘贴快捷键不同：

Windows Terminal：

右键选中文本自动复制
Ctrl+Shift+C 复制
Ctrl+Shift+V 粘贴

Windows CMD：

右键 → 标记 → 选中文本 → 回车复制
右键粘贴

macOS Terminal：

Cmd+C 复制
Cmd+V 粘贴

Linux终端：

Ctrl+Shift+C 复制
Ctrl+Shift+V 粘贴
或鼠标中键粘贴（选中即复制）

问题4：命令历史记录丢失

症状：重启终端后之前输入的命令无法通过上下箭头找回

PowerShell 7配置：

powershell

# PowerShell 7默认已配置历史记录
# 查看历史记录位置
$env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine\

# 增强历史记录功能（编辑PowerShell配置文件）
notepad $PROFILE

# 添加以下内容：
Set-PSReadLineOption -HistorySearchCursorMovesToEnd
Set-PSReadLineOption -MaximumHistoryCount 10000
Set-PSReadLineKeyHandler -Key UpArrow -Function HistorySearchBackward
Set-PSReadLineKeyHandler -Key DownArrow -Function HistorySearchForward

Bash/Zsh配置（macOS/Linux）：

bash

# 确认历史记录文件
echo $HISTFILE
# 应该是~/.bash_history或~/.zsh_history

# 如果为空，添加到配置
# Zsh用户（编辑~/.zshrc）：
echo 'export HISTFILE=~/.zsh_history' >> ~/.zshrc
echo 'export HISTSIZE=10000' >> ~/.zshrc
echo 'export SAVEHIST=10000' >> ~/.zshrc
source ~/.zshrc

# Bash用户（编辑~/.bashrc）：
echo 'export HISTFILE=~/.bash_history' >> ~/.bashrc
echo 'export HISTSIZE=10000' >> ~/.bashrc
echo 'export HISTFILESIZE=20000' >> ~/.bashrc
source ~/.bashrc

验证历史记录：

powershell

# PowerShell 7
Get-History

# Bash/Zsh
history | tail -20

第九部分：学员常见问题FAQ

💡 本节收录：直播课程中学员最常问的20个问题，帮你避开90%的坑！

9.1 安装与配置类

Q1：运行 `code --version` 报错说找不到命令？

A1：你可能在Cursor里运行的！

code 是 VS Code 的命令
cursor 是 Cursor 的命令

正确做法：

在Cursor里运行：cursor --version
在VS Code里运行：code --version
查看Claude Code版本：claude --version

Q2：找不到settings.json文件在哪儿？

A2：不同编辑器位置不同！

Cursor位置：

Windows: C:\Users\你的用户名\AppData\Roaming\Cursor\User\settings.json
Mac: ~/Library/Application Support/Cursor/User/settings.json

VS Code位置：

Windows: C:\Users\你的用户名\AppData\Roaming\Code\User\settings.json
Mac: ~/Library/Application Support/Code/User/settings.json

快速打开方法：

按 Ctrl/Cmd + Shift + P
输入：open user settings json
选择：Preferences: Open User Settings (JSON)

Q3：配置后还是报错，怎么办？

A3：按照这个检查清单逐项排查：

□ settings.json文件保存了吗？（看文件名有没有*号）
□ JSON格式正确吗？（大括号、逗号、引号都对吗）
□ 重启了终端吗？（配置需要重启终端才生效）
□ 重启了编辑器吗？（有时需要完全重启）

还是不行？ 把错误信息截图，群里问老金！

Q4：zsh、PowerShell、bash 有什么区别？我该用哪个？

A4：它们都是Shell（命令行翻译器），选对应你系统的就行！

操作系统	推荐Shell	为什么
Windows	PowerShell	系统自带，功能强大
Mac	zsh	2019年后的系统默认
Linux	bash	通用标准

你不用手动选，按照第7.1节配置后，编辑器会自动选对的！

Q5：怎么知道我现在用的是哪个Shell？

A5：打开终端运行这个命令：

bash

echo $SHELL

看输出：

显示 /bin/zsh → 你在用zsh
显示 /bin/bash → 你在用bash
Windows显示 powershell → 你在用PowerShell

9.2 启动与使用类

Q6：怎么启动Claude Code？

A6：有2种方式，推荐第1种！

方式1：终端命令启动（推荐）

bash

# 进入项目目录
cd /你的项目路径

# 启动Claude Code
claude

方式2：IDE快捷键启动

配置tasks.json（见第7.1节）
按 Ctrl/Cmd + Shift + P → 选 Tasks: Run Task → 选 Claude Code: 启动交互模式

Q7：启动后看到什么才算成功？

A7：看到这个界面就成功了：

╭─────────────────────────────────────────╮
│  Welcome to Claude Code v2.1           │
│  • Type /help to see available commands │
╰─────────────────────────────────────────╯

You: █

关键要素：

✅ 显示欢迎信息
✅ 显示版本号（v2.1+）
✅ 显示工作目录
✅ 有输入光标 █

Q8：`--dangerously-skip-permissions` 是什么？我该用吗？

A8：这个参数跳过权限询问，新手别用！

通俗解释：

不加参数 = AI做事前都问你"可以吗？"
加参数 = AI直接干，不问你

老金建议：

🟢 新手（前2周）：别加！让AI问你，你能学到它在做什么
🟡 熟练后：自己的小项目可以加，省时间
🔴 重要项目：永远别加！安全第一

详细说明见第6.5.2节。

Q9：启动Claude Code后怎么退出？

A9：两种方法：

方法1：命令退出

bash

/exit

方法2：快捷键退出

按 Ctrl + C 两次
或 Ctrl + D

Q10：能同时打开多个Claude Code吗？

A10：可以！每个终端窗口都能启动一个Claude Code实例。

使用场景：

窗口1：处理前端代码
窗口2：处理后端代码
窗口3：运行测试

9.3 配置文件类

Q11：tasks.json文件放在哪里？

A11：放在项目根目录的 .vscode 文件夹里！

完整路径示例：

你的项目/
├── .vscode/
│   └── tasks.json  ← 放这里
├── src/
└── package.json

创建步骤：

在项目根目录创建 .vscode 文件夹（如果没有）
在 .vscode 里创建 tasks.json 文件
复制第7.1节的配置粘贴进去
保存

Q12：配置后快捷键不生效？

A12：检查这些：

□ keybindings.json保存了吗？
□ 快捷键有冲突吗？（换个组合试试）
□ 重启编辑器了吗？

查看快捷键冲突：

按 Ctrl/Cmd + K, Ctrl/Cmd + S（打开快捷键设置）
搜索你配置的快捷键
看是否有其他命令占用

Q13：粘贴配置后报JSON错误？

A13：99%是格式问题！

常见错误：

错误	原因	解决
`Unexpected token`	多了/少了逗号	最后一项配置不要逗号
`Invalid character`	中文引号	把 `""` 改成 `""`
`Unexpected end`	大括号不匹配	数数 `{` 和 `}` 是否相等

快速检查：

用在线工具检查JSON格式：https://jsonlint.com/
复制你的配置粘贴进去，它会告诉你哪里错了

9.4 权限与安全类

Q14：Claude Code会偷偷上传我的代码吗？

A14：不会！Claude Code只上传你让它处理的内容。

工作原理：

你问问题 → Claude Code读取相关文件
把文件内容发给Anthropic API处理
收到AI回复后显示给你

隐私保护：

✅ 只上传你明确要求处理的文件
✅ 你可以通过权限控制它能访问什么
✅ 不会后台扫描或上传整个项目

Q15：我不想让Claude Code访问某些文件，怎么办？

A15：用 .gitignore 或 .claudeignore 排除！

方法1：.gitignore（推荐） Claude Code默认会忽略 .gitignore 里的文件。

方法2：.claudeignore 在项目根目录创建 .claudeignore 文件：

# 不让Claude访问的文件
.env
*.key
secrets/
config/production.json

9.5 网络与性能类

Q16：Claude Code响应很慢，怎么优化？

A16：检查网络和上下文大小！

网络检查：

bash

# 测试到Anthropic的延迟
ping api.anthropic.com
# 延迟<500ms = 正常，>1000ms = 慢

优化方法：

✅ 使用代理（国内用户必需）
✅ 减少上下文（不要让AI读太多文件）
✅ 使用 .claudeignore 排除无关文件

Q17：国内网络访问Anthropic API很慢？

A17：配置代理！

临时代理（当前终端生效）：

bash

# macOS/Linux
export HTTPS_PROXY=http://127.0.0.1:7890

# Windows PowerShell
$env:HTTPS_PROXY="http://127.0.0.1:7890"

永久代理（推荐）： 在 ~/.zshrc 或 ~/.bashrc 添加：

bash

export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

9.6 错误信息类

Q18：启动时报错 `claude: command not found`？

A18：Claude Code没安装或PATH未配置！

解决步骤：

检查是否安装：
bash
```
claude --version
```
1

如果提示命令找不到：

macOS/Linux:

bash

# 检查安装位置
ls ~/.local/bin/claude

# 如果存在，添加到PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows:

powershell

# 检查安装位置
ls $env:LOCALAPPDATA\claude-code

# 如果存在，手动添加到PATH
# 系统设置 → 环境变量 → 用户变量的Path → 添加：
# C:\Users\你的用户名\AppData\Local\claude-code\bin

如果确实没安装：

macOS/Linux:

bash

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

Windows:

powershell

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

Q19：启动时报错 `API key not found`？

A19：没配置ANTHROPIC_API_KEY环境变量！

快速检查：

bash

# 查看环境变量是否存在
echo $ANTHROPIC_API_KEY  # macOS/Linux
echo $env:ANTHROPIC_API_KEY  # Windows

如果显示空 → 没配置，回到第四部分重新配置。

Q20：我之前用npm安装过Claude Code，怎么办？

A20：官方提供了迁移命令！

bash

# 一键迁移到原生版本
claude install

这个命令会：

下载并安装原生版本
保留你的所有配置
自动卸载旧的npm版本

验证迁移成功：

bash

claude --version
# 应显示：Claude Code v2.1.x (native)
# 而不是：(npm)

如果迁移失败，手动卸载npm版本：

bash

npm uninstall -g @anthropic-ai/claude-code
# 然后重新运行原生安装

Q21：原生安装和npm安装有什么区别？

A21：简单来说，原生安装更简单更稳定！

对比项	原生安装 ⭐	npm安装（已废弃）
需要Node.js	❌ 不需要	✅ 必须安装
安装时间	⏱️ 3-5分钟	⏱️ 30-40分钟
自动更新	✅ 后台自动	❌ 需手动运行
PATH配置	✅ 自动完成	⚠️ 经常出错
稳定性	✅ 生产级	⚠️ 依赖环境

Q22：原生安装可以离线使用吗？

A22：可以！安装后只需要网络访问API即可。

✅ 安装时需要网络（下载安装包）
✅ 安装后可以离线使用（但需要能访问Anthropic API）
✅ 配合本地模型（如Ollama）可以完全离线

Q23：原生安装会占用多少空间？

A23：大约100-200MB。

Windows: ~150MB 在 C:\Users\你的用户名\AppData\Local\claude-code\
macOS/Linux: ~100MB 在 ~/.local/bin/ 和 ~/.claude/

相比npm安装节省约50%空间。

Q24：我电脑上已经有Node.js了，还需要卸载吗？

A24：不需要！可以共存。

✅ Node.js可以继续用于其他项目
✅ Claude Code原生安装不影响Node.js
✅ 如果你不用Node.js做开发，可以考虑卸载节省空间

Q25：原生安装会自动更新吗？可以关闭吗？

A25：默认自动更新，可以关闭。

查看更新状态：

bash

claude --version
# 查看当前版本

禁用自动更新：

bash

# macOS/Linux
export CLAUDE_AUTO_UPDATE=false

# Windows PowerShell
$env:CLAUDE_AUTO_UPDATE="false"

手动更新：

bash

claude install
# 重新运行安装命令即可更新

Q26：公司电脑安装需要管理员权限吗？

A26：Windows需要，Mac/Linux不需要！

Windows：

⚠️ 建议以管理员身份运行PowerShell
原因：需要写入 AppData 目录

macOS/Linux：

✅ 不需要sudo
安装到用户目录 ~/.local/bin/

Q27：安装脚本安全吗？会不会有病毒？

A27：官方脚本，经过签名和验证！

安全验证：

官方域名：claude.ai/install.sh 和 claude.ai/install.ps1
代码签名：由Anthropic PBC签名
开源透明：脚本内容可在GitHub公开查看

如果你担心，可以先查看脚本：

bash

# 只下载不执行
curl -fsSL https://claude.ai/install.sh
# 阅读后觉得安全再执行
curl -fsSL https://claude.ai/install.sh | bash

Q28：我的问题不在这里，怎么办？

A20：这样做：

✅ 运行 claude --help 查看官方帮助
✅ 查看日志文件：~/.claude/logs/ 找错误信息
✅ 访问官方文档：https://docs.claude.ai/code
✅ GitHub搜索类似问题：https://github.com/anthropics/claude-code/issues
✅ 把错误信息截图，在学习群里问老金！

提问时请提供：

操作系统和版本
Claude Code版本（claude --version）
完整错误信息（截图或复制文字）
你做了什么操作

总结与检查清单

完成本课后，请确认以下所有项：

系统要求：

操作系统兼容（Windows 10+ / macOS 10.15+ / Linux）
终端可用（PowerShell / Terminal / Bash）
至少2GB可用磁盘空间

账号准备：

注册了Anthropic账号（或使用中转站）
获取了API Key
Key已保存到安全位置

系统配置：

环境变量ANTHROPIC_API_KEY已配置
终端能正确显示中文
网络能访问api.anthropic.com（或配置了代理）

Claude Code安装：

Claude Code原生安装成功
claude --version 显示正确版本（带native标识）
claude --help 显示帮助信息

功能验证：

通过基础测试套件
完成Hello World项目
IDE集成配置完成（可选）

如果以上全部勾选，恭喜你已经完成准备工作！🎉

⚠️ 2026年更新说明：本课程已更新为原生安装方式，不再需要Node.js和npm！如果你是从旧版教程过来的，注意核对清单中已删除Node.js相关项。

附录

A. 常用命令速查

bash

# Claude Code版本和帮助
claude --version           # 查看版本（应显示native标识）
claude --help              # 查看帮助
claude /doctor             # 系统诊断

# Claude Code操作
claude                     # 进入交互模式
claude "你的问题"          # 单次提问
claude -p "问题"           # 打印模式（脚本友好）

# 更新Claude Code
claude install             # 重新安装/更新到最新版本

# 环境变量查看
$env:ANTHROPIC_API_KEY     # PowerShell 7（推荐）
echo $ANTHROPIC_API_KEY    # macOS/Linux
echo %ANTHROPIC_API_KEY%   # Windows CMD（不推荐）

# 网络测试
ping api.anthropic.com     # 测试连通性
curl -I https://api.anthropic.com  # 测试HTTPS访问

# 配置管理
claude config list         # 查看所有配置
claude config get <key>    # 查看特定配置
claude config set <key> <value>  # 设置配置

B. 从npm迁移到原生安装

如果你之前通过npm安装过Claude Code，请按以下步骤迁移：

步骤1：检查当前安装方式

bash

claude --version
# 如果显示 (npm) → 需要迁移
# 如果显示 (native) → 已经是原生版本

步骤2：运行迁移命令

bash

claude install

步骤3：验证迁移成功

bash

claude --version
# 应显示：Claude Code v2.1.x (native)

步骤4：卸载npm版本（可选）

bash

npm uninstall -g @anthropic-ai/claude-code

迁移时会保留：

✅ 所有配置文件（~/.claude/）
✅ API Key配置
✅ 自定义命令和技能
✅ 信任目录设置

特殊场景：使用nvm的用户

如果你用nvm管理多个Node版本，可能需要手动处理：

bash

# 1. 对每个Node版本卸载
nvm use 20
npm uninstall -g @anthropic-ai/claude-code

nvm use 22
npm uninstall -g @anthropic-ai/claude-code

# 2. 然后运行原生安装
claude install

# 3. 清理nvm shims
rm ~/.asdf/shims/claude  # 如果你用asdf

C. 推荐学习资源

Claude Code官方文档：

英文：https://docs.anthropic.com/en/docs/claude-code
中文：https://code.claude.com/docs/en/

Anthropic API文档：

https://docs.anthropic.com/

终端使用教程：

Windows Terminal：https://learn.microsoft.com/zh-cn/windows/terminal/
macOS终端：https://support.apple.com/zh-cn/guide/terminal/

社区支持：

Claude Discord：https://discord.gg/anthropic
GitHub Discussions：https://github.com/anthropics/claude-code/discussions

课程制作：老金 最后更新：2026年2月（原生安装版本）版本：V3.0（原生安装重大更新版）许可：本课程采用CC BY-NC-SA 4.0许可

版本更新日志

V3.0 重大更新（2026-02-02）

更新项	变化说明
安装方式	从npm安装切换到原生安装
Node.js	不再需要Node.js和npm
安装时间	从40分钟缩短到5分钟
自动更新	新增后台自动更新功能
系统要求	简化系统要求检查清单
FAQ	新增8个原生安装相关常见问题
迁移指南	新增从npm迁移到原生的完整指南

V2.1 修正内容（2025-12-23）

修正项	问题	修正后
API测试模型名称	`claude-sonnet-4-20250514` 格式和日期错误	修正为 `claude-sonnet-4-5-20250929`

💡 审查方法：基于官方Claude API文档验证模型名称准确性。

Claude Code 完整安装指南：从零开始到成功运行 ​

📚 本课学习目标 ​

🗺️ 学习路径导航（先看这里！） ​

路径A：快速上手（⏱️ 30分钟） ​

路径B：完整学习（⏱️ 2-3小时） ​

路径C：问题排查（⏱️ 10分钟） ​

路径D：专项学习（⏱️ 30-60分钟/主题） ​

术语表（小白必读） ​

第一部分：Claude Code 简介 ​

1.1 什么是 Claude Code ​

1.2 核心优势：为什么值得学习 ​

优势1：隐私与安全 ​

优势2：真正的编程助手 ​

优势3：多语言多框架支持 ​

1.3 与主流工具对比 ​

1.4 适合谁学习 ​

课前准备检查清单 ​

第二部分：系统要求快速检查 ​

2.1 快速检查清单（核心3项） ​

2.2 详细要求说明（可选阅读） ​

第三部分：原生安装说明（⭐ 重要更新） ​

3.1 为什么切换到原生安装？ ​

3.2 原生安装的工作原理 ​

3.3 自动更新机制 ​

3.4 如果你之前用npm安装过？ ​

第四部分：Anthropic 账号准备 ​

4.1 注册 Anthropic 账号 ​

4.2 API Key 获取步骤 ​

4.3 环境变量配置 ​

Windows配置方法 ​

macOS/Linux配置方法 ​

安全注意事项 ​

4.3.1 API中转站配置（可选） ​

4.4 计费与订阅 ​

第五部分：Claude Code 原生安装（⭐ 核心重点） ​

5.1 安装方式概览 ​

5.2 方式1：脚本安装（推荐 - 跨平台） ​

macOS / Linux / WSL 安装 ​

Windows PowerShell 安装 ​

5.3 方式2：Homebrew安装（macOS/Linux） ​

5.4 方式3：WinGet安装（Windows） ​

5.5 验证安装成功 ​

5.6 安装失败排查 ​

问题1：命令找不到 ​

问题2：权限被拒绝 ​

问题3：网络连接失败 ​

问题4：Windows SmartScreen拦截 ​

5.7 卸载 Claude Code ​

第六部分：首次启动与验证 ​

6.1 启动 Claude Code 的三种方式 ​

6.2 首次启动的初始化流程 ​

6.3 配置文件结构 ​

第6.5部分：Claude Code启动方式详解 ​

6.5.1 启动方式概览 ​

6.5.2 方式一：终端命令启动（基础必学） ​

基础启动命令 ​

带参数的启动命令 ​

--dangerously-skip-permissions 详解（重要！） ​

启动验证清单 ​

6.5.3 方式二：IDE扩展启动（进阶） ​

VS Code扩展安装（官方扩展已发布） ​

Cursor集成方式（需要手动安装） ​

6.5.4 启动方式选择建议 ​

6.6 Hello World 快速验证 ​

6.6.1 基础功能测试（5分钟） ​

6.6.2 Hello World 项目实战（15分钟） ​

6.6.3 完整验证清单 ​

第七部分：IDE 集成配置 ​

7.1 VS Code 完整集成方案 ​

步骤1：VS Code基础配置 ​

步骤2：配置集成终端 ​

步骤3：创建VS Code任务（可选但推荐） ​

步骤4：配置快捷键（可选） ​

7.2 Cursor 编辑器集成 ​

方法 A：用命令面板打开（最推荐） ​

方法 B：直接打开文件路径（万能方法） ​

7.3 JetBrains IDEs 集成 ​

步骤1：配置External Tools ​

步骤2：配置快捷键 ​

第八部分：故障排查 ​

Claude Code 完整安装指南：从零开始到成功运行

📚 本课学习目标

🗺️ 学习路径导航（先看这里！）

路径A：快速上手（⏱️ 30分钟）

路径B：完整学习（⏱️ 2-3小时）

路径C：问题排查（⏱️ 10分钟）

路径D：专项学习（⏱️ 30-60分钟/主题）

术语表（小白必读）

第一部分：Claude Code 简介

1.1 什么是 Claude Code

1.2 核心优势：为什么值得学习

优势1：隐私与安全

优势2：真正的编程助手

优势3：多语言多框架支持

1.3 与主流工具对比

1.4 适合谁学习

课前准备检查清单

第二部分：系统要求快速检查

2.1 快速检查清单（核心3项）

2.2 详细要求说明（可选阅读）

第三部分：原生安装说明（⭐ 重要更新）

3.1 为什么切换到原生安装？

3.2 原生安装的工作原理

3.3 自动更新机制

3.4 如果你之前用npm安装过？

第四部分：Anthropic 账号准备

4.1 注册 Anthropic 账号

4.2 API Key 获取步骤

4.3 环境变量配置

Windows配置方法

macOS/Linux配置方法

安全注意事项

4.3.1 API中转站配置（可选）

4.4 计费与订阅

第五部分：Claude Code 原生安装（⭐ 核心重点）

5.1 安装方式概览

5.2 方式1：脚本安装（推荐 - 跨平台）

macOS / Linux / WSL 安装

Windows PowerShell 安装

5.3 方式2：Homebrew安装（macOS/Linux）

5.4 方式3：WinGet安装（Windows）

5.5 验证安装成功

5.6 安装失败排查

问题1：命令找不到

问题2：权限被拒绝

问题3：网络连接失败

问题4：Windows SmartScreen拦截

5.7 卸载 Claude Code

第六部分：首次启动与验证

6.1 启动 Claude Code 的三种方式

6.2 首次启动的初始化流程

6.3 配置文件结构

第6.5部分：Claude Code启动方式详解

6.5.1 启动方式概览

6.5.2 方式一：终端命令启动（基础必学）

基础启动命令

带参数的启动命令

--dangerously-skip-permissions 详解（重要！）

启动验证清单

6.5.3 方式二：IDE扩展启动（进阶）

VS Code扩展安装（官方扩展已发布）

Cursor集成方式（需要手动安装）

6.5.4 启动方式选择建议

6.6 Hello World 快速验证

6.6.1 基础功能测试（5分钟）

6.6.2 Hello World 项目实战（15分钟）

6.6.3 完整验证清单

第七部分：IDE 集成配置

7.1 VS Code 完整集成方案

步骤1：VS Code基础配置

步骤2：配置集成终端

步骤3：创建VS Code任务（可选但推荐）

步骤4：配置快捷键（可选）

7.2 Cursor 编辑器集成

方法 A：用命令面板打开（最推荐）

方法 B：直接打开文件路径（万能方法）

7.3 JetBrains IDEs 集成

步骤1：配置External Tools

步骤2：配置快捷键

第八部分：故障排查