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

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

## 概述

本教程面向从未接触过 Claude Code 的开发者，目标是在 60 分钟内完成从零安装、身份认证、项目初始化，到使用 Claude Code 独立完成一个可运行的 Todo 应用的全过程。适合有基本命令行经验但不需要任何 AI 编程工具使用基础的开发者。读完本文，你将掌握 Claude Code 的核心工作流，并具备在真实项目中使用它的能力。

## 前置条件

| 条件 | 说明 |
|------|------|
| 操作系统 | macOS 12+、Ubuntu 20.04+、Windows 10+（需 WSL2） |
| Node.js | v18.0+，推荐 v20 LTS |
| 终端 | 任意终端模拟器（iTerm2、Windows Terminal 等） |
| 网络 | 能访问 Anthropic API 或 claude.ai |
| 账户 | Claude Pro/Max/Team 订阅，或 Anthropic API Key |

如果你还没有 Node.js，先安装它：

```bash
# macOS（推荐 Homebrew）
brew install node@20

# Linux / WSL2（推荐 nvm）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

# 验证
node --version   # 应显示 v20.x.x
npm --version    # 应显示 10.x.x
```

---

## 第一步：安装 Claude Code

### 1.1 全局安装

Claude Code 是一个 npm 包，一条命令即可安装：

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

**预期结果：**

```
added 1 package in 12s
1 package is looking for funding
```

**验证安装：**

```bash
claude --version
# 输出示例：2.1.56
```

### 1.2 常见安装问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| `EACCES: permission denied` | npm 全局目录权限不足 | 不要用 `sudo`！执行下方修复命令 |
| `command not found: claude` | npm 全局 bin 不在 PATH 中 | 检查 `npm config get prefix` 并加入 PATH |
| `node: not found` | 未安装 Node.js | 按前置条件安装 Node.js |

**修复 npm 全局权限问题（Linux/macOS）：**

```bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 重新安装
npm install -g @anthropic-ai/claude-code
```

---

## 第二步：身份认证

Claude Code 提供两种认证方式，根据你的账户类型选择一种即可。

### 方式 A：Claude 订阅认证（推荐新手使用）

如果你有 Claude Pro、Max 或 Team 订阅：

```bash
claude auth login
```

执行后会自动打开浏览器，跳转到 Anthropic 的 OAuth 授权页面。登录你的 Claude 账户并授权即可。终端会显示：

```
✓ Authentication successful. Logged in as your-email@example.com
```

### 方式 B：API Key 认证

如果你使用 Anthropic API：

```bash
# 临时设置（仅当前终端会话有效）
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 永久设置（写入 shell 配置文件）
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc
```

> ⚠️ **安全提示：** 绝对不要把 API Key 提交到 Git 仓库。确认 `.gitignore` 中包含 `.env` 文件。

### 验证认证成功

```bash
claude -p "你好，请用一句话介绍你自己"
```

如果看到 Claude 的回复，说明认证成功。

---

## 第三步：认识核心命令

Claude Code 有两种使用模式：**交互模式**和**非交互模式**。新手先用交互模式。

### 3.1 启动交互模式

```bash
# 进入项目目录
mkdir ~/my-todo-app && cd ~/my-todo-app

# 启动 Claude Code
claude
```

你会看到 Claude Code 的 REPL 界面，左下角显示当前模型和用量信息。

### 3.2 必须掌握的 7 个斜杠命令

| 命令 | 功能 | 使用频率 |
|------|------|----------|
| `/help` | 显示所有可用命令 | 首次使用时 |
| `/init` | 为当前项目生成 CLAUDE.md 配置文件 | 每个新项目一次 |
| `/compact` | 压缩对话上下文，释放 token 空间 | 每 10-15 轮对话一次 |
| `/clear` | 清空当前对话 | 切换任务时 |
| `/cost` | 查看当前会话费用 | 定期检查 |
| `/model` | 切换模型（opus/sonnet/haiku） | 需要时 |
| `/permissions` | 管理工具权限 | 配置时 |

### 3.3 非交互模式（管道和脚本）

```bash
# 单次提问
claude -p "解释当前目录的 package.json 中的依赖关系"

# 管道输入
cat src/app.ts | claude -p "为这个文件添加单元测试"

# 指定输出格式
claude -p "列出 src/ 下所有文件" --output-format json

# 设置费用上限
claude -p "重构这个函数" --max-budget-usd 0.50
```

