<!-- title: Claude Code入门：安装配置到第一个项目 -->

# Claude Code 入门教程：从安装到完成第一个项目

## 概述

本教程面向零基础读者，带你完成 Claude Code 的安装、账号登录、项目初始化与首个开发任务。你将学会核心交互方式（交互模式、斜杠命令、CLAUDE.md 记忆文件），并独立完成一个可运行的 TODO 命令行应用。全程约 60 分钟，无需任何 AI 编程工具使用经验。

## 前置条件

| 项目 | 要求 | 检查命令 |
| --- | --- | --- |
| 操作系统 | macOS / Linux / Windows（原生或 WSL） | — |
| Node.js | 18 或更高版本 | `node --version` |
| 终端 | 任意终端或命令提示符 | — |
| 账号 | Claude.ai 订阅账号（推荐）或 Anthropic Console 账号 | — |

如果 Node.js 未安装，访问 https://nodejs.org 下载 LTS 版本，或使用版本管理器：

```bash
# 使用 nvm 安装 Node.js（Linux/macOS）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts
node --version   # 应输出 v18.x 或更高
```

## 第一步：安装 Claude Code

Claude Code 提供两种安装方式，任选其一。

### 方式一：NPM 安装（已有 Node.js 环境）

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

### 方式二：原生安装（推荐，不依赖 Node）

```bash
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
```

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

安装完成后验证：

```bash
claude --version
# 预期输出：2.x.x（版本号随更新变化）
```

**常见问题 1：`npm install -g` 报权限错误（EACCES）**

不要使用 `sudo`，修复 npm 全局目录权限或改用原生安装方式：

```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
```

**常见问题 2：`claude` 命令找不到**

PATH 未包含 npm 全局 bin 目录。执行 `npm config get prefix` 找到路径，将 `<prefix>/bin` 加入 PATH 后重新打开终端。

**常见问题 3：企业网络下安装超时**

设置镜像或代理：

```bash
npm config set registry https://registry.npmmirror.com
```

## 第二步：登录账号

在任意目录启动：

```bash
claude
```

首次启动会进入浏览器完成 OAuth 登录，两种账号均可：

- **Claude.ai 账号**（推荐）：Pro/Max 订阅直接使用，无需单独付费 API
- **Anthropic Console 账号**：预充值 API 额度，按 token 计费

登录成功后凭据存储在本地，之后无需重复登录。如果在会话中需要切换账号，使用 `/login` 命令。

**常见问题：浏览器无法打开（远程 SSH 服务器场景）**

启动时按住提示复制认证 URL，在本地浏览器打开完成授权后，把回调码粘贴回终端即可。

## 第三步：认识交互界面

登录后你会看到：

```
✻ Welcome to Claude Code!

...

> Try "create a util logging.py that..."
```

底部以 `>` 开头的输入框就是你的对话入口。先记住几个保命快捷键：

| 按键/命令 | 作用 |
| --- | --- |
| `Esc` | 立即中断 Claude 当前操作（上下文保留） |
| `Esc` 连按两次 或 `/rewind` | 打开回滚菜单，恢复到之前的代码/对话状态 |
| `Ctrl+C` | 退出程序 |
| `/clear` | 清空对话历史，重置上下文 |
| `/help` | 查看所有可用命令 |

Claude Code 的每一个动作都在你的监督之下：它要**读文件、写文件、执行命令**前都会弹出确认框，你可以选择允许一次、允许本会话或拒绝。新手阶段建议逐条审阅，熟悉后再放开权限。

## 第四步：创建第一个项目并启动

创建一个空的 Node.js 项目作为练习场：

```bash
mkdir todo-app && cd todo-app
npm init -y
git init
claude
```

进入会话后，第一个任务建议是**了解项目**而不是写代码：

```
> 这个项目当前是什么结构？帮我初始化一个规范的 package.json
```

Claude 会读取目录内容、给出分析，然后提议修改并等待你确认。你也可以用内置命令一键生成项目记忆文件：

```
> /init
```

`/init` 会分析代码库的构建系统、测试框架和代码风格，生成一份 `CLAUDE.md`。这个文件会在**每次会话启动时自动加载**，相当于给 Claude 的工作交接文档。

## 第五步：理解 CLAUDE.md——让 Claude 记住你的规则

CLAUDE.md 是 Claude Code 最重要的配置文件，有四个层级，由高到低：

