<!-- title: Claude Code零基础入门：安装配置与首个项目 -->

# Claude Code零基础入门：安装配置与首个项目

## 概述

本教程面向零基础开发者，系统讲解如何从零安装、配置并使用 Claude Code —— Anthropic 官方推出的终端 AI 编程助手。学完本教程，你将能够独立完成 Claude Code 的安装、身份认证、项目配置，并使用它完成一个真实的小型项目。适用人群：有基本命令行经验但从未接触过 Claude Code 的开发者。

---

## 一、Claude Code 是什么

Claude Code 是 Anthropic 推出的一款**运行在终端中的 AI 编程助手**。它与浏览器中的 ChatGPT 或 Claude.ai 不同，直接运行在你的本地终端环境中，能够：

- **读写你的项目文件** —— 理解整个代码仓库的上下文
- **执行终端命令** —— 运行测试、安装依赖、启动服务
- **操作 Git** —— 提交代码、创建分支、解决冲突
- **搜索代码** —— 使用 Grep、Glob 等工具快速定位代码
- **启动子代理** —— 并行处理多个独立任务

简单来说，Claude Code 就像一个坐在你旁边的高级开发者，通过终端和你对话，直接帮你写代码、调 Bug、做重构。

### 核心架构


![图表1](images/claude-code-tutorial-0102-mermaid-0.png)

> *图表 1*


Claude Code 本身是一个 Node.js 命令行工具，它将你的指令、项目文件内容、终端输出等信息发送给 Anthropic 的 Claude 模型，模型返回操作指令，Claude Code 再在本地执行这些操作。整个过程在你的机器上完成，代码不会上传到 Anthropic 的服务器（只有文本内容会发送给模型）。

---

## 二、前置条件

在开始安装之前，请确保你的系统满足以下要求：

| 要求 | 最低版本 | 推荐版本 | 检查命令 |
|------|----------|----------|----------|
| **Node.js** | v18.0+ | v20.x LTS | `node --version` |
| **npm** | v8.0+ | v10.x | `npm --version` |
| **Git** | v2.0+ | 最新版 | `git --version` |
| **内存** | 4GB RAM | 8GB+ | — |
| **网络** | 需要访问 Anthropic API | 稳定连接 | — |

### 2.1 操作系统支持

- **macOS**：原生支持，推荐 macOS 12+
- **Linux**：主流发行版（Ubuntu 20.04+、Fedora、Debian 等）原生支持
- **Windows**：通过 **WSL2**（Windows Subsystem for Linux）使用，不支持原生 Windows CMD/PowerShell

> **Windows 用户注意**：Claude Code 目前不直接支持 Windows 原生终端。你需要先安装 WSL2，在 WSL2 的 Linux 环境中使用。安装 WSL2 的方法：在 PowerShell（管理员）中运行 `wsl --install`，然后重启电脑。

### 2.2 安装 Node.js（如果尚未安装）

推荐使用 **nvm**（Node Version Manager）管理 Node.js 版本：

```bash
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc

# 安装 Node.js LTS 版本
nvm install --lts

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

如果你更喜欢直接安装，也可以从 [Node.js 官网](https://nodejs.org/) 下载安装包。

---

## 三、安装 Claude Code

### 3.1 全局安装

Claude Code 通过 npm 全局安装，一条命令搞定：

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

安装完成后，验证是否成功：

```bash
claude --version
```

如果看到版本号输出（如 `2.1.x`），说明安装成功。

### 3.2 常见安装问题

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

```
npm ERR! Error: EACCES, permission denied
```

**解决方案**：不要使用 `sudo npm install -g`。推荐做法是配置 npm 的全局安装目录：

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

然后重新运行安装命令。

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

安装成功但终端找不到 `claude` 命令，通常是 PATH 问题：

```bash
# 查看 npm 全局安装路径
npm config get prefix

# 将其加入 PATH（假设输出为 /home/yourname/.npm-global）
echo 'export PATH="/home/yourname/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

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

