<!-- title: Claude Code零基础入门安装与实战 -->

# Claude Code 零基础入门：从安装到第一个项目

## 概述

本教程面向**从未接触过 Claude Code 的开发者**，从零开始讲解如何安装、配置并完成第一个真实项目。你将学到：环境准备与安装、认证与账户配置、核心交互模式、CLAUDE.md 项目指令文件编写、以及用 Claude Code 从零搭建一个可运行的 REST API 项目。适用人群：有任何编程基础但从未使用过 AI 编程助手的开发者。

---

## 一、Claude Code 是什么

Claude Code 是 Anthropic 推出的**智能体式（Agentic）编程工具**。它不是一个代码补全插件，而是一个能在终端中**读取你的代码库、编辑文件、执行命令、与 Git 集成**的全能编码助手。

与传统 AI 编程工具的核心区别：

| 维度 | 传统代码补全（Copilot 等） | Claude Code |
|------|--------------------------|-------------|
| 工作方式 | 逐行补全建议 | 对话式，理解整个项目上下文 |
| 操作范围 | 当前编辑器文件 | 整个代码库，跨文件编辑 |
| 执行能力 | 仅生成代码片段 | 可运行命令、读写文件、管理 Git |
| 交互模式 | 被动触发 | 主动对话、规划、执行 |
| 运行环境 | IDE 插件 | 终端 CLI / 桌面应用 / IDE 集成 / 浏览器 |

Claude Code 可在**四种环境**中使用：

1. **终端 CLI** — 核心形态，最灵活
2. **桌面应用** — macOS / Windows 独立应用
3. **IDE 集成** — VS Code、JetBrains 插件
4. **浏览器** — claude.ai/code 网页版

本教程聚焦**终端 CLI**，这是功能最完整、可定制性最强的形态。

---

## 二、环境准备

### 2.1 系统要求

Claude Code 支持 macOS、Linux 和 Windows（通过 WSL）。核心前提条件：

- **Node.js 18 或更高版本**（推荐 LTS 版本 v20+）
- **网络连接**（需要访问 Anthropic API）
- **终端/命令行工具**

### 2.2 安装 Node.js

**macOS / Linux：**

```bash
# 使用 nvm 安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc   # 或 source ~/.zshrc
nvm install --lts
nvm use --lts

# 验证
node --version    # 应输出 v20.x.x 或更高
npm --version     # 应输出 10.x.x 或更高
```

**Windows（WSL）：**

```bash
# 在 WSL Ubuntu 中
sudo apt update
sudo apt install nodejs npm
# 或同样使用 nvm
```

**验证 Node.js 就绪：**

```bash
node --version && npm --version
```

预期输出类似：

```
v20.19.0
10.9.2
```

### 2.3 获取访问权限

Claude Code 需要 Anthropic 账户，有两种方式：

**方式一：Claude 订阅（推荐新手）**

拥有 Claude Pro / Max / Team / Enterprise 订阅即可直接使用，无需单独付费 API。

**方式二：API Key**