```mermaid
flowchart TD
    A["企业策略<br/>/etc/claude-code/CLAUDE.md<br/>IT 统一下发"] --> B["用户全局<br/>~/.claude/CLAUDE.md<br/>个人所有项目生效"]
    B --> C["项目共享<br/>./CLAUDE.md<br/>提交到 Git 团队共享"]
    C --> D["项目本地<br/>./CLAUDE.local.md<br/>个人笔记不入库"]
    style A fill:#e8eaf6
    style B fill:#c5cae9
    style C fill:#9fa8da
    style D fill:#7986cb
```

在项目根目录手动创建一个简洁的 `CLAUDE.md`：

```markdown
# 项目约定

## 命令
- 运行测试：npm test
- 启动开发：node index.js

## 代码风格
- 使用 ES modules（import/export），不用 CommonJS
- 所有函数必须有 JSDoc 注释

## 工作流
- 完成代码修改后必须运行 npm test 验证
- 不要自动 git commit，先给我看改动
```

写 CLAUDE.md 的三条黄金法则：

1. **写 Claude 猜不到的东西**——构建命令、特殊环境变量、团队规范；它读代码就能知道的不要写
2. **保持简短**——臃肿的文件会导致 Claude 忽略真正的规则，每一行都问自己“删掉这行会出错的吗”
3. **定期修剪**——把它当代码维护，行为不对时先检查这个文件

还有一个即时技巧：在输入框中以 `#` 开头输入一句话，Claude 会问你要存入哪个记忆文件，这是积累项目规则最快的方式。

## 第六步：完成第一个开发任务

现在让 Claude 真正写代码。输入：

```
> 创建一个 TODO 命令行应用：
> 1. 用 index.js 实现添加、列出、完成三个命令
> 2. 数据存储在 todos.json
> 3. 附带完整的测试文件，写完后运行测试验证
```

Claude Code 的工作循环如下：

```mermaid
flowchart LR
    A[理解任务] --> B[探索现有代码]
    B --> C[提出修改方案]
    C --> D{用户确认?}
    D -- 允许 --> E[执行编辑/命令]
    D -- 拒绝 --> C
    E --> F[运行测试验证]
    F -- 失败 --> B
    F -- 通过 --> G[汇报结果]
    G --> H[等待下一个任务]
    style F fill:#c8e6c9
```

**预期结果**：你会依次看到它创建 `index.js`、`todos.json`、`test/todo.test.js`，每次写文件前弹出确认框；最后自动执行 `npm test`，终端输出全部通过的测试结果。这就是 Claude Code 与普通聊天机器人的本质区别——**它给 Claude 一个可运行的验证手段，失败就自己迭代直到通过**。

**常见问题 1：生成的代码不符合我的习惯**

中途按 `Esc` 打断，说“改用 async/await 重新实现”。纠正同一问题超过两次时，更好的做法是 `/clear` 清空重来，把你的要求写得更具体，或沉淀到 CLAUDE.md。

**常见问题 2：它改错了文件，我想撤销**

连按两次 `Esc` 打开 rewind 菜单，可以单独恢复代码、单独恢复对话，或两者都恢复。Claude 在每次修改前都会自动创建检查点。

**常见问题 3：会话变长了，回答质量下降**

上下文（context window）是有限资源，塞满了文件内容和命令输出后性能会退化。处理无关任务前先 `/clear`；想在保留要点的同时释放空间，用 `/compact 保留 API 变更相关内容` 定向压缩。

## 第七步：日常高频命令速查

| 命令 | 用途 | 示例 |
| --- | --- | --- |
| `claude` | 启动交互会话 | `claude` |
| `claude "任务"` | 启动并直接给任务 | `claude "修复构建错误"` |
| `claude -p "问题"` | 非交互执行后退出，适合脚本 | `claude -p "解释这个函数"` |
| `claude -c` | 继续最近一次对话 | `claude -c` |
| `claude -r` | 从历史会话列表中选择恢复 | `claude -r` |
| `claude commit` | 生成描述性 Git 提交 | `claude commit` |
| `claude update` | 升级到最新版本 | `claude update` |
| `/permissions` | 管理工具权限白名单 | 会话内输入 |

两个实用组合：

```bash
# 管道输入：把日志喂给 Claude 分析
cat error.log | claude -p "找出异常并给出修复建议"

# 指定输出格式，便于程序解析
claude -p "列出所有API端点" --output-format json
```