```
Error: Claude Code requires Node.js 18 or later
```

使用 nvm 切换到新版本：

```bash
nvm install 20
nvm use 20
nvm alias default 20
```

---

## 四、身份认证

安装完成后，首次运行 `claude` 会引导你完成身份认证。Claude Code 支持两种认证方式：

### 4.1 OAuth 认证（推荐）

如果你有 Claude Pro、Max 或 Team 订阅，推荐使用 OAuth：

```bash
claude
```

首次运行会显示一个 URL，按回车后会自动在浏览器中打开。在浏览器中登录你的 Anthropic 账号并授权即可。

### 4.2 API Key 认证

如果你使用 API Key（按量付费模式）：

```bash
# 设置 API Key 环境变量
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"

# 然后启动
claude
```

建议将 API Key 写入 shell 配置文件，避免每次手动设置：

```bash
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc
```

> **安全提醒**：永远不要将 API Key 提交到 Git 仓库。确保 `.gitignore` 中包含 `.env` 文件。

### 4.3 验证认证状态

启动 Claude Code 后，如果看到类似下面的提示，说明认证成功：

```
╭──────────────────────────────────────────────╮
│  Welcome to Claude Code!                     │
│                                              │
│  Model: claude-sonnet-4-6                    │
│  Account: your@email.com                     │
╰──────────────────────────────────────────────╯
>
```

---

## 五、核心概念速览

在开始实战之前，先了解 Claude Code 的几个核心概念：

### 5.1 交互模式

| 模式 | 启动方式 | 用途 |
|------|----------|------|
| **交互式 REPL** | `claude` | 持续对话，适合开发调试 |
| **单次执行** | `claude "你的指令"` | 一次性任务，执行完退出 |
| **管道模式** | `cat file.txt \| claude "分析这个文件"` | 将输入传给 Claude 处理 |
| **恢复会话** | `claude --resume` | 继续上次未完成的对话 |

### 5.2 权限模型

Claude Code 的操作需要你的授权。它会将操作分为几类：

- **只读操作**（读文件、搜索代码）：默认允许
- **写入操作**（编辑文件、创建文件）：需要确认
- **危险操作**（删除文件、执行命令）：需要明确批准

你可以通过权限配置减少重复确认的烦恼（后文详述）。

### 5.3 上下文管理

Claude Code 自动收集以下上下文信息：

- 当前目录的文件结构
- Git 仓库状态
- `CLAUDE.md` 文件中的指令
- 项目中的关键文件（package.json、配置文件等）

---

## 六、核心命令与快捷键

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

在交互模式中，使用 `/` 开头的命令来执行特定操作：

| 命令 | 功能 | 使用场景 |
|------|------|----------|
| `/help` | 查看帮助信息 | 忘记命令时查看 |
| `/clear` | 清除对话历史 | 上下文过长时重置 |
| `/compact` | 压缩对话历史 | 上下文快满时节省空间 |
| `/model` | 切换模型 | 切换 Sonnet/Opus 等 |
| `/plan` | 进入规划模式 | 复杂任务先制定计划 |
| `/permissions` | 管理权限 | 调整自动允许的操作 |
| `/review` | 代码审查 | 让 Claude 审查代码变更 |
| `/cost` | 查看会话费用 | 监控 API 用量 |
| `/status` | 查看当前状态 | 检查模型、上下文等信息 |
| `/memory` | 查看/编辑记忆 | 管理跨会话记忆 |
| `/mcp` | MCP 服务器管理 | 查看 MCP 连接状态 |
| `/vim` | 切换 Vim 模式 | Vim 爱好者 |
| `/quit` | 退出 Claude Code | 结束会话 |

### 6.2 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息（单行模式） |
| `Shift + Enter` | 换行（不发送） |
| `Escape` | 取消当前操作/中断 Claude 的回复 |
| `Shift + Tab` | 切换 Plan/Act 模式 |
| `Tab` | 自动补全文件路径 |
| `↑` / `↓` | 浏览历史消息 |
| `Ctrl + C` | 中断当前操作 |
| `Ctrl + D` | 退出 Claude Code |

