<!-- title: Claude Code零基础入门到第一个项目 -->

# Claude Code零基础入门：从安装到跑通第一个AI编程项目

> **学习目标**：读完本文后，你将独立完成Claude Code的安装、认证配置、项目初始化，并能用AI辅助完成一个真实的全栈小项目。
>
> **适用人群**：从未使用过Claude Code的开发者，或对终端AI编程工具有兴趣的技术爱好者。假设你具备基础终端操作能力（cd、ls等），但不需要任何AI工具使用经验。

---

## 一、Claude Code是什么？

Claude Code是Anthropic推出的官方AI编程助手，直接运行在终端（Terminal）中。它不是聊天机器人包装——它是一个**真正的Agent**，能够：

| 能力 | 说明 |
|------|------|
| 读取代码库 | 自动扫描项目结构、理解文件间依赖关系 |
| 编辑文件 | 直接修改代码，不是给你"建议让你自己改" |
| 执行命令 | 运行测试、构建项目、安装依赖 |
| 集成工具链 | Git、GitHub、MCP服务器、IDE插件 |
| 管理上下文 | 通过CLAUDE.md文件持久化项目知识 |

2026年的Claude Code已经不再依赖Node.js环境，推出了**原生安装器（Native Installer）**，一条命令即可完成安装。同时提供桌面应用（Desktop App）、VS Code扩展、JetBrains插件等多种使用方式。

```mermaid
graph TB
    subgraph "Claude Code 使用方式"
        A[终端 CLI<br/>claude命令] --> B[核心引擎]
        C[VS Code 扩展] --> B
        D[JetBrains 插件] --> B
        E[Desktop App<br/>桌面应用] --> B
        F[Web 模式<br/>浏览器] --> B
    end

    subgraph "核心能力"
        B --> G[文件读写]
        B --> H[命令执行]
        B --> I[代码搜索]
        B --> J[Git操作]
        B --> K[MCP工具调用]
    end

    style B fill:#f9a825,stroke:#333,color:#000
    style A fill:#4caf50,stroke:#333,color:#fff
    style C fill:#2196f3,stroke:#333,color:#fff
    style D fill:#9c27b0,stroke:#333,color:#fff
    style E fill:#ff5722,stroke:#333,color:#fff
    style F fill:#607d8b,stroke:#333,color:#fff
```

---

## 二、系统要求

在安装之前，确认你的环境满足以下最低要求：

| 项目 | 要求 |
|------|------|
| **操作系统** | macOS 12+、Ubuntu 20.04+ / Debian 11+ / Fedora 38+、Windows 10/11（WSL2 或原生） |
| **内存** | 至少4GB RAM |
| **网络** | 稳定的互联网连接 |
| **磁盘空间** | 约500MB |
| **终端** | 任意现代终端（iTerm2、Terminal.app、Windows Terminal、PowerShell等） |

> **注意**：2026年之前的安装教程通常要求先安装Node.js v18+。现在Claude Code的原生安装器已**不再需要**Node.js环境，但如果你的系统已有Node.js也不冲突。

---

## 三、安装Claude Code

### 3.1 macOS安装

打开终端，执行以下一条命令：

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

安装器会自动：
1. 检测系统架构（Intel/Apple Silicon）
2. 下载对应二进制文件
3. 安装到 `~/.claude/local/bin/` 目录
4. 自动添加到系统PATH

如果你使用Homebrew，也可以：

```bash
brew install claude-code
```

### 3.2 Linux安装

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

对于Debian/Ubuntu系统，也可以使用apt：

```bash
# 添加Anthropic的apt源
curl -fsSL https://apt.claude.ai/gpg | sudo gpg --dearmor -o /usr/share/keyrings/claude.gpg
echo "deb [signed-by=/usr/share/keyrings/claude.gpg] https://apt.claude.ai stable main" | sudo tee /etc/apt/sources.list.d/claude.list
sudo apt update && sudo apt install claude-code
```

### 3.3 Windows安装

**方式一：PowerShell原生安装（推荐）**

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

**方式二：WinGet**

```powershell
winget install Anthropic.ClaudeCode
```

**方式三：WSL2（Windows Subsystem for Linux）**

如果你更习惯Linux环境，在WSL2中安装：

```bash
# 进入WSL
wsl
# 然后使用Linux安装命令
curl -fsSL https://claude.ai/install.sh | sh
```

### 3.4 验证安装

安装完成后，验证Claude Code是否正确安装：

```bash
claude --version
```

预期输出类似：

