小白友好 · 中文版
✨ 2025 最强 AI 编程助手

Claude Code 小白教程

从零开始,手把手教你安装、配置和使用 Claude Code。无需任何基础,跟着做就行。

自动写代码
自动改 Bug
理解整个项目
命令行操作

🤔 Claude Code 到底是啥?

简单说,Claude Code 就是一个跑在你终端(命令行)里的 AI 编程助手。你用文字告诉它你想干什么,它就能帮你:

它和 ChatGPT 最大的不同是:它直接在你电脑上操作文件,而不只是在网页里聊天。

你(终端里打字)
Claude Code
第三方 API 代理
Claude AI 模型
1

准备工作

在安装之前,请确保你有以下东西:

📦 你需要准备的东西

项目说明怎么获得
电脑 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
2

安装 Claude Code

国内用户注意!Claude Code 的官方安装脚本需要访问 claude.ai,该网站在国内无法直接访问。但别担心,下面提供了完全不需要翻墙的安装方法。

这是国内用户最推荐的方式!使用国内 npm 镜像,完全不需要翻墙,一条命令搞定。

先安装 Node.js(如果还没有的话)

npm 是 Node.js 自带的包管理器,所以需要先安装 Node.js(版本 18 以上)。

方法 A:用 Homebrew 安装(推荐)

bash
brew install node

方法 B:去 Node.js 中文官网 下载安装包,双击安装。

Node.js 中文官网 下载 Windows 安装包(.msi),双击安装即可。安装时记得勾选 "Add to PATH"。

另外还需要安装 Git for Windows,因为 Claude Code 在 Windows 上需要 Git Bash 环境。

bash — Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs

安装好后,验证一下版本:

bash
node -v # 应该显示 v18.x.x 或更高 npm -v # 应该显示 9.x.x 或更高

用国内镜像安装 Claude Code

这是关键的一步,使用淘宝 npm 镜像源来安装,完全不需要翻墙

bash — 一条命令搞定
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

这条命令做了什么?

  • npm install -g — 全局安装一个包
  • @anthropic-ai/claude-code — Claude Code 的 npm 包名
  • --registry=https://registry.npmmirror.com — 使用国内淘宝镜像源,不走国外服务器

想永久使用国内镜像?可以把镜像源设为默认,以后装任何 npm 包都走国内:

bash
npm config set registry https://registry.npmmirror.com # 设置好之后,以后就可以直接用: npm install -g @anthropic-ai/claude-code

等待安装完成

安装过程可能需要 1-3 分钟(取决于你的网速)。看到类似下面的输出就表示安装成功了:

Terminal
$ npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com added 1 package in 45s npm warn deprecated @anthropic-ai/claude-code: Use the native installation method $

看到 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)

bash
# 1. 解压下载的文件(文件名换成你实际下载的) tar -xzf claude-code-*-darwin-arm64.tar.gz # 2. 移动到系统路径 sudo mv claude /usr/local/bin/ # 3. 确保可执行权限 chmod +x /usr/local/bin/claude

Windows 用户

下载 .exe 文件后,把它放到一个方便的位置(如 C:\Program Files\ClaudeCode\),然后将该目录添加到系统 PATH 环境变量中。

GitHub 访问慢?可以试试国内的 GitHub 镜像站来加速下载,或者让已经下载好的朋友直接把文件传给你。

以下是官方推荐的安装方式,但需要访问 claude.ai在国内需要翻墙(VPN/代理)才能执行。如果你有翻墙工具,可以使用这种方式。

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

PowerShell:

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

CMD:

cmd
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
bash
brew install --cask claude-code

小技巧:如果你只是暂时有翻墙工具,可以只在安装时打开 VPN,安装完毕后关掉就行。Claude Code 日常使用是连接你的第三方 API 代理,不需要翻墙。

验证安装成功

无论用哪种方式安装,安装完成后都运行以下命令验证:

检查版本号

bash
claude -v
Terminal
$ claude -v 2.1.50 ← 看到版本号就说明安装成功了!

运行诊断检查(可选)

bash
claude doctor