### 6.3 CLI 常用参数

```bash
# 指定模型
claude --model claude-opus-4-6

# 单次执行模式
claude -p "解释这个项目的架构"

# 从标准输入读取
echo "hello world" | claude -p "翻译为中文"

# 恢复上次会话
claude --resume

# 指定工作目录
claude --cwd /path/to/project

# 输出为 JSON 格式（适合脚本集成）
claude -p "list all TODO comments" --output-format json

# 非交互模式（适合 CI/CD）
claude -p "run tests" --allowedTools "Bash(npm test)"
```

---

## 七、CLAUDE.md 配置详解

`CLAUDE.md` 是 Claude Code 的**项目配置文件**，它告诉 Claude 如何理解和处理你的项目。这是 Claude Code 最强大的特性之一。

### 7.1 CLAUDE.md 的层级结构


![图表2](images/claude-code-tutorial-0102-mermaid-1.png)

> *图表 2*


### 7.2 创建你的第一个 CLAUDE.md

在项目根目录创建 `CLAUDE.md` 文件：

```markdown
# 项目说明
这是一个使用 React + TypeScript 的前端项目。

# 技术栈
- React 18 + TypeScript
- Vite 构建工具
- TailwindCSS 样式
- Vitest 测试框架

# 代码规范
- 使用函数式组件和 Hooks
- 变量使用 camelCase，组件使用 PascalCase
- 优先使用命名导出而非默认导出
- 提交信息遵循 Conventional Commits 规范

# 项目结构
- src/components/ - 通用组件
- src/pages/ - 页面组件
- src/hooks/ - 自定义 Hooks
- src/utils/ - 工具函数
- src/api/ - API 请求相关

# 注意事项
- 不要修改 src/generated/ 下的文件（自动生成的）
- 运行测试命令: npm test
- 运行构建命令: npm run build
```

### 7.3 全局 CLAUDE.md

在 `~/.claude/CLAUDE.md` 中放置对所有项目通用的偏好：

```markdown
# 全局偏好
- 回复使用中文
- 代码注释使用英文
- 默认使用 TypeScript
- 优先使用原生 API 而非第三方库
- commit message 不要自动加版本号
```

### 7.4 settings.json 配置

`settings.json` 用于配置 Claude Code 的行为和权限。文件位置：

- **全局配置**：`~/.claude/settings.json`
- **项目配置**：`.claude/settings.json`
- **本地配置**（不提交 Git）：`.claude/settings.local.json`

一个典型的 settings.json：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test*)",
      "Bash(npm run lint*)",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(curl*|*)",
      "Bash(wget*)"
    ]
  },
  "model": "claude-sonnet-4-6",
  "theme": "dark"
}
```

---

## 八、实战：使用 Claude Code 创建第一个项目

现在让我们通过一个完整的实战案例，体验 Claude Code 的完整工作流。我们将创建一个 **命令行待办事项工具**。

### 8.1 创建项目

```bash
# 创建项目目录
mkdir todo-cli && cd todo-cli

# 初始化 Git 仓库
git init

# 启动 Claude Code
claude
```

### 8.2 与 Claude Code 对话

在 Claude Code 的交互提示符中输入：

```
> 帮我创建一个 Python 命令行待办事项工具。要求：
> 1. 使用 argparse 处理命令行参数
> 2. 支持添加、删除、列表、完成标记操作
> 3. 数据存储在 JSON 文件中
> 4. 代码结构清晰，有类型注解
```

Claude Code 会：
1. 分析你的需求
2. 创建 `todo.py` 文件（会请求你确认）
3. 可能还会创建 `requirements.txt` 或 `README.md`

### 8.3 查看生成的代码

在 Claude Code 中使用 `/review` 或者直接说：

```
> 展示你创建的文件的内容
```

你应该能看到类似以下的 Python 文件：

```python
# todo.py
import argparse
import json
from pathlib import Path
from datetime import datetime
from typing import Optional