```
Claude Code v2.1.19
```

如果出现 `command not found`，手动添加PATH：

```bash
# 添加到 ~/.bashrc 或 ~/.zshrc
export PATH="$HOME/.claude/local/bin:$PATH"
source ~/.bashrc  # 或 source ~/.zshrc
```

### 3.5 npm安装方式（传统方式，仍可用）

如果你已有Node.js环境，也可以用npm安装：

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

> **注意**：npm方式不再是官方首推的安装方式。2026年2月之后，npm版本更新可能滞后于原生安装器版本。新用户推荐使用原生安装器。

```mermaid
flowchart LR
    A[开始安装] --> B{操作系统?}
    B -->|macOS| C[curl安装<br/>或 brew install]
    B -->|Linux| D[curl安装<br/>或 apt/yum]
    B -->|Windows| E{安装方式?}
    E -->|原生| F[PowerShell irm]
    E -->|WinGet| G[winget install]
    E -->|WSL2| H[Linux命令]

    C --> I[验证: claude --version]
    D --> I
    F --> I
    G --> I
    H --> I

    I --> J{成功?}
    J -->|是| K[进入认证环节]
    J -->|否| L[检查PATH或重新安装]
    L --> I

    style K fill:#4caf50,stroke:#333,color:#fff
    style L fill:#ff9800,stroke:#333,color:#fff
```

---

## 四、认证配置

Claude Code支持多种认证方式，选择最适合你的那一种：

### 4.1 方式一：Claude Max订阅（推荐个人用户）

如果你有Claude Pro/Max订阅（即claude.ai网站会员），这是最简单的方式：

```bash
claude
```

首次运行会自动弹出浏览器OAuth登录页面。登录你的Claude账号后，终端会自动获取认证令牌。

**Max计划的使用额度**：
- Pro计划：有一定的月度使用限制
- Max计划（$100/月或$200/月）：更高的使用额度

### 4.2 方式二：API Key（适合开发者）

如果你使用Anthropic API按量付费：

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

建议将这行加入你的shell配置文件：

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

