Claude Code 小白教程
从零开始,手把手教你安装、配置和使用 Claude Code。无需任何基础,跟着做就行。
🤔 Claude Code 到底是啥?
简单说,Claude Code 就是一个跑在你终端(命令行)里的 AI 编程助手。你用文字告诉它你想干什么,它就能帮你:
- 写代码 — 直接帮你创建文件、写函数
- 改代码 — 帮你修 Bug、重构、优化
- 读代码 — 看懂你的项目结构,回答你关于代码的问题
- 跑命令 — 帮你执行 git、npm 等终端命令
- 做项目 — 从零创建一整个项目
它和 ChatGPT 最大的不同是:它直接在你电脑上操作文件,而不只是在网页里聊天。
准备工作
在安装之前,请确保你有以下东西:
📦 你需要准备的东西
| 项目 | 说明 | 怎么获得 |
|---|---|---|
| 电脑 | macOS / Linux / Windows 都行 | 你正在用的就行 |
| 终端 | 就是命令行工具 | Mac 自带 Terminal;Windows 用 Git Bash |
| Node.js 18+ | npm 安装方式需要(推荐方式) | 见下方安装教程 |
| 第三方 API Key | 用来调用 Claude 模型的密钥 | 向你的第三方 API 代理商获取 |
| 第三方 API 地址 | 代理商提供的 URL 地址 | 向你的第三方 API 代理商获取 |
因为国内无法直接访问 Anthropic 官方服务,所以我们需要通过第三方 API 代理来使用 Claude 模型。你需要从代理商那里获得两样东西:
- API Key(一串密钥字符串,类似
sk-ant-xxxx...) - API Base URL(一个网址,类似
https://your-proxy.com)
没有这两样东西,Claude Code 是无法工作的。请先联系你的代理商获取。
怎么打开终端?
- Mac:按
Command + 空格,输入 "Terminal",回车 - Windows:安装 Git for Windows,然后打开 "Git Bash"
- Linux:按
Ctrl + Alt + T
安装 Claude Code
国内用户注意!Claude Code 的官方安装脚本需要访问 claude.ai,该网站在国内无法直接访问。但别担心,下面提供了完全不需要翻墙的安装方法。
这是国内用户最推荐的方式!使用国内 npm 镜像,完全不需要翻墙,一条命令搞定。
先安装 Node.js(如果还没有的话)
npm 是 Node.js 自带的包管理器,所以需要先安装 Node.js(版本 18 以上)。
去 Node.js 中文官网 下载 Windows 安装包(.msi),双击安装即可。安装时记得勾选 "Add to PATH"。
另外还需要安装 Git for Windows,因为 Claude Code 在 Windows 上需要 Git Bash 环境。
安装好后,验证一下版本:
用国内镜像安装 Claude Code
这是关键的一步,使用淘宝 npm 镜像源来安装,完全不需要翻墙:
这条命令做了什么?
npm install -g— 全局安装一个包@anthropic-ai/claude-code— Claude Code 的 npm 包名--registry=https://registry.npmmirror.com— 使用国内淘宝镜像源,不走国外服务器
想永久使用国内镜像?可以把镜像源设为默认,以后装任何 npm 包都走国内:
等待安装完成
安装过程可能需要 1-3 分钟(取决于你的网速)。看到类似下面的输出就表示安装成功了:
看到 warn deprecated 的警告不用管!这只是官方建议用另一种安装方式,并不影响使用,npm 安装的版本功能完全一样。
GitHub 在国内大部分时候可以访问(速度可能较慢)。你可以直接去 GitHub 下载编译好的二进制文件。
前往 GitHub Releases 页面
在浏览器中打开:https://github.com/anthropics/claude-code/releases
找到最新版本,下载对应你系统的文件:
| 你的系统 | 下载哪个文件 |
|---|---|
| Mac (Apple 芯片 M1/M2/M3/M4) | claude-code-x.x.x-darwin-arm64.tar.gz |
| Mac (Intel 芯片) | claude-code-x.x.x-darwin-x64.tar.gz |
| Linux (x64) | claude-code-x.x.x-linux-x64.tar.gz |
| Windows (x64) | claude-code-x.x.x-win-x64.exe |
安装二进制文件(Mac/Linux)
Windows 用户
下载 .exe 文件后,把它放到一个方便的位置(如 C:\Program Files\ClaudeCode\),然后将该目录添加到系统 PATH 环境变量中。
GitHub 访问慢?可以试试国内的 GitHub 镜像站来加速下载,或者让已经下载好的朋友直接把文件传给你。
以下是官方推荐的安装方式,但需要访问 claude.ai,在国内需要翻墙(VPN/代理)才能执行。如果你有翻墙工具,可以使用这种方式。
PowerShell:
CMD:
小技巧:如果你只是暂时有翻墙工具,可以只在安装时打开 VPN,安装完毕后关掉就行。Claude Code 日常使用是连接你的第三方 API 代理,不需要翻墙。
验证安装成功
无论用哪种方式安装,安装完成后都运行以下命令验证:
检查版本号
运行诊断检查(可选)
这个命令会检查你的安装环境是否一切正常。
安装遇到问题?
- 提示
npm: command not found— 说明你还没装 Node.js,先装 Node.js 再来 - 提示
permission denied— 在命令前面加sudo重试:sudo npm install -g @anthropic-ai/claude-code - 下载速度很慢 — 确认你加了
--registry=https://registry.npmmirror.com走国内镜像 claude -v提示找不到命令 — 关闭终端重新打开试试,或者检查 npm 的全局 bin 路径是否在 PATH 中
配置第三方 API(最重要!)
这一步是整个教程最关键的一步!因为我们在国内不能直接登录 Anthropic 账号,所以必须手动配置第三方提供的 API 地址和密钥。如果这一步没搞对,后面什么都用不了。
有两种配置方式,推荐使用方式一(配置文件),因为只需要设置一次,以后每次用都自动生效。
创建配置目录
先确保 ~/.claude/ 目录存在(通常安装后就已经有了):
创建配置文件
用任意文本编辑器创建 ~/.claude/settings.json 文件。这里我们用终端命令直接创建:
替换成你自己的信息
打开刚才创建的文件,把里面的内容替换成你自己的真实信息。举个例子:
你也可以用 nano 或 vim 等编辑器来编辑这个文件:
验证配置文件
检查一下文件内容是否正确:
确保输出的 JSON 格式正确,API Key 和 URL 都是你自己的真实信息。
每次打开终端时手动设置环境变量(关闭终端后失效,适合临时测试):
这种方式每次打开新的终端窗口都要重新设置,比较麻烦。如果你只是想先试试能不能用,可以用这种方式。确认可以用了之后建议切换到方式一。
把环境变量写到你的 Shell 配置文件里,这样每次打开终端都会自动加载:
🔑 两个关键配置项详解
| 配置项 | 含义 | 示例值 |
|---|---|---|
ANTHROPIC_API_KEY |
你的 API 密钥,用来验证你的身份和付费额度 | sk-ant-api03-xxxxx |
ANTHROPIC_BASE_URL |
第三方代理的 API 服务器地址 | https://api.your-proxy.com |
这两个值都是你的代理商提供的,每个代理商的格式可能不同。请根据你实际拿到的信息填写。
第一次运行
进入你的项目目录
Claude Code 需要在一个项目目录中运行,这样它才能看到你的代码文件。
启动 Claude Code
看到这个画面说明成功了
出现 > 提示符就表示 Claude Code 已经准备好了,可以开始对话了!
试着说句话
在 > 后面输入你想问的问题,按回车发送:
如果启动后报错,请检查:
- API Key 是否正确(有没有多余的空格或引号)
- API Base URL 是否正确(注意
https://不能漏) - 网络是否正常(能否访问你的代理商地址)
可以运行 /status 命令查看连接状态。
基本对话用法
Claude Code 的核心用法非常简单:你打字说话,它来干活。下面是一些最常用的场景。
📖 场景一:让它看懂你的项目
🔍 场景二:问具体的代码问题
你可以用 @ 符号直接引用文件,例如输入 解释一下 @src/api/user.ts,Claude 会自动读取这个文件。
🐛 场景三:让它修 Bug
当 Claude 要修改你的文件时,它会先问你同意不同意。你输入 y(同意)或者 n(拒绝)即可。
让 AI 帮你写代码(实战演示)
下面是几个完整的实战例子,展示 Claude Code 有多强大。
🌟 实战一:从零创建一个 TODO 应用
🌟 实战二:给现有项目加新功能
🌟 实战三:用自然语言跑命令
注意:执行命令之前 Claude 会征求你的同意,你可以看到它要执行什么命令再决定是否允许。
常用命令大全
在 Claude Code 的对话框中,以 / 开头的是内置命令,用来控制 Claude Code 本身的行为。
| 命令 | 功能 | 使用场景 |
|---|---|---|
/help |
显示帮助信息 | 不知道怎么用的时候看看 |
/status |
查看连接状态、版本、模型信息 | 检查 API 是否连接正常 |
/model |
切换 AI 模型 | 想换用更快或更强的模型 |
/clear |
清空当前对话历史 | 想开始新的话题 |
/compact |
压缩对话历史 | 对话太长、token 用太多时 |
/cost |
查看本次消耗了多少 token | 想看看花了多少钱 |
/init |
初始化项目配置(CLAUDE.md) | 让 Claude 更了解你的项目 |
/memory |
编辑记忆文件 | 让 Claude 记住你的偏好 |
/config |
打开设置界面 | 修改主题、权限、模型等设置 |
/permissions |
查看和管理权限规则 | 控制 Claude 能做什么 |
/doctor |
运行诊断检查 | 出问题时排查原因 |
/vim |
开启 Vim 编辑模式 | 习惯 Vim 操作的用户 |
/theme |
切换颜色主题 | 想换个好看的界面颜色 |
/exit |
退出 Claude Code | 用完了想退出(也可以按 Ctrl+D) |
快速执行终端命令:在对话框中用 ! 开头可以直接运行终端命令,不需要 Claude 解读。例如:
项目记忆:CLAUDE.md
CLAUDE.md 是一个特殊的文件,相当于给 Claude 的"项目说明书"。把它放在项目根目录,Claude 每次启动时都会自动读取。
📝 怎么创建 CLAUDE.md?
最简单的方式 — 让 Claude 帮你创建:
Claude 会自动扫描你的项目,然后生成一个合适的 CLAUDE.md。
📄 CLAUDE.md 写什么内容?
下面是一个示例模板:
记忆层级(从高到低):
- 项目级
./CLAUDE.md— 整个团队共享的项目说明 - 个人级
~/.claude/CLAUDE.md— 你个人的偏好(适用于所有项目) - 本地级
./CLAUDE.local.md— 你个人在此项目中的偏好(不提交到 Git)
切换 AI 模型
Claude 有多个模型可以选择,不同模型各有特点:
| 模型 | 特点 | 适用场景 | 命令 |
|---|---|---|---|
| Opus | 最强大,最聪明 | 复杂问题、架构设计、困难 Bug | /model opus |
| Sonnet | 均衡型,速度与能力兼顾 | 日常编程、代码修改(默认) | /model sonnet |
| Haiku | 最快速,最便宜 | 简单问题、快速查询 | /model haiku |
快捷切换:在对话中按 Option+P(Mac)或 Alt+P(Windows/Linux)可以快速切换模型。
你也可以在启动时指定模型:
使用第三方代理时,请确认你的代理商支持哪些模型。不是所有代理都支持全部模型。如果切换后报错,可能是代理商不支持该模型。
权限管理
Claude Code 有一套完善的权限系统,可以控制它能做什么、不能做什么。
🔒 权限是怎么工作的?
当 Claude 想要执行某个操作(比如修改文件、运行命令)时,它会先询问你:
- 输入 y — 这次允许
- 输入 a — 以后同类操作都允许(不再询问)
- 输入 n — 拒绝
⚡ 权限模式快速切换
按 Shift+Tab 可以在不同权限模式间切换:
| 模式 | 说明 |
|---|---|
| 默认模式 | 每次操作都会询问你 |
| Accept Edits | 自动允许文件编辑,命令还是会问 |
| Plan 模式 | Claude 只分析不动手,适合先看看方案 |
在 ~/.claude/settings.json 中可以预设权限规则:
非交互模式(脚本化使用)
Claude Code 还可以不进入对话模式,直接用命令行参数完成任务,适合集成到脚本或自动化流程中。
IDE 集成(VS Code)
如果你使用 VS Code,可以安装 Claude Code 插件,在编辑器内直接使用。
安装 VS Code 插件
打开 VS Code,按 Cmd+Shift+X(Mac)或 Ctrl+Shift+X(Windows),搜索 "Claude Code",点击安装。
打开 Claude 面板
安装后在 VS Code 侧边栏会出现 Claude 的图标,点击即可打开对话面板。
享受图形化体验
在 VS Code 中使用 Claude Code 有几个额外好处:
- 文件修改可以用 并排对比视图 查看
- 可以用
@引用文件时有 自动补全 - 支持 多标签对话
VS Code 插件底层还是使用你配置好的 API Key 和 Base URL,所以确保之前的配置已经完成。
快捷键速查表
| 快捷键 | 功能 |
|---|---|
Ctrl+C | 取消当前输入或停止操作 |
Ctrl+D | 退出 Claude Code |
Ctrl+L | 清屏(保留历史记录) |
Ctrl+J | 输入换行(多行输入) |
Shift+Tab | 切换权限模式 |
Option+P / Alt+P | 切换模型 |
Option+Enter | 输入多行(Mac) |
Esc Esc | 回退操作 / 总结对话 |
Ctrl+R | 搜索历史命令 |
常见问题
这说明你的 API Key 配置有问题。请检查:
- API Key 是否完整复制(前后没有多余的空格或换行)
- 配置文件中 JSON 格式是否正确(注意引号和逗号)
- API Key 是否还有效(没有过期或被禁用)
运行以下命令检查你的配置:
这说明无法连接到你的 API 代理地址。请检查:
- ANTHROPIC_BASE_URL 是否正确(注意 http/https、端口号)
- 代理服务器是否正常运行
- 网络是否通畅(试试
curl 你的API地址) - 是否需要设置网络代理(HTTPS_PROXY)
- 使用
/compact命令定期压缩对话历史 - 用
/clear清除不需要的对话内容 - 切换到 Haiku 模型(最便宜)处理简单问题
- 用
/cost查看当前消耗了多少 Token - 尽量一次把需求说清楚,减少来回对话次数
- 按两次
Esc键可以回退最近的修改 - 如果你的项目用了 Git,可以用
git checkout -- 文件名恢复 - 可以告诉 Claude "撤回你刚才的修改"
可以输入"继续"或"请接着说"让 Claude 继续未完成的回复。也可以用 /compact 压缩之前的对话来释放上下文空间。
Claude 会自动根据你的输入语言来回复。如果你用中文提问,它通常会用中文回答。你也可以在 CLAUDE.md 中加一行规则:
Claude Code 会自动在后台更新。你也可以手动更新:
术语表(看不懂的词看这里)
| 术语 | 白话解释 |
|---|---|
| 终端 / Terminal | 就是那个黑色的命令行窗口,用来打字执行命令的地方 |
| API | Application Programming Interface,程序之间沟通的"接口"。这里指的是调用 Claude 模型的通道 |
| API Key | 一串密码字符串,证明"你有权使用这个 API" |
| Base URL | API 的服务器地址,就像网站的网址一样 |
| Token | AI 处理文本的单位。大约 1 个中文字 ≈ 2-3 个 Token。Token 越多,费用越高 |
| 模型 / Model | AI 的"大脑"。不同模型有不同的能力和速度 |
| Opus / Sonnet / Haiku | Claude 的三种模型,从最强到最快排列 |
| 代理 / Proxy | 中间人服务,帮你转发请求到 Anthropic 的服务器(因为直接访问不了) |
| 环境变量 | 操作系统里的一种全局设置,程序可以读取它 |
| CLAUDE.md | 项目的"说明书"文件,让 Claude 了解你的项目 |
| MCP | Model Context Protocol,让 Claude 可以连接外部工具(如 GitHub、数据库等) |
| Git | 代码版本管理工具,记录代码的每一次修改 |
| npm | Node.js 的包管理器,用来安装 JavaScript 项目的依赖 |