### 工作流全景图

```mermaid
flowchart TD
    A[启动 claude] --> B{选择模式}
    B -->|交互式| C[REPL 界面]
    B -->|管道式| D["claude -p 命令"]

    C --> E[描述需求]
    E --> F[Claude 分析代码]
    F --> G[读取文件/执行命令]
    G --> H[生成代码修改]
    H --> I{用户确认}
    I -->|接受| J[变更生效]
    I -->|拒绝| K[调整需求]
    K --> E

    D --> L[输出结果到 stdout]

    J --> M["/compact 压缩上下文"]
    M --> E

    style A fill:#e1f5fe
    style J fill:#c8e6c9
    style I fill:#fff9c4
```

---

## 第四步：配置项目环境

### 4.1 生成 CLAUDE.md

`CLAUDE.md` 是 Claude Code 理解你项目的核心配置文件，类似 `.cursorrules` 或 `.github/copilot-instructions.md`。

```bash
cd ~/my-todo-app
claude
```

在交互界面中输入：

```
/init
```

Claude 会扫描项目目录并生成一个基础 `CLAUDE.md`。由于这是空项目，我们手动创建一个：

```markdown
# Todo App

## 技术栈
- 语言：TypeScript
- 运行时：Node.js 20
- 测试：Vitest
- 无框架，纯 Node.js 实现

## 项目结构
- src/index.ts — 主入口
- src/todo.ts — Todo 核心逻辑
- src/storage.ts — 存储层
- tests/ — 测试文件

## 编码规范
- TypeScript strict 模式
- 函数式风格优先
- 所有公共函数必须有 JSDoc 注释
- 错误处理：throw Error，不返回 null

## 常用命令
- `npm run dev` — 启动开发模式
- `npm test` — 运行测试
- `npm run build` — 编译 TypeScript
```

### 4.2 配置权限（settings.json）

权限系统控制 Claude Code 能执行哪些操作。在项目根目录创建 `.claude/settings.json`：

```bash
mkdir -p .claude
```

```json
{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(node:*)",
      "Bash(npx:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(mkdir:*)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)"
    ]
  }
}
```

### 4.3 配置层级理解

Claude Code 的配置有三个层级，优先级从高到低：

```mermaid
flowchart BT
    A["~/.claude/settings.json<br/>（用户全局配置）"] --> B[".claude/settings.json<br/>（项目共享配置，提交到 Git）"]
    B --> C[".claude/settings.local.json<br/>（项目本地配置，不提交 Git）"]

    style C fill:#c8e6c9
    style B fill:#fff9c4
    style A fill:#e1f5fe
```

| 层级 | 路径 | 用途 | 是否提交 Git |
|------|------|------|-------------|
| 用户全局 | `~/.claude/settings.json` | 所有项目共享的基础配置 | — |
| 项目共享 | `.claude/settings.json` | 团队共享的项目权限 | ✅ 是 |
| 项目本地 | `.claude/settings.local.json` | 个人偏好（如模型选择） | ❌ 否 |

---

## 第五步：实战 — 构建第一个 Todo 应用

现在让我们用 Claude Code 从零构建一个完整的命令行 Todo 应用。

### 5.1 初始化项目

在 Claude Code 交互界面中输入：

```
帮我初始化一个 TypeScript + Node.js 项目，使用 Vitest 作为测试框架。
项目名为 todo-app，需要包含 package.json、tsconfig.json、vitest.config.ts。
```

**预期结果：** Claude 会执行以下操作：
1. 运行 `npm init -y` 创建 `package.json`
2. 创建 `tsconfig.json` 配置 TypeScript
3. 安装依赖：`npm install -D typescript vitest @types/node`
4. 创建 `vitest.config.ts`
5. 添加 npm scripts：`dev`、`test`、`build`

Claude 每一步都会请求你的确认。仔细阅读拟执行的操作，按 `y` 确认。

### 5.2 实现核心逻辑

```
创建 src/todo.ts，实现 Todo 类，需要支持以下功能：
1. 添加任务（add）—— 参数：title (string)，返回 TodoItem
2. 完成任务（complete）—— 参数：id (number)，返回 boolean
3. 删除任务（remove）—— 参数：id (number)，返回 boolean  
4. 列出所有任务（list）—— 返回 TodoItem[]
5. 按状态筛选（filter）—— 参数：completed (boolean)，返回 TodoItem[]

TodoItem 接口：{ id: number, title: string, completed: boolean, createdAt: Date }
每个方法需要 JSDoc 注释。
```