## 实战案例：从零到可运行的 TODO 应用

以下是完整的项目产物，你可以直接对照检查 Claude 的输出（也适合手工搭建后让 Claude 增强功能）。

**index.js**：

```javascript
#!/usr/bin/env node
import fs from 'fs';
import { Command } from 'commander';

const program = new Command();
const DB_FILE = './todos.json';

function loadTodos() {
  try {
    return JSON.parse(fs.readFileSync(DB_FILE, 'utf-8'));
  } catch {
    return [];
  }
}

function saveTodos(todos) {
  fs.writeFileSync(DB_FILE, JSON.stringify(todos, null, 2));
}

program.command('add <text...>')
  .description('添加一条待办')
  .action((text) => {
    const todos = loadTodos();
    todos.push({ id: Date.now(), text: text.join(' '), done: false });
    saveTodos(todos);
    console.log(`已添加: ${text.join(' ')}`);
  });

program.command('list')
  .description('列出全部待办')
  .action(() => {
    const todos = loadTodos();
    if (!todos.length) return console.log('暂无待办');
    todos.forEach(t =>
      console.log(`${t.done ? '[x]' : '[ ]'} #${t.id} ${t.text}`));
  });

program.command('done <id>')
  .description('标记完成')
  .action((id) => {
    const todos = loadTodos();
    const todo = todos.find(t => t.id === Number(id));
    if (!todo) return console.log('未找到该条目');
    todo.done = true;
    saveTodos(todos);
    console.log(`已完成: ${todo.text}`);
  });

program.parse();
```

**test/todo.test.js**（使用 Node 内置测试器，零依赖）：

```javascript
import { test } from 'node:test';
import assert from 'node:assert';
import { execSync } from 'node:child_process';

const run = (args) =>
  execSync(`node index.js ${args}`, { encoding: 'utf-8' });

test('添加并列表显示', () => {
  run('add "写周报"');
  const out = run('list');
  assert.match(out, /\[ \].*写周报/);
});

test('标记完成后状态更新', () => {
  run('add "买菜"');
  const list = run('list');
  const id = list.match(/#(\d+) 买菜/)[1];
  run(`done ${id}`);
  assert.match(run('list'), /\[x\].*买菜/);
});
```

在 package.json 中加入 `"test": "node --test"` 后运行 `npm test`，两个测试全部通过即完成。整个过程只需要一条自然语言指令，Claude 独立完成了文件创建、依赖选择和测试验证。

## 延伸阅读

- 下一篇进阶：Claude Code Skills 开发实战——把重复工作流封装成 `/命令`
- Anthropic 工程博客《Claude Code Best Practices》——本文多篇技巧的出处
- MCP（Model Context Protocol）——让 Claude 连接数据库、Figma、Jira 等外部工具

## 训练营适用性评估

- **适用类型**：AI 辅助编程训练营、开发者效率提升工作坊、新员工 onboarding；零基础学员的第一课
- **预计教学时长**：线下集中教学 2.5～3 小时（安装 20 分钟 + 核心概念 40 分钟 + 实战 90 分钟 + 答疑）；自学约 1.5 小时
- **配套练习建议**：让学员用本教程流程改写一个"书签管理 CLI"，检验是否掌握“任务描述 → 审阅确认 → 测试验证”的闭环
- **教学风险提示**：现场最常见卡点是 npm 网络问题与账号登录，建议课前发预装脚本；免费额度不足的学员提前准备 Console 充值方案

## 参考来源

1. [Claude Code overview - Anthropic Docs](https://docs.anthropic.com/en/docs/claude-code/overview) — 安装前提、30 秒快速上手、功能定位的官方说明
2. [Quickstart - Anthropic Docs](https://docs.anthropic.com/en/docs/claude-code/quickstart) — 本文分步教学结构的官方蓝本，含安装、登录、首批任务示例
3. [Manage Claude's memory - Anthropic Docs](https://docs.anthropic.com/en/docs/claude-code/memory) — CLAUDE.md 四层级结构与 `#` 快捷记忆机制
4. [Best practices for Claude Code - Anthropic Engineering](https://www.anthropic.com/engineering/claude-code-best-practices) — CLAUDE.md 编写黄金法则、验证循环与上下文管理策略
5. [CLI reference - Anthropic Docs](https://docs.anthropic.com/en/docs/claude-code/cli-reference) — 命令行参数与 `-p` 非交互模式完整定义

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