在 [console.anthropic.com](https://console.anthropic.com) 注册并获取 API Key，按使用量计费。

---

## 三、安装 Claude Code

### 3.1 一键安装

```bash
npm install -g @anthropic-ai/claude-code
```

安装完成后验证：

```bash
claude --version
```

预期输出类似：

```
Claude Code v2.1.x
```

### 3.2 首次认证

```bash
claude
```

首次运行会触发认证流程。根据你的账户类型：

**订阅用户：**
1. 终端显示一个 URL 和验证码
2. 在浏览器中打开 URL，输入验证码
3. 完成授权，终端自动登录

**API Key 用户：**
1. 选择 "Enter API Key"
2. 粘贴你的 API Key
3. 回车确认

认证成功后，你将看到 Claude Code 的交互式提示符：

```
claude>
```

到这里，你已经可以开始和 Claude Code 对话了。

### 3.3 安装故障排除

**问题 1：`command not found: claude`**

```bash
# 检查 npm 全局路径是否在 PATH 中
npm config get prefix
# 确保该路径/bin 在你的 PATH 中
export PATH="$(npm config get prefix)/bin:$PATH"
# 永久生效，添加到 ~/.bashrc 或 ~/.zshrc
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
```

**问题 2：权限错误 `EACCES`**

```bash
# 方案一：使用 nvm 管理的 Node（推荐）
nvm use --lts
npm install -g @anthropic-ai/claude-code

# 方案二：修改 npm 全局目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @anthropic-ai/claude-code
```

**问题 3：Node.js 版本过低**

```bash
node --version  # 需要 >= 18
# 如果版本过低，用 nvm 升级
nvm install 20
nvm use 20
```

---

## 四、核心交互模式

Claude Code 有三种核心使用模式，理解它们是从新手到高效用户的关键。

### 4.1 交互式会话（默认模式）

```bash
cd your-project
claude
```

进入交互式 REPL（Read-Eval-Print Loop），可以持续对话：

```
claude> 帮我看看这个项目的结构
claude> 解释一下 src/index.ts 的主要逻辑
claude> 给用户模块加一个邮箱验证功能
```

这是最常用的模式，适合**探索、开发、调试**等所有场景。

### 4.2 单次提问模式（-p 标志）

```bash
claude -p "这个项目用了什么技术栈？"
```

执行一次提问后立即返回结果并退出。适合：
- 快速查询
- 脚本集成
- CI/CD 流水线

### 4.3 管道模式

```bash
# 将文件内容传给 Claude Code 分析
cat error.log | claude -p "分析这些错误日志的根本原因"

# 将 Claude Code 的输出导入文件
claude -p "生成一个 .gitignore 文件用于 Node.js 项目" > .gitignore
```

### 4.4 整体工作流概览

```text
flowchart TD
    A[启动 Claude Code] --> B{选择模式}
    B --> C[交互式会话<br/>claude]
    B --> D[单次提问<br/>claude -p "问题"]
    B --> E[管道模式<br/>cat file | claude -p]

    C --> F[探索代码库]
    C --> G[编写/修改代码]
    C --> H[调试与修复]
    C --> I[Git 操作]

    D --> J[快速查询]
    D --> K[脚本集成]

    E --> L[日志分析]
    E --> M[批量处理]

    F --> N[输出结果]
    G --> N
    H --> N
    I --> N
    J --> N
    K --> N
    L --> N
    M --> N
```

---

## 五、常用命令速查

### 5.1 斜杠命令（Slash Commands）

在交互式会话中，使用 `/` 开头的命令可以快速执行操作：

| 命令 | 功能 | 使用场景 |
|------|------|----------|
| `/help` | 显示帮助信息 | 忘记命令时查看 |
| `/init` | 初始化项目 CLAUDE.md | 新项目首次使用 |
| `/clear` | 清除对话历史 | 上下文过长时重置 |
| `/compact` | 压缩上下文窗口 | 对话过长时节省 Token |
| `/cost` | 显示当前会话费用 | 监控使用成本 |
| `/model` | 切换模型 | 选择 Opus/Sonnet/Haiku |
| `/review` | 代码审查 | 检查当前变更 |
| `/bug` | 报告 Bug | 反馈问题给 Anthropic |
| `/memory` | 查看/编辑记忆文件 | 管理持久化偏好 |

### 5.2 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息（默认单行） |
| `Shift + Enter` | 换行（多行输入） |
| `Escape` | 取消当前操作 |
| `Ctrl + C` | 中断 Claude 的回复 |
| `Ctrl + D` | 退出 Claude Code |
| `Tab` | 接受代码补全建议 |
| `↑ / ↓` | 浏览历史消息 |

### 5.3 权限模式

Claude Code 在执行操作前会根据权限设置决定是否需要确认：

```mermaid
flowchart LR
    A[操作请求] --> B{权限检查}
    B -->|白名单已允许| C[直接执行]
    B -->|需要确认| D[提示用户]
    D -->|用户同意| C
    D -->|用户拒绝| E[跳过操作]
    B -->|自动拒绝| E

    C --> F[继续对话]
    E --> F
```

三种权限级别：
- **Allow（允许）** — 自动执行，不再询问
- **Deny（拒绝）** — 永远不允许该操作
- **Default（默认）** — 每次询问用户

建议新手使用默认模式，逐步将常用安全操作加入白名单。

---

## 六、配置 CLAUDE.md — 项目级指令

CLAUDE.md 是 Claude Code 的**项目配置文件**，类似于 `.editorconfig` 或 `.eslintrc`，用于告诉 Claude Code 如何在你的项目中工作。

### 6.1 三层配置体系

```mermaid
flowchart TB
    A["~/.claude/CLAUDE.md<br/>全局配置<br/>所有项目生效"] --> B["项目根目录/CLAUDE.md<br/>项目配置<br/>当前项目生效"]
    B --> C["子目录/CLAUDE.md<br/>目录配置<br/>特定模块生效"]

    D[优先级：子目录 > 项目 > 全局] --> C
```

### 6.2 快速初始化

```bash
cd your-project
claude
claude> /init
```

`/init` 命令会扫描项目结构，自动生成一个基础 CLAUDE.md。

### 6.3 编写你的第一个 CLAUDE.md

```markdown
# 项目：Weather API

## 技术栈
- Node.js 20 + TypeScript
- Express.js 框架
- SQLite 数据库

## 代码规范
- 使用 ESLint + Prettier
- 缩进：2 空格
- 命名：camelCase 变量，PascalCase 类
- 注释使用中文

## 项目结构
- src/routes/ — 路由定义
- src/models/ — 数据模型
- src/services/ — 业务逻辑
- src/utils/ — 工具函数

## 工作规则
- 修改代码后运行 npm test 验证
- 不要修改 .env 文件
- API 响应统一使用 JSON 格式
- 错误处理使用统一格式 { error: string, code: number }
```

### 6.4 CLAUDE.md 最佳实践

**要写的：**
- 技术栈和版本约束
- 代码规范（命名、格式、注释语言）
- 项目目录结构说明
- 测试命令和验证步骤
- 安全红线（不要修改的文件）

**不要写的：**
- 过于冗长的背景知识
- 频繁变化的信息（如具体端口号，用 .env 代替）
- 不相关的个人偏好

---

## 七、实战：从零搭建天气查询 API

下面通过一个完整项目，体验 Claude Code 的核心能力。

### 7.1 创建项目骨架

```bash
mkdir weather-api && cd weather-api
git init
claude
```

在交互式会话中输入：

```
claude> 我想创建一个 Node.js + Express 的天气查询 REST API。
项目需求：
1. 查询指定城市的实时天气（调用 OpenWeatherMap API）
2. 查询城市未来 5 天的天气预报
3. 所有响应统一 JSON 格式
4. 包含错误处理和参数验证
5. 使用 TypeScript
```

Claude Code 会：
1. 分析需求，制定实现计划
2. 创建项目文件结构
3. 初始化 package.json 和 tsconfig.json
4. 逐文件编写代码
5. 在每一步请求你的确认

**预期生成的文件结构：**

```
weather-api/
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── CLAUDE.md
├── src/
│   ├── index.ts
│   ├── routes/
│   │   └── weather.ts
│   ├── services/
│   │   └── weatherService.ts
│   ├── middleware/
│   │   └── errorHandler.ts
│   └── types/
│       └── index.ts
└── tests/
    └── weather.test.ts
```

### 7.2 审查与调整

Claude Code 在创建或修改文件前会**展示 diff**，你可以：

- 输入 `y` 接受修改
- 输入 `n` 拒绝修改
- 输入反馈意见让 Claude 调整

例如，如果 Claude 生成的端口硬编码了 3000，你可以说：

```
claude> 端口号改为从环境变量 PORT 读取，默认值 8080
```

Claude 会只修改相关部分，而不是重写整个文件。

### 7.3 安装依赖并运行

```
claude> 安装依赖并启动开发服务器
```

Claude 会执行：

```bash
npm install
npm run dev
```

并在终端中展示运行结果。如果启动失败，直接告诉 Claude：

```
claude> 启动报错了，帮我看看错误信息并修复
```

Claude 会读取错误日志，定位问题，并提出修复方案。

### 7.4 添加功能

继续在会话中提出新需求：

```
claude> 添加一个缓存层，相同城市的天气数据缓存 10 分钟，减少 API 调用次数
```

Claude 会：
1. 创建缓存模块
2. 在 Service 层集成缓存逻辑
3. 保持现有接口不变

### 7.5 编写测试

```
claude> 为 weatherService 编写单元测试，使用 Jest 框架，mock 外部 API 调用
```

Claude 会生成测试文件并运行：

```bash
npm test
```

### 7.6 Git 提交

```
claude> 提交所有变更，commit message 要清晰描述这次改动
```

Claude 会生成规范的 commit message 并执行 git 操作（需你确认）。

### 7.7 完整工作流回顾

```mermaid
flowchart TD
    A[创建项目目录] --> B[启动 Claude Code]
    B --> C[描述需求]
    C --> D[Claude 生成代码]
    D --> E[审查 Diff]
    E -->|接受| F[代码写入磁盘]
    E -->|拒绝/调整| G[提供反馈]
    G --> D
    F --> H[安装依赖]
    H --> I[启动验证]
    I -->|成功| J[添加功能]
    I -->|失败| K[调试修复]
    K --> I
    J --> L[编写测试]
    L --> M[运行测试]
    M --> N[Git 提交]
    N --> O[项目完成 ✅]
```

---

## 八、高效使用技巧

### 8.1 善用上下文

Claude Code 会**自动读取项目文件**来理解上下文。但你可以主动提供更多线索：

```
claude> 先读一下 src/routes/weather.ts 和 src/services/weatherService.ts，然后帮我添加一个新端点，获取指定城市的历史天气数据
```

明确指定文件可以让 Claude 更精准地理解代码关系。

### 8.2 分步操作优于一步到位

**不推荐：**
```
claude> 帮我创建一个完整的用户认证系统，包括注册、登录、JWT、密码重置、邮箱验证
```

**推荐：**
```
claude> 第一步：创建用户数据模型和数据库迁移
claude> 第二步：实现注册和登录接口
claude> 第三步：添加 JWT 中间件
claude> 第四步：实现密码重置流程
claude> 第五步：添加邮箱验证
```

分步操作让每一步的输出可验证，出问题也更容易回滚。

### 8.3 利用 Plan Mode（规划模式）

对于复杂任务，使用 `EnterPlanMode` 让 Claude 先制定计划：

```
claude> 我需要把这个项目从 Express 迁移到 Fastify，帮我规划一下
```

Claude 会先输出迁移计划，等你确认后再执行。这避免了错误方向上的大量工作。

### 8.4 成本控制

Claude Code 按 Token 使用量计费。控制成本的关键策略：

| 策略 | 说明 |
|------|------|
| `/compact` | 压缩上下文，减少 Token 消耗 |
| `/clear` | 完成一个阶段后清除历史，重新开始 |
| 精准提问 | 避免模糊的大范围问题 |
| 用 CLAUDE.md | 把常用规则写入文件，避免每次重复说明 |
| 选择合适模型 | `/model` 切换到 Sonnet（便宜）或 Opus（强大） |

### 8.5 常见新手陷阱

**陷阱 1：忽略 Diff 直接全盘接受**

每次 Claude 修改文件都会展示 Diff。建议**仔细阅读**，至少确认修改的方向正确。

**陷阱 2：对话历史过长导致质量下降**

上下文窗口有限。当你感觉 Claude 的回复"变笨"时，执行 `/clear` 开始新对话。

**陷阱 3：不写 CLAUDE.md**

没有 CLAUDE.md，Claude 每次都要重新理解你的项目规范。花 5 分钟写一份，后续每次对话都受益。

**陷阱 4：让 Claude 一次做太多事**

Claude Code 很强大，但"小步快跑"永远比"一步到位"更可靠。

---

## 九、四端安装对比

Claude Code 不仅限于终端，以下是四种使用方式的安装与特点对比：

```mermaid
flowchart LR
    subgraph 四端使用
        A[终端 CLI<br/>npm install -g<br/>功能最全]
        B[桌面应用<br/>下载 dmg/exe<br/>开箱即用]
        C[VS Code 插件<br/>扩展商店安装<br/>编辑器内使用]
        D[浏览器<br/>claude.ai/code<br/>零安装]
    end

    A --- E[适合：全栈开发者<br/>DevOps 工程师]
    B --- F[适合：前端开发者<br/>非终端用户]
    C --- G[适合：日常编码<br/>轻量任务]
    D --- H[适合：快速体验<br/>临时使用]
```

| 维度 | 终端 CLI | 桌面应用 | VS Code 插件 | 浏览器 |
|------|---------|---------|-------------|--------|
| 安装方式 | `npm install -g` | 下载安装包 | 扩展商店搜索安装 | 打开网页 |
| 功能完整度 | ★★★★★ | ★★★★☆ | ★★★☆☆ | ★★★☆☆ |
| 定制能力 | 最高 | 中等 | 中等 | 最低 |
| 学习曲线 | 中等 | 低 | 低 | 最低 |
| 适合场景 | 全功能开发 | 日常编码 | 编辑器内辅助 | 快速体验 |

---

## 十、从入门到进阶的学习路径

完成本教程后，建议按以下路径继续深入：

```mermaid
flowchart TD
    A[✅ 你在这里<br/>安装与第一个项目] --> B[Step 2<br/>CLAUDE.md 深度定制]
    B --> C[Step 3<br/>Skills 自定义命令]
    C --> D[Step 4<br/>MCP 服务器集成]
    D --> E[Step 5<br/>Hooks 自动化]
    E --> F[Step 6<br/>多 Agent 协作]
    F --> G[Step 7<br/>CI/CD 集成]

    style A fill:#4CAF50,color:#fff
    style B fill:#2196F3,color:#fff
    style C fill:#2196F3,color:#fff
    style D fill:#FF9800,color:#fff
    style E fill:#FF9800,color:#fff
    style F fill:#9C27B0,color:#fff
    style G fill:#9C27B0,color:#fff
```

每个阶段的核心学习点：

| 阶段 | 核心技能 | 预计时间 |
|------|---------|---------|
| 安装与入门 | 环境搭建、基本交互、第一个项目 | 1-2 天 |
| CLAUDE.md 定制 | 项目配置、多层配置体系、团队规范 | 2-3 天 |
| Skills 开发 | 自定义斜杠命令、提示词工程 | 3-5 天 |
| MCP 服务器 | 外部工具集成、协议理解、服务器开发 | 5-7 天 |
| Hooks 自动化 | 工作流编排、事件驱动、质量门禁 | 3-5 天 |
| 多 Agent 协作 | Worktree 并行、子 Agent 调度 | 5-7 天 |
| CI/CD 集成 | -p 模式、GitHub Actions、自动审查 | 3-5 天 |

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | 全栈开发训练营、AI 工具培训、企业内部开发者培训 |
| 学员基础要求 | 会使用终端、有任意语言编程经验、了解 REST API 概念 |
| 预计教学时长 | 3-4 小时（含实操），建议分两个 2 小时场次 |
| 实操占比 | 70%（学员现场安装、配置、完成第一个项目） |
| 硬件要求 | 学员自带笔记本（macOS/Linux/WSL），需联网 |
| 考核方式 | 学员独立使用 Claude Code 完成一个指定功能的 API 项目 |

---

## 参考来源

1. [Quickstart — Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速入门指南
2. [Terminal Guide for New Users — Claude Code Docs](https://code.claude.com/docs/en/terminal-guide) — 面向终端新手的安装教程
3. [Claude Code Tutorial for Beginners — Complete 2026 Guide](https://codewithmukesh.com/blog/claude-code-for-beginners/) — 第三方完整入门教程，含 27 节课程
4. [Claude Code: Complete Guide to Installation and Getting Started](https://neurohive.io/en/guides/claude-code-getting-started-guide/) — Neurohive 安装配置详解
5. [Claude Code Cheat Sheet — Commands, Shortcuts, Tips](https://computingforgeeks.com/claude-code-cheat-sheet/) — 命令速查与配置参考

> [!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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)