### 5.3 实现存储层

```
创建 src/storage.ts，实现 JsonStorage 类：
- 构造函数接收文件路径（默认 ./data/todos.json）
- save(items: TodoItem[]): void —— 写入 JSON 文件
- load(): TodoItem[] —— 读取 JSON 文件，文件不存在返回空数组
- 使用 fs/promises 进行异步文件操作
```

### 5.4 实现主入口

```
创建 src/index.ts，实现命令行交互界面：
- 使用 readline/promises 读取用户输入
- 支持命令：add <title>, done <id>, rm <id>, list, filter <done|pending>, quit
- 启动时从存储加载已有任务
- 每次操作后自动保存
- 优雅的错误处理和退出
```

### 5.5 让 Claude 写测试

```
为 src/todo.ts 编写完整的单元测试，放在 tests/todo.test.ts 中。
测试用例需要覆盖：
- 添加任务
- 完成任务（正常和 id 不存在的情况）
- 删除任务（正常和 id 不存在的情况）
- 列出所有任务
- 按状态筛选
- 自增 ID 的正确性
```

**预期测试文件内容（Claude 生成）：**

```typescript
import { describe, it, expect } from 'vitest';
import { Todo } from '../src/todo';

describe('Todo', () => {
  let todo: Todo;

  beforeEach(() => {
    todo = new Todo();
  });

  it('should add a task', () => {
    const item = todo.add('Learn Claude Code');
    expect(item.id).toBe(1);
    expect(item.title).toBe('Learn Claude Code');
    expect(item.completed).toBe(false);
  });

  it('should auto-increment IDs', () => {
    todo.add('Task 1');
    todo.add('Task 2');
    const items = todo.list();
    expect(items).toHaveLength(2);
    expect(items[1].id).toBe(2);
  });

  it('should complete a task', () => {
    todo.add('Task 1');
    const result = todo.complete(1);
    expect(result).toBe(true);
    expect(todo.list()[0].completed).toBe(true);
  });

  it('should return false for non-existent id on complete', () => {
    const result = todo.complete(999);
    expect(result).toBe(false);
  });

  it('should remove a task', () => {
    todo.add('Task 1');
    const result = todo.remove(1);
    expect(result).toBe(true);
    expect(todo.list()).toHaveLength(0);
  });

  it('should filter by status', () => {
    todo.add('Task 1');
    todo.add('Task 2');
    todo.complete(1);
    const completed = todo.filter(true);
    const pending = todo.filter(false);
    expect(completed).toHaveLength(1);
    expect(pending).toHaveLength(1);
  });
});
```

### 5.6 运行测试

```
运行测试，确保全部通过
```

Claude 会执行 `npm test`。如果测试全部通过，你会看到：

```
 ✓ tests/todo.test.ts (6 tests) 12ms
   ✓ Todo > should add a task
   ✓ Todo > should auto-increment IDs
   ✓ Todo > should complete a task
   ✓ Todo > return false for non-existent id
   ✓ Todo > remove a task
   ✓ Todo > filter by status

 Test Files  1 passed (1)
 Tests       6 passed (6)
```

### 5.7 运行应用

```
编译并运行应用，测试添加几个任务
```

Claude 会执行：

```bash
npm run build    # 编译 TypeScript
node dist/index.js
```

---

## 第六步：IDE 集成

虽然 Claude Code 在终端中功能完整，但结合 IDE 使用体验更佳。

### 6.1 VS Code

在 VS Code 扩展市场搜索 **"Claude Code"** 并安装。

**三种使用方式：**

| 方式 | 入口 | 适用场景 |
|------|------|----------|
| 扩展面板 | 侧边栏 Claude 图标 | 查看可视化 diff、@引用文件 |
| 集成终端 | VS Code 内置终端 | 完整 CLI 功能 + 文件感知 |
| 外部终端 + `/ide` | 终端中输入 `/ide` | 完整 CLI + IDE 联动 |