这个命令会检查你的安装环境是否一切正常。

安装遇到问题?

  • 提示 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 中
3

配置第三方 API(最重要!)

这一步是整个教程最关键的一步!因为我们在国内不能直接登录 Anthropic 账号,所以必须手动配置第三方提供的 API 地址和密钥。如果这一步没搞对,后面什么都用不了。

有两种配置方式,推荐使用方式一(配置文件),因为只需要设置一次,以后每次用都自动生效。

创建配置目录

先确保 ~/.claude/ 目录存在(通常安装后就已经有了):

bash
mkdir -p ~/.claude

创建配置文件

用任意文本编辑器创建 ~/.claude/settings.json 文件。这里我们用终端命令直接创建:

bash
cat > ~/.claude/settings.json << 'EOF' { "env": { "ANTHROPIC_API_KEY": "把这里替换成你的API密钥", "ANTHROPIC_BASE_URL": "把这里替换成你的API地址" } } EOF

替换成你自己的信息

打开刚才创建的文件,把里面的内容替换成你自己的真实信息。举个例子:

json — 示例
{ "env": { "ANTHROPIC_API_KEY": "sk-ant-api03-xxxxxxxxxxxxxxxxxx", "ANTHROPIC_BASE_URL": "https://api.your-proxy.com" } }

你也可以用 nanovim 等编辑器来编辑这个文件:

bash
nano ~/.claude/settings.json

验证配置文件

检查一下文件内容是否正确:

bash
cat ~/.claude/settings.json

确保输出的 JSON 格式正确,API Key 和 URL 都是你自己的真实信息。

每次打开终端时手动设置环境变量(关闭终端后失效,适合临时测试):

bash
# 设置你的 API 密钥 export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxx" # 设置第三方代理的 API 地址 export ANTHROPIC_BASE_URL="https://api.your-proxy.com" # 然后启动 Claude Code claude

这种方式每次打开新的终端窗口都要重新设置,比较麻烦。如果你只是想先试试能不能用,可以用这种方式。确认可以用了之后建议切换到方式一。

把环境变量写到你的 Shell 配置文件里,这样每次打开终端都会自动加载:

bash
# 把下面两行加到 ~/.zshrc 文件末尾 echo 'export ANTHROPIC_API_KEY="你的API密钥"' >> ~/.zshrc echo 'export ANTHROPIC_BASE_URL="你的API地址"' >> ~/.zshrc # 让配置立即生效 source ~/.zshrc
bash
# 把下面两行加到 ~/.bashrc 文件末尾 echo 'export ANTHROPIC_API_KEY="你的API密钥"' >> ~/.bashrc echo 'export ANTHROPIC_BASE_URL="你的API地址"' >> ~/.bashrc # 让配置立即生效 source ~/.bashrc

🔑 两个关键配置项详解

配置项含义示例值
ANTHROPIC_API_KEY 你的 API 密钥,用来验证你的身份和付费额度 sk-ant-api03-xxxxx
ANTHROPIC_BASE_URL 第三方代理的 API 服务器地址 https://api.your-proxy.com

这两个值都是你的代理商提供的,每个代理商的格式可能不同。请根据你实际拿到的信息填写。

4

第一次运行

进入你的项目目录

Claude Code 需要在一个项目目录中运行,这样它才能看到你的代码文件。

bash
# 进入你的项目文件夹(换成你自己的路径) cd ~/my-project # 如果你还没有项目,可以先创建一个测试目录 mkdir ~/test-project && cd ~/test-project

启动 Claude Code

bash
claude

看到这个画面说明成功了

Terminal — claude
╭────────────────────────────────────────╮ Claude Code v1.x.x Model: claude-sonnet-4-6 Working directory: ~/test-project ╰────────────────────────────────────────╯ Tips: Use /help for available commands >

出现 > 提示符就表示 Claude Code 已经准备好了,可以开始对话了!

试着说句话

> 后面输入你想问的问题,按回车发送:

Terminal — claude
> 你好,请用中文介绍一下你自己 Claude: 你好!我是 Claude Code,一个运行在终端里的 AI 编程助手。 我可以帮你: • 阅读和理解你的代码 • 编写新的代码文件 • 修复代码中的 Bug • 执行终端命令 • 管理 Git 版本控制 有什么我可以帮你的吗? >

如果启动后报错,请检查:

  • API Key 是否正确(有没有多余的空格或引号)
  • API Base URL 是否正确(注意 https:// 不能漏)
  • 网络是否正常(能否访问你的代理商地址)

可以运行 /status 命令查看连接状态。

5

基本对话用法

Claude Code 的核心用法非常简单:你打字说话,它来干活。下面是一些最常用的场景。

📖 场景一:让它看懂你的项目

Terminal — claude
> 帮我分析一下这个项目的整体结构和功能 Claude: 我来看一下项目结构... 📁 项目结构分析: ├── src/ — 源代码目录 │ ├── App.tsx — 主入口组件(React) │ ├── api/ — 后端 API 接口 │ └── utils/ — 工具函数 ├── package.json — 项目依赖配置 └── README.md — 项目说明文档 这是一个 React + TypeScript 的前端项目,主要功能是...

🔍 场景二:问具体的代码问题

Terminal — claude
> src/api/user.ts 这个文件里的 getUserProfile 函数是干嘛的? Claude: 我来读一下这个文件... `getUserProfile` 函数的作用是根据用户 ID 从后端获取 用户的个人资料信息。它接收一个 `userId` 参数,然后向 `/api/users/:id` 发送 GET 请求,返回包含用户名、邮箱、 头像等信息的对象。

你可以用 @ 符号直接引用文件,例如输入 解释一下 @src/api/user.ts,Claude 会自动读取这个文件。

🐛 场景三:让它修 Bug

Terminal — claude
> 登录页面点击登录按钮后没有反应,帮我找一下 Bug Claude: 让我检查一下登录相关的代码... 找到问题了!在 `src/pages/Login.tsx` 第 42 行: ```tsx // 问题:handleSubmit 函数没有 await 异步调用 const handleSubmit = (e) => { e.preventDefault(); loginAPI(username, password); // ← 缺少 await }; ``` 应该改为: ```tsx const handleSubmit = async (e) => { e.preventDefault(); await loginAPI(username, password); // ← 加上 await }; ``` 要我帮你直接修改这个文件吗?

当 Claude 要修改你的文件时,它会先问你同意不同意。你输入 y(同意)或者 n(拒绝)即可。

6

让 AI 帮你写代码(实战演示)

下面是几个完整的实战例子,展示 Claude Code 有多强大。

🌟 实战一:从零创建一个 TODO 应用

Terminal — claude
> 帮我用 HTML + CSS + JavaScript 创建一个漂亮的 TODO 待办事项应用, 要支持添加、删除、标记完成功能,界面要好看一点 Claude: 好的,我来为你创建一个完整的 TODO 应用。 📝 Created index.html 📝 Created style.css 📝 Created app.js ✅ 已经创建了 3 个文件: • index.html — 页面结构 • style.css — 样式(渐变背景 + 卡片设计) • app.js — 交互逻辑(增删改查 + 本地存储) 你可以用浏览器直接打开 index.html 查看效果。

🌟 实战二:给现有项目加新功能

Terminal — claude
> 给项目加一个暗黑模式切换功能,点击按钮可以在亮色和暗色主题之间切换 Claude: 我来看看项目现有的样式结构... ✏️ Modified src/App.tsx (添加了主题切换按钮和逻辑) ✏️ Modified src/styles/main.css (添加了暗色主题 CSS 变量) ✏️ Modified src/hooks/index.ts (新增 useTheme Hook) ✅ 暗黑模式功能已添加! • 页面右上角新增了🌙/☀️切换按钮 • 主题偏好会保存到 localStorage • 默认跟随系统主题设置

🌟 实战三:用自然语言跑命令

Terminal — claude
> 帮我安装项目依赖,然后启动开发服务器 Claude: 我来执行安装和启动命令。 🔧 Will run: npm install Allow? (y/n) y added 1247 packages in 32s 🔧 Will run: npm run dev Allow? (y/n) y VITE v5.x.x ready in 420 ms ➜ Local: http://localhost:5173/

注意:执行命令之前 Claude 会征求你的同意,你可以看到它要执行什么命令再决定是否允许。

7

常用命令大全

在 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 ! git status ! npm test ! ls -la
8

项目记忆:CLAUDE.md

CLAUDE.md 是一个特殊的文件,相当于给 Claude 的"项目说明书"。把它放在项目根目录,Claude 每次启动时都会自动读取。

📝 怎么创建 CLAUDE.md?

最简单的方式 — 让 Claude 帮你创建:

在 Claude Code 中输入
/init

Claude 会自动扫描你的项目,然后生成一个合适的 CLAUDE.md。

📄 CLAUDE.md 写什么内容?

下面是一个示例模板:

markdown — CLAUDE.md 示例
# 我的电商项目 ## 项目概述 这是一个基于 React + Node.js 的电商网站 ## 技术栈 - 前端:React 18 + TypeScript + Tailwind CSS - 后端:Node.js + Express + PostgreSQL - 测试:Jest + React Testing Library ## 常用命令 - npm run dev — 启动前端开发服务器 - npm run server — 启动后端服务器 - npm test — 运行测试 - npm run build — 构建生产版本 ## 目录结构 - src/components/ — React 组件 - src/pages/ — 页面组件 - src/api/ — API 调用函数 - server/routes/ — 后端路由 - server/models/ — 数据库模型 ## 编码规范 - 使用 TypeScript 严格模式 - 组件使用函数式写法 - CSS 使用 Tailwind 类名 - 变量命名用 camelCase

记忆层级(从高到低):

  • 项目级 ./CLAUDE.md — 整个团队共享的项目说明
  • 个人级 ~/.claude/CLAUDE.md — 你个人的偏好(适用于所有项目)
  • 本地级 ./CLAUDE.local.md — 你个人在此项目中的偏好(不提交到 Git)
9

切换 AI 模型

Claude 有多个模型可以选择,不同模型各有特点:

模型特点适用场景命令
Opus 最强大,最聪明 复杂问题、架构设计、困难 Bug /model opus
Sonnet 均衡型,速度与能力兼顾 日常编程、代码修改(默认) /model sonnet
Haiku 最快速,最便宜 简单问题、快速查询 /model haiku

快捷切换:在对话中按 Option+P(Mac)或 Alt+P(Windows/Linux)可以快速切换模型。

你也可以在启动时指定模型:

bash
# 启动时用 Opus 模型 claude --model opus # 启动时用 Haiku 模型(省钱快速) claude --model haiku

使用第三方代理时,请确认你的代理商支持哪些模型。不是所有代理都支持全部模型。如果切换后报错,可能是代理商不支持该模型。

10

权限管理

Claude Code 有一套完善的权限系统,可以控制它能做什么、不能做什么。

🔒 权限是怎么工作的?

当 Claude 想要执行某个操作(比如修改文件、运行命令)时,它会先询问你:

Terminal — claude
🔧 Claude wants to run: npm install axios Allow? (y) Yes, allow this once (a) Always allow "npm install *" (n) No, deny this >
  • 输入 y — 这次允许
  • 输入 a — 以后同类操作都允许(不再询问)
  • 输入 n — 拒绝

⚡ 权限模式快速切换

Shift+Tab 可以在不同权限模式间切换:

模式说明
默认模式每次操作都会询问你
Accept Edits自动允许文件编辑,命令还是会问
Plan 模式Claude 只分析不动手,适合先看看方案

~/.claude/settings.json 中可以预设权限规则:

json
{ "permissions": { "allow": [ "Read", "Edit", "Bash(npm run *)", "Bash(git status)", "Bash(git diff *)" ], "deny": [ "Bash(rm -rf *)" ] } }
11

非交互模式(脚本化使用)

Claude Code 还可以不进入对话模式,直接用命令行参数完成任务,适合集成到脚本或自动化流程中。

bash — 一次性提问
# -p 参数:打印模式,问完就退出 claude -p "这个项目用了什么技术栈?" # 管道输入:把文件内容传给 Claude cat error.log | claude -p "帮我分析这些错误日志" # 指定输出格式为 JSON claude -p "列出所有 API 接口" --output-format json # 继续上次的对话 claude -c "上面的问题还有补充吗?" # 限制最大回合数和预算 claude -p "重构这个函数" --max-turns 3 --max-budget-usd 1.00
12

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,所以确保之前的配置已经完成。

13

快捷键速查表

快捷键功能
Ctrl+C取消当前输入或停止操作
Ctrl+D退出 Claude Code
Ctrl+L清屏(保留历史记录)
Ctrl+J输入换行(多行输入)
Shift+Tab切换权限模式
Option+P / Alt+P切换模型
Option+Enter输入多行(Mac)
Esc Esc回退操作 / 总结对话
Ctrl+R搜索历史命令
14

常见问题

Q:启动后提示 "Authentication failed" 或 "Invalid API Key" 怎么办?

这说明你的 API Key 配置有问题。请检查:

  • API Key 是否完整复制(前后没有多余的空格或换行)
  • 配置文件中 JSON 格式是否正确(注意引号和逗号)
  • API Key 是否还有效(没有过期或被禁用)

运行以下命令检查你的配置:

bash
cat ~/.claude/settings.json
Q:提示 "Connection refused" 或 "Network error" 怎么办?

这说明无法连接到你的 API 代理地址。请检查:

  • ANTHROPIC_BASE_URL 是否正确(注意 http/https、端口号)
  • 代理服务器是否正常运行
  • 网络是否通畅(试试 curl 你的API地址
  • 是否需要设置网络代理(HTTPS_PROXY)
Q:怎么减少 Token 消耗(省钱)?
  • 使用 /compact 命令定期压缩对话历史
  • /clear 清除不需要的对话内容
  • 切换到 Haiku 模型(最便宜)处理简单问题
  • /cost 查看当前消耗了多少 Token
  • 尽量一次把需求说清楚,减少来回对话次数
Q:Claude 修改了我的文件,怎么撤回?
  • 按两次 Esc 键可以回退最近的修改
  • 如果你的项目用了 Git,可以用 git checkout -- 文件名 恢复
  • 可以告诉 Claude "撤回你刚才的修改"
Q:Claude 的回复太长被截断了怎么办?

可以输入"继续"或"请接着说"让 Claude 继续未完成的回复。也可以用 /compact 压缩之前的对话来释放上下文空间。

Q:如何让 Claude Code 使用中文回复?

Claude 会自动根据你的输入语言来回复。如果你用中文提问,它通常会用中文回答。你也可以在 CLAUDE.md 中加一行规则:

CLAUDE.md
## 语言偏好 - 所有回复请使用中文
Q:如何更新 Claude Code?

Claude Code 会自动在后台更新。你也可以手动更新:

bash
claude update
15

术语表(看不懂的词看这里)

术语白话解释
终端 / Terminal就是那个黑色的命令行窗口,用来打字执行命令的地方
APIApplication Programming Interface,程序之间沟通的"接口"。这里指的是调用 Claude 模型的通道
API Key一串密码字符串,证明"你有权使用这个 API"
Base URLAPI 的服务器地址,就像网站的网址一样
TokenAI 处理文本的单位。大约 1 个中文字 ≈ 2-3 个 Token。Token 越多,费用越高
模型 / ModelAI 的"大脑"。不同模型有不同的能力和速度
Opus / Sonnet / HaikuClaude 的三种模型,从最强到最快排列
代理 / Proxy中间人服务,帮你转发请求到 Anthropic 的服务器(因为直接访问不了)
环境变量操作系统里的一种全局设置,程序可以读取它
CLAUDE.md项目的"说明书"文件,让 Claude 了解你的项目
MCPModel Context Protocol,让 Claude 可以连接外部工具(如 GitHub、数据库等)
Git代码版本管理工具,记录代码的每一次修改
npmNode.js 的包管理器,用来安装 JavaScript 项目的依赖