获取API Key的步骤：
1. 访问 [console.anthropic.com](https://console.anthropic.com)
2. 注册/登录Anthropic开发者账户
3. 进入 Settings → API Keys
4. 点击 Create Key，复制保存

### 4.3 方式三：企业级认证

企业用户可能使用以下方式：
- **Azure OpenAI**：配置Azure端点和凭据
- **Amazon Bedrock**：使用AWS认证
- **企业SSO**：通过组织管理员配置

### 4.4 验证认证

```bash
claude
```

如果认证成功，你会看到Claude Code的交互式提示符：

```
╭──────────────────────────────────────╮
│  >  Welcome to Claude Code!          │
│                                      │
╰──────────────────────────────────────╯
```

此时可以输入你的第一条消息试试：

```
> 你好，请介绍一下你自己
```

---

## 五、IDE集成（可选但强烈推荐）

虽然终端CLI是Claude Code的核心，但在IDE中使用体验更佳——能直接看到代码差异的视觉对比、一键接受/拒绝修改。

### 5.1 VS Code集成

```bash
# 从VS Code扩展市场安装
code --install-extension anthropic.claude-code
```

或在VS Code中：
1. 打开扩展面板（Cmd+Shift+X / Ctrl+Shift+X）
2. 搜索 "Claude Code"
3. 点击 Install

安装后，侧边栏会出现Claude Code图标，点击即可在IDE内使用。主要快捷键：

| 快捷键 | 功能 |
|--------|------|
| `Cmd+Shift+C` | 打开Claude Code面板 |
| `Tab` | 接受当前代码建议 |
| `Esc` | 拒绝当前代码建议 |
| `Cmd+Shift+A` | 在当前文件中启动Claude |

### 5.2 JetBrains集成

1. 打开 Settings → Plugins → Marketplace
2. 搜索 "Claude Code"
3. 点击 Install
4. 重启IDE后，底部会出现Claude Code工具窗口

### 5.3 Desktop App

如果你不习惯终端，可以下载Claude Code桌面应用：
- 访问 claude.ai/download
- 下载对应平台安装包
- 图形界面操作，功能与CLI一致

```mermaid
graph TB
    subgraph "IDE集成对比"
        direction LR
        A["终端 CLI<br/>✅ 完整功能<br/>✅ 灵活<br/>❌ 纯文本界面"]
        B["VS Code<br/>✅ 可视化Diff<br/>✅ 快捷键<br/>✅ 项目感知"]
        C["JetBrains<br/>✅ 可视化Diff<br/>✅ 项目感知<br/>✅ 深度集成"]
        D["Desktop App<br/>✅ 图形界面<br/>✅ 无需终端<br/>✅ 适合非开发者"]
    end

    style A fill:#4caf50,stroke:#333,color:#fff
    style B fill:#2196f3,stroke:#333,color:#fff
    style C fill:#9c27b0,stroke:#333,color:#fff
    style D fill:#ff5722,stroke:#333,color:#fff
```

---

## 六、核心概念速览

在动手做项目之前，理解这几个核心概念：

### 6.1 CLAUDE.md——项目的"记忆文件"

CLAUDE.md是Claude Code最重要的配置文件。它像一个README，告诉AI关于你项目的一切：

```markdown
# 项目：我的博客系统

## 技术栈
- 前端：React + TypeScript
- 后端：Node.js + Express
- 数据库：PostgreSQL

## 规范
- 使用中文注释
- 代码风格遵循 ESLint 配置
- 测试框架使用 Jest
- API 使用 RESTful 风格

## 目录结构
- src/components/ - React组件
- src/api/ - API路由
- src/models/ - 数据模型
```

CLAUDE.md有三个层级：

| 层级 | 位置 | 作用 |
|------|------|------|
| 全局 | `~/.claude/CLAUDE.md` | 所有项目共享的偏好 |
| 项目 | `项目根目录/CLAUDE.md` | 当前项目的规则和上下文 |
| 子目录 | `src/CLAUDE.md` | 子目录级别的特定规则 |

### 6.2 权限系统

Claude Code有严格的权限控制。首次在某个目录运行时，它会请求你确认：

```
⚠️  Claude Code wants to read files in /home/user/my-project
    Allow? [y/n]
```

你可以通过以下方式管理权限：

```bash
# 查看当前权限设置
/permissions

# 信任某个目录（不再每次询问）
/trust
```

### 6.3 Plan模式与Act模式

| 模式 | 说明 | 何时使用 |
|------|------|----------|
| **Act模式**（默认） | Claude直接执行操作 | 明确知道要做什么时 |
| **Plan模式** | Claude先分析、规划，等你确认后再执行 | 复杂任务、不确定方案时 |

切换方式：在对话中输入 `/plan` 进入Plan模式，再输入 `/plan` 退出回到Act模式。

---

## 七、实战项目：创建一个Markdown笔记管理CLI工具

现在，让我们从零开始，用Claude Code创建一个完整的Node.js CLI项目。

### 7.1 项目初始化

```bash
# 创建项目目录
mkdir md-notes && cd md-notes

# 启动Claude Code
claude
```

### 7.2 第一次对话——创建CLAUDE.md

```
> 帮我在当前目录创建一个CLAUDE.md文件，描述以下项目：
> - 项目名称：md-notes
> - 用途：一个命令行Markdown笔记管理工具
> - 技术栈：Node.js + TypeScript
> - 功能：创建笔记、列出笔记、搜索笔记、删除笔记
> - 所有笔记存储在 ~/.md-notes/ 目录下
> - 代码注释用中文
```

Claude Code会自动分析当前目录结构（此时是空的），然后创建CLAUDE.md。

### 7.3 创建项目结构

继续在对话中说：

```
> 根据CLAUDE.md中的描述，初始化这个Node.js + TypeScript项目。
> 包括：package.json、tsconfig.json、src目录结构和基本入口文件。
> 不要安装依赖，先创建文件结构。
```

Claude Code会执行类似以下操作（你可能需要逐个确认权限）：

```
创建文件：package.json
创建文件：tsconfig.json
创建目录：src/
创建文件：src/index.ts
创建文件：src/commands/
创建文件：src/utils/
```

### 7.4 实现核心功能

```
> 现在实现所有功能：创建笔记、列出笔记、搜索笔记、删除笔记。
> 每个命令一个文件，放在 src/commands/ 下。
> 主入口 src/index.ts 负责解析命令行参数并路由到对应命令。
> 使用 chalk 库给输出加颜色，使用 commander 库处理命令行参数。
> 先安装依赖，然后实现所有代码。
```

Claude Code会：
1. 运行 `npm install commander chalk @types/node` 等命令
2. 逐个创建和编写源文件
3. 确保TypeScript类型正确

### 7.5 完整交互记录（预期结果）

以下是你可能在终端中看到的完整流程：

```bash
$ mkdir md-notes && cd md-notes
$ claude

╭──────────────────────────────────────╮
│  >  Welcome to Claude Code!          │
╰──────────────────────────────────────╯

> 帮我创建一个Node.js CLI工具，用于管理Markdown笔记

Claude Code 正在分析当前目录...
✗ 当前目录为空

我将创建一个完整的CLI工具项目。让我开始：

1. 创建 package.json
   ✓ package.json 已创建

2. 创建 tsconfig.json
   ✓ tsconfig.json 已创建

3. 安装依赖
   $ npm install commander chalk
   $ npm install -D typescript @types/node ts-node
   ✓ 依赖安装完成

4. 创建源代码结构
   ✓ src/index.ts
   ✓ src/commands/create.ts
   ✓ src/commands/list.ts
   ✓ srccommands/search.ts
   ✓ src/commands/delete.ts

5. 更新 package.json 的 bin 字段
   ✓ package.json 已更新

项目创建完成！你可以通过以下命令测试：
  npx ts-node src/index.ts create "我的第一篇笔记"
  npx ts-node src/index.ts list
  npx ts-node src/index.ts search "关键词"
  npx ts-node src/index.ts delete "笔记标题"
```

### 7.6 测试项目

让Claude Code帮你测试：

```
> 帮我测试一下所有功能是否正常工作。
> 创建几篇示例笔记，然后测试列表、搜索和删除。
```

Claude Code会自动执行测试命令并报告结果。你也可以手动测试：

```bash
# 编译TypeScript
npx tsc

# 创建笔记
node dist/index.js create "学习笔记" --content "今天学习了Claude Code"

# 列出所有笔记
node dist/index.js list

# 搜索笔记
node dist/index.js search "Claude"

# 删除笔记
node dist/index.js delete "学习笔记"
```

### 7.7 项目最终结构

```
md-notes/
├── CLAUDE.md          # 项目上下文描述
├── package.json       # 项目配置
├── tsconfig.json      # TypeScript配置
├── src/
│   ├── index.ts       # 主入口，命令路由
│   └── commands/
│       ├── create.ts  # 创建笔记
│       ├── list.ts    # 列出笔记
│       ├── search.ts  # 搜索笔记
│       └── delete.ts  # 删除笔记
└── dist/              # 编译输出（gitignore）
```

```mermaid
flowchart TD
    A[用户输入命令] --> B[commander 解析]
    B --> C{命令类型?}
    C -->|create| D[创建.md文件<br/>保存到 ~/.md-notes/]
    C -->|list| E[读取目录<br/>格式化输出列表]
    C -->|search| F[遍历文件<br/>关键词匹配]
    C -->|delete| G[确认后删除<br/>对应.md文件]

    D --> H[chalk 彩色输出结果]
    E --> H
    F --> H
    G --> H

    style A fill:#2196f3,stroke:#333,color:#fff
    style B fill:#ff9800,stroke:#333,color:#fff
    style H fill:#4caf50,stroke:#333,color:#fff
```

---

## 八、常用命令速查表

掌握以下命令，你就能高效使用Claude Code的80%功能：

### 8.1 启动与退出

| 命令 | 说明 |
|------|------|
| `claude` | 交互模式启动 |
| `claude "一次性任务"` | 非交互模式，执行单条指令后退出 |
| `claude -p "提示词"` | Pipe模式，适合脚本集成 |
| `Ctrl+C` | 中断当前操作 |
| `/exit` 或 `Ctrl+D` | 退出Claude Code |

### 8.2 会话内命令

| 命令 | 说明 |
|------|------|
| `/help` | 查看帮助信息 |
| `/clear` | 清除当前会话上下文 |
| `/compact` | 压缩上下文（节省token） |
| `/plan` | 切换Plan/Act模式 |
| `/permissions` | 查看/管理权限 |
| `/trust` | 信任当前目录 |
| `/cost` | 查看本次会话token消耗 |
| `/undo` | 撤销上一次修改 |

### 8.3 外部集成命令

| 命令 | 说明 |
|------|------|
| `/mcp` | 管理MCP服务器连接 |
| `/skills` | 查看可用Skills |
| `/review` | 代码审查模式 |

---

## 九、常见问题与排查

### Q1：安装后 `claude` 命令找不到

```bash
# 检查安装路径
ls ~/.claude/local/bin/

# 手动添加PATH
echo 'export PATH="$HOME/.claude/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

### Q2：认证失败或超时

```bash
# 重新登录
claude auth login

# 检查认证状态
claude auth status

# 使用API Key方式
export ANTHROPIC_API_KEY="your-key-here"
```

### Q3：权限弹窗太频繁

```bash
# 在项目目录下信任当前目录
claude
> /trust

# 或手动编辑 settings.json
# 路径：~/.claude/settings.json
{
  "trustedDirectories": ["/home/user/my-project"]
}
```

### Q4：Claude Code修改了不想改的文件

Claude Code每次修改文件前都会显示差异（diff），你有权拒绝。如果已经修改：

```
> /undo
```

或者使用Git回滚：

```bash
git checkout -- 被修改的文件
```

> **强烈建议**：每次用Claude Code工作前确保项目在Git管理下。这样任何修改都可以轻松回退。

### Q5：国内网络环境无法连接

如果你在中国大陆使用，可能需要：
1. 配置代理：`export HTTPS_PROXY=http://127.0.0.1:7890`
2. 或使用API Key方式配合第三方中转服务
3. 或使用国内模型服务商提供的兼容接口

### Q6：Token消耗过快

```
> /compact    # 压缩当前上下文
> /clear      # 完全清除上下文重新开始
> /cost       # 查看当前消耗
```

在CLAUDE.md中加入简洁的项目描述可以减少每次会话的上下文消耗。

---

## 十、最佳实践总结

### 10.1 项目准备

1. **始终使用Git**：`git init` 应该是你进入项目后的第一个动作
2. **编写CLAUDE.md**：好的CLAUDE.md = 高质量的AI协作
3. **分步指导**：不要一次性给出巨大需求，拆分成小步骤

### 10.2 高效对话

```
❌ 差：帮我做一个完整的电商系统
✅ 好：先创建用户注册的API接口，使用Express + TypeScript

❌ 差：修bug
✅ 好：运行测试发现 src/auth.ts:42 抛出 TypeError，帮我修复
```

### 10.3 安全习惯

- 不要让Claude Code处理 `.env` 文件中的敏感信息
- 在CLAUDE.md中明确标注哪些文件不应修改
- 定期使用 `/permissions` 检查权限设置
- 企业项目建议配置 `allowedTools` 白名单

```mermaid
flowchart TD
    A[开始使用Claude Code] --> B[安装与认证]
    B --> C[创建项目目录]
    C --> D[git init]
    D --> E[编写CLAUDE.md]
    E --> F[用claude初始化项目]
    F --> G[分步实现功能]
    G --> H[测试验证]
    H --> I{通过?}
    I -->|是| J[git commit]
    I -->|否| K[描述问题让AI修复]
    K --> H
    J --> L[继续下一个功能]
    L --> G

    style A fill:#2196f3,stroke:#333,color:#fff
    style J fill:#4caf50,stroke:#333,color:#fff
    style K fill:#ff9800,stroke:#333,color:#fff
```

---

## 延伸阅读

- [Claude Code官方快速入门](https://code.claude.com/docs/en/quickstart) — Anthropic官方文档，最权威的入门指南
- [Claude Code终端指南（面向新用户）](https://code.claude.com/docs/en/terminal-guide) — 零终端经验用户的逐步教程
- [CLAUDE.md最佳实践](https://code.claude.com/docs/en/best-practices) — 官方推荐的项目配置方式
- [Claude Code权限配置](https://code.claude.com/docs/en/permissions) — 理解沙箱和权限管理
- [Claude Code高级安装配置](https://code.claude.com/docs/en/setup) — 多平台安装的详细说明

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | AI编程入门营、前端/后端开发训练营、全栈工程师训练营 |
| **教学时长** | 2-3小时（含实操） |
| **难度等级** | ⭐⭐（入门级） |
| **前置要求** | 基本终端操作能力、任意编程语言基础 |
| **硬件要求** | 任意开发机（Mac/Linux/Windows均可） |
| **推荐课时安排** | 安装配置45分钟 + 概念讲解30分钟 + 实战项目75分钟 + Q&A 30分钟 |

---

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic官方Claude Code快速入门指南
2. [Terminal Guide for New Users - Claude Code Docs](https://code.claude.com/docs/en/terminal-guide) — 面向终端新用户的逐步安装教程
3. [Advanced Setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 系统要求、多平台安装与版本管理
4. [Claude Code Tutorial for Beginners (2026)](https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma) — 从安装到首个项目的完整教程
5. [Claude Code Complete Guide to Installation and Getting Started](https://neurohive.io/en/guides/claude-code-getting-started-guide/) — 涵盖CLI、Desktop App和核心命令的入门指南

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