**推荐新手使用集成终端**：在 VS Code 中打开项目，按 `` Ctrl+` `` 打开终端，输入 `claude`。Claude 会自动感知 VS Code 中打开的文件和选中的代码。

### 6.2 JetBrains 系列

支持 IntelliJ IDEA、PyCharm、WebStorm、GoLand、Android Studio 等。

1. 打开 `Settings → Plugins → Marketplace`
2. 搜索 **"Claude Code"** 并安装
3. 重启 IDE 后，底部工具栏出现 Claude Code 面板

**JetBrains 独有功能：**
- 选中代码自动作为上下文传递
- 使用 JetBrains 原生 Diff Viewer 查看变更
- 与 IDE 的 Run Configuration 集成

---

## 第七步：上下文管理 — 长期项目的关键技能

### 7.1 为什么要管理上下文

Claude Code 的对话有 token 上限。当项目变大、对话变长时，你需要主动管理上下文，否则 Claude 会"遗忘"早期信息。

```mermaid
flowchart LR
    A[对话开始] --> B[上下文逐渐增长]
    B --> C{接近上限?}
    C -->|否| B
    C -->|是| D["/compact 压缩"]
    D --> E[保留关键信息]
    E --> F[释放 token 空间]
    F --> B

    G[".claudeignore"] -.->|排除无关文件| B
    H["CLAUDE.md"] -.->|提供持久上下文| B
    I["Memory 系统"] -.->|跨会话记忆| B

    style D fill:#fff9c4
    style G fill:#ffcdd2
    style H fill:#c8e6c9
    style I fill:#e1bee7
```

### 7.2 五个上下文管理技巧

**技巧 1：定期 `/compact`**

每 10-15 轮对话执行一次。Claude 会压缩历史对话，保留关键信息，释放空间。

**技巧 2：善用 `.claudeignore`**

类似 `.gitignore`，排除不需要 Claude 看到的文件：

```
node_modules/
dist/
*.min.js
*.map
package-lock.json
data/
```

**技巧 3：写好 CLAUDE.md**

把项目约定、技术栈、目录结构写清楚。这是每次新会话 Claude 首先读取的文件，相当于项目的"入职手册"。

**技巧 4：精准引用文件**

不要让 Claude 自己大海捞针，直接告诉它看哪里：

```
# ❌ 模糊
帮我修复 bug

# ✅ 精准
@src/todo.ts 第 42 行的 complete 方法有个 bug：
当 id 不存在时应该抛出错误而不是返回 false。请修复。
```

**技巧 5：使用 Memory 系统**

在对话中使用 `/memory` 查看 Claude 的持久记忆。Claude 会自动将重要的项目知识保存到 `~/.claude/projects/` 目录下，下次会话自动加载。

---

## 第八步：费用控制与模型选择

### 8.1 模型选择策略

| 模型 | 特点 | 适用场景 | 相对成本 |
|------|------|----------|----------|
| Claude Sonnet 4.6 | 速度与能力的最佳平衡 | 日常开发、代码生成 | 基准 |
| Claude Opus 4.6 | 最强推理能力 | 复杂架构设计、疑难 bug | 较高 |
| Claude Haiku 4.5 | 最快响应速度 | 简单查询、格式转换 | 最低 |

**切换模型：**

```bash
# 交互模式中
/model opus

# 非交互模式
claude -p "解释这段代码" --model haiku
```

### 8.2 费用监控

```bash
# 交互模式中查看当前会话费用
/cost