DATA_FILE = Path.home() / ".todo_data.json"

def load_todos() -> list[dict]:
    """Load todos from JSON file."""
    if DATA_FILE.exists():
        return json.loads(DATA_FILE.read_text())
    return []

def save_todos(todos: list[dict]) -> None:
    """Save todos to JSON file."""
    DATA_FILE.write_text(json.dumps(todos, indent=2, ensure_ascii=False))

def add_todo(title: str, priority: str = "normal") -> None:
    """Add a new todo item."""
    todos = load_todos()
    todos.append({
        "id": len(todos) + 1,
        "title": title,
        "priority": priority,
        "done": False,
        "created_at": datetime.now().isoformat()
    })
    save_todos(todos)
    print(f"✅ Added: {title}")

def list_todos(show_all: bool = False) -> None:
    """List all todo items."""
    todos = load_todos()
    if not todos:
        print("No todos found.")
        return
    for todo in todos:
        status = "✓" if todo["done"] else "○"
        print(f"  {status} [{todo['id']}] {todo['title']} ({todo['priority']})")

# ... 更多函数
```

### 8.4 测试与迭代

继续在 Claude Code 中对话来完善项目：

```
> 给我添加单元测试，使用 pytest 框架

> 帮我添加一个 --sort 参数，可以按优先级排序

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

Claude Code 会自动执行 `pytest` 命令并报告结果。

### 8.5 提交代码

当项目完成后：

```
> 帮我提交代码到 Git
```

Claude Code 会自动执行 `git add`、`git status`、`git commit` 等操作（每步都会请求你确认）。

---

## 九、高效工作流技巧

### 9.1 Plan 模式：先规划再执行

对于复杂任务，先进入 Plan 模式，让 Claude 制定计划后再执行：

```
> /plan
```

或使用快捷键 `Shift + Tab` 切换到 Plan 模式。在 Plan 模式下，Claude 只会分析代码和制定方案，不会修改任何文件。确认方案后再切回 Act 模式执行。

### 9.2 上下文压缩

当对话过长时，使用 `/compact` 压缩历史：

```
> /compact
```

Claude Code 会自动总结之前的对话，释放上下文空间。你也可以自定义压缩提示：

```
> /compact 请保留所有关于数据库schema的讨论
```

### 9.3 恢复会话

如果你意外退出或想继续昨天的工作：

```bash
# 恢复最近的会话
claude --resume

# 继续特定会话（Claude 会列出最近的会话供选择）
claude --continue
```

### 9.4 多文件编辑

Claude Code 擅长处理跨多个文件的修改：

```
> 把所有的 console.log 替换成自定义的 logger，并创建 logger 模块
```

Claude Code 会搜索所有相关文件，一次性完成修改。

### 9.5 使用 -p 模式自动化

`-p`（pipe/prompt）模式适合将 Claude Code 集成到脚本中：

```bash
# 代码审查
claude -p "review the changes in my git diff and suggest improvements" < <(git diff)

# 自动生成 commit message
claude -p "generate a conventional commit message" < <(git diff --staged)

# 批量文件处理
for file in src/*.ts; do
  claude -p "add type annotations to this TypeScript file" < "$file" > "${file%.ts}.typed.ts"
done
```

---

## 十、权限精细控制

### 10.1 权限模式

Claude Code 提供三种权限模式：

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| **Default** | 每次操作都确认 | 新手推荐，安全 |
| **Auto-accept edits** | 自动接受文件编辑 | 信任 Claude 的编辑能力 |
| **Yolo/Auto-accept all** | 自动接受所有操作 | CI/CD、自动化场景 |

### 10.2 在 settings.json 中配置权限

```json
{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(git *)",
      "Bash(npm test*)",
      "Bash(npm run lint*)",
      "Bash(npm run build*)",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(pytest*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(chmod 777*)"
    ]
  }
}
```