# 非交互模式设置费用上限
claude -p "重构这个函数" --max-budget-usd 1.00
```

### 8.3 省钱策略

1. **简单任务用 Haiku**：格式化、注释、简单查询
2. **日常编码用 Sonnet**：默认模型，性价比最高
3. **复杂问题用 Opus**：架构决策、多文件重构
4. **及时 `/compact`**：减少无效 token 消耗
5. **写清楚需求**：一次说清楚比反复修改更省钱

---

## 第九步：权限系统详解

权限系统是 Claude Code 安全模型的核心。理解它，你才能安心让 AI 操作你的文件系统。

### 9.1 四种权限模式

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| `default` | 危险操作需确认 | 日常开发 |
| `acceptEdits` | 自动接受文件编辑 | 快速迭代 |
| `plan` | 仅规划不执行 | 审查方案 |
| `bypassPermissions` | 跳过所有确认 | CI/CD 自动化 |

### 9.2 权限配置模式

```json
{
  "permissions": {
    "allow": [
      "Bash(git status:*)",       // 允许 git status 的任何参数
      "Bash(npm test:*)",          // 允许 npm test 的任何参数
      "Bash(npm run lint:*)",      // 允许 npm run lint 的任何参数
      "Read",                      // 允许读取任何文件
      "Glob",                      // 允许文件模式匹配
      "Grep"                       // 允许内容搜索
    ],
    "deny": [
      "Bash(rm -rf:*)",            // 禁止 rm -rf
      "Bash(git push --force:*)",  // 禁止强制推送
      "Bash(git reset --hard:*)"   // 禁止硬重置
    ]
  }
}
```

> 💡 **建议：** 初期使用 `default` 模式，逐步将频繁确认的安全操作加入 allow 列表。不要一开始就用 `bypassPermissions`。

---

## 第十步：从 Todo 应用学到的完整工作流

让我们用一个完整的流程图回顾整个开发流程：

```mermaid
flowchart TD
    subgraph 准备阶段
        A[安装 Claude Code] --> B[认证登录]
        B --> C[创建项目目录]
        C --> D["运行 /init 生成 CLAUDE.md"]
    end

    subgraph 开发阶段
        D --> E[描述需求]
        E --> F[Claude 读取项目文件]
        F --> G[Claude 生成代码方案]
        G --> H{审查方案}
        H -->|确认| I[代码写入文件]
        H -->|修改需求| E
        I --> J[运行测试验证]
        J --> K{测试通过?}
        K -->|是| L[继续下一个功能]
        K -->|否| M[让 Claude 修复]
        M --> J
        L --> E
    end

    subgraph 维护阶段
        L --> N["/compact 压缩上下文"]
        N --> O["/cost 检查费用"]
        O --> P[提交 Git]
        P --> Q[下一个任务]
    end

    style A fill:#e1f5fe
    style I fill:#c8e6c9
    style K fill:#fff9c4
    style M fill:#ffcdd2
```

---

## 常见问题速查表

| 问题 | 命令/操作 |
|------|-----------|
| 安装后 `claude` 命令找不到 | `npm config get prefix` 检查路径，加入 PATH |
| 认证失败 401 | 检查 API Key 是否正确，或重新 `claude auth login` |
| 权限弹窗太频繁 | 编辑 `.claude/settings.json` 的 allow 列表 |
| 回复越来越慢 | 执行 `/compact` 压缩上下文 |
| 想切换模型 | `/model opus` 或 `/model haiku` |
| 想查看费用 | `/cost` |
| 对话跑偏了 | `/clear` 清空重来 |
| 想了解某个文件 | `@src/app.ts 解释这个文件的结构` |
| Claude 修改了不该改的文件 | 检查 deny 列表，添加 `Bash(vim:*)` 等限制 |

---

## 进阶方向

掌握了基础之后，可以按以下顺序深入学习：

1. **Skills 系统** — 创建可复用的自定义工作流，用 `/command` 触发
2. **MCP 服务器** — 连接外部工具（数据库、API、文件系统）扩展能力
3. **Agent 模式** — 使用 `claude -p` 实现自动化流水线，集成 CI/CD
4. **Hooks 机制** — 在特定事件（如文件保存、Git 提交）自动触发 Claude 操作
5. **多 Agent 协作** — 使用 Workflows 编排多个 Agent 并行处理复杂任务

---

## 参考来源

1. [Claude Code 官方文档 — Overview](https://docs.anthropic.com/en/docs/claude-code/overview) — Anthropic 官方 Claude Code 功能概述与安装指引
2. [Claude Code 官方文档 — Quickstart](https://docs.anthropic.com/en/docs/claude-code/quickstart) — 快速入门指南，包含安装和首个项目
3. [Claude Code GitHub 仓库](https://github.com/anthropics/claude-code) — 源代码、Issue 追踪和社区讨论
4. [Anthropic Blog — Claude Code Deep Dive](https://www.anthropic.com/blog/claude-code) — Anthropic 官方博客对 Claude Code 设计理念的介绍
5. [Claude Code 最佳实践指南](https://docs.anthropic.com/en/docs/claude-code/best-practices) — 官方推荐的项目配置和上下文管理技巧

---

> 🏫 **训练营适用性评估：** 本教程适合「AI 编程工具入门」类型训练营，面向有编程基础但未使用过 AI 编程助手的开发者。预计教学时长 90-120 分钟（含动手实操环节）。可作为训练营第一天的入门课程，后续衔接 Skills 开发和 MCP 服务器开发课程。建议教学形式：讲师现场演示安装和配置，学员跟随操作完成 Todo 应用，最后 30 分钟自由探索和答疑。

> [!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)