**语法规则**：
- `"Bash(npm test*)"` —— 允许所有以 `npm test` 开头的命令
- `"Bash(git *)"` —— 允许所有 git 命令
- `"Read"` —— 允许所有文件读取操作
- `"Write"` —— 允许所有文件写入操作

### 10.3 交互式权限管理

在会话中使用 `/permissions` 命令可以实时查看和调整权限：

```
> /permissions
```

这会打开一个交互式界面，你可以添加、删除权限规则。

---

## 十一、完整工作流全景

下面是一个典型的 Claude Code 开发工作流：

```text
flowchart LR
    A[终端启动 Claude Code] --> B[认证/选择模型]
    B --> C[读取 CLAUDE.md<br/>加载项目上下文]
    C --> D{任务复杂度}
    D -->|简单任务| E[直接对话执行]
    D -->|复杂任务| F[/plan 模式<br/>制定计划]
    F --> G[审核计划]
    G --> H[切换 Act 模式<br/>逐步执行]
    E --> I[Claude 操作文件<br/>运行命令]
    H --> I
    I --> J{结果满意？}
    J -->|是| K[Git 提交]
    J -->|否| L[继续迭代<br/>补充指令]
    L --> I
    K --> M[推送远程<br/>或创建 PR]
    style F fill:#f59e0b,color:#fff
    style H fill:#10b981,color:#fff
    style K fill:#3b82f6,color:#fff
```

### 最佳实践总结

1. **始终在项目根目录启动** Claude Code，让它能看到完整的项目结构
2. **写好 CLAUDE.md**，这是提升 Claude Code 效率的最大杠杆
3. **复杂任务先 Plan**，避免 Claude 走错方向
4. **及时 `/compact`**，长对话会消耗上下文空间
5. **善用权限配置**，减少重复确认的摩擦
6. **不要盲目确认**，养成审查 Claude 操作的习惯
7. **使用 `--resume` 恢复会话**，保持工作连续性

---

## 十二、常见问题排查

### Q1：Claude Code 响应很慢

- **切换模型**：使用 `/model` 切换到 Sonnet（更快）或 Opus（更强）
- **压缩上下文**：`/compact` 释放空间
- **检查网络**：确保到 Anthropic API 的连接稳定

### Q2：Claude Code 修改了不该改的文件

- **使用 CLAUDE.md 限定范围**：在 CLAUDE.md 中明确标注不要修改的目录
- **配置 deny 权限**：在 settings.json 中禁止特定操作
- **Plan 模式审查**：对关键任务先在 Plan 模式下审查方案

### Q3：上下文耗尽（Context Window Full）

- `/compact` 压缩历史
- `/clear` 完全清除对话
- 将部分讨论记录到 CLAUDE.md 或注释中
- 拆分任务为多个独立会话

### Q4：如何查看费用

使用 `/cost` 命令查看当前会话的 Token 用量和预估费用。

---

## 延伸阅读

- [Claude Code 官方快速入门](https://code.claude.com/docs/en/quickstart) —— Anthropic 官方文档
- [Claude Code 权限配置](https://code.claude.com/docs/en/permissions) —— 权限系统详解
- [Claude Code CLI 速查表](https://support.claude.com/en/articles/14553413-claude-code-cheatsheet) —— 官方命令参考
- [Claude Code GitHub](https://github.com/anthropics/claude-code) —— 源码和 Issue 追踪
- [Claude Code Tips & Tricks](https://github.com/ykdojo/claude-code-tips) —— 社区整理的 45 条技巧

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | AI 工具训练营、前端/后端开发者入门营、DevOps 效率提升营 |
| **预计教学时长** | 2-3 小时（含动手实操） |
| **学员基础要求** | 基本命令行操作能力，了解一门编程语言 |
| **实操比重** | 60% 实操 + 40% 讲解 |
| **最佳分组方式** | 每人独立完成，助教巡场答疑 |
| **考核方式** | 提交一个由 Claude Code 辅助完成的小项目（含 CLAUDE.md 配置） |

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