<!-- title: Claude Code入门：从环境自检到首个功能 -->

# Claude Code 入门：从环境自检到首个功能落地

## 概述

本教程面向完全零基础的开发者，目标是让你在一小时内完成 Claude Code 的环境检查、安装、认证，并端到端交付一个真实可运行的命令行小工具。学完后你能独立判断本机环境是否达标、选择正确的安装与认证方式、跑通 `/doctor` 自检，并理解 `settings.json` 与 `.claude` 目录的组织方式。全程不依赖任何框架，跟着敲命令即可。

## 前置条件

在动手之前，请确认你具备以下条件，缺一不可：

- **操作系统**：macOS 12+、主流 Linux 发行版（Ubuntu 20.04+ / Debian / Arch 等），或 Windows 10/11（必须通过 WSL2 运行，原生 cmd/PowerShell 暂不是一等公民）。
- **Node.js**：18 及以上版本，推荐 20 LTS。Claude Code 是用 Node 编写的 CLI，没有 Node 跑不起来。
- **终端基础**：会用 `cd` 切目录、`ls` 看文件、`mkdir` 建目录。不需要会写 shell 脚本。
- **账号**：一个 Anthropic 账号。两条路径二选一——① 已订阅 **Claude Pro / Max** 套餐；② 或拥有 **Anthropic API key**（控制台 console.anthropic.com 申请，需充值余额）。
- **网络**：能访问 `api.anthropic.com` 与 `claude.ai`。若你在受限网络环境，需要预先配置 HTTP(S) 代理（后文会讲）。

如果你对上述任何一项不确定，本教程的第一步就是教你怎么逐项排查。

---

## 第一步：环境自检（别跳过这一步）

绝大多数"装不上、跑不起来"的问题，根因都在环境。花三分钟自查，能省后面三小时的排查。

### 1.1 检查 Node 版本

打开终端，执行：

```bash
node --version
```

**预期结果**：输出形如 `v20.11.0` 或 `v18.19.0`。

**常见问题**：
- 提示 `command not found` → 没装 Node。用 [fnm](https://github.com/Schniz/fnm)（推荐，快且跨平台）安装：

  ```bash
  curl -fsSL https://fnm.vercel.app/install | bash
  exec $SHELL
  fnm install 20
  fnm use 20
  ```

- 版本低于 18（如 `v16.x`）→ Claude Code 拒绝启动。执行 `fnm install 20 && fnm use 20` 升级。

### 1.2 检查 npm 全局目录权限

```bash
npm config get prefix
```

如果输出指向 `/usr/local` 或 `/usr`，说明你用的是系统 Node，`npm install -g` 会要求 `sudo`，后续极容易踩"权限拒绝"的坑。建议把全局前缀改到你的家目录：

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

### 1.3 检查网络与代理

执行一次连通性测试：

```bash
curl -sS -o /dev/null -w "%{http_code}\n" https://api.anthropic.com
```

**预期结果**：返回 `401`（未授权但能连通）或 `404`，只要不是超时即代表网络通。

**常见问题**：长时间无响应或报 `Could not resolve host` → 你处于受限网络。配置代理环境变量：

```bash
export HTTPS_PROXY=http://127.0.0.1:7890   # 改成你本机代理端口
export HTTP_PROXY=http://127.0.0.1:7890
```

把这两行追加到 `~/.bashrc` 持久化。Claude Code 会读取 `HTTPS_PROXY` 走代理。

> **小提示**：代理端口因工具而异（Clash 默认 7890、V2Ray 常见 10809）。确认端口的方法：打开你的代理客户端，查看"本地监听端口"。

---

## 第二步：安装 Claude Code

Claude Code 提供两种官方安装方式。新手用 npm，老手或离线机器用原生安装包。

### 方式 A：npm 全局安装（推荐）

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

**预期结果**：末尾出现 `added X packages`，无 `npm ERR!`。

**验证安装**：

```bash
claude --version
```

看到版本号（如 `1.0.x`）即安装成功。

**常见问题**：
- `EACCES: permission denied` → 回到 1.2 修复全局目录权限，或临时加 `sudo`（不推荐，长期会有麻烦）。
- 安装卡住 → 多半是 npm 源问题，临时换源：`npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com`。

### 方式 B：原生安装（零 Node 依赖）

适合不想装 Node、或在隔离服务器上部署的场景。macOS / Linux 一行命令：

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

Windows PowerShell（不需要 WSL 的轻量场景）：

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

**预期结果**：脚本下载预编译二进制到 `~/.local/bin/claude`（或 `$HOME/.claude/local`），并尝试加入 PATH。

**常见问题**：
- 装完执行 `claude` 提示 `command not found` → 二进制所在目录不在 PATH。把 `~/.local/bin` 加入 PATH：`echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc && source ~/.bashrc`。

### 方式 C：IDE 插件（VS Code / JetBrains）

在 VS Code 扩展市场搜索 "Claude Code" 安装，或在 JetBrains 插件仓库搜索安装。插件本质上是调用本地 `claude` 二进制，所以**仍需先用方式 A 或 B 装好 CLI**。本教程以终端为主，IDE 插件留作后续探索。

---

## 第三步：首次认证

认证决定 Claude Code 用哪个账号的额度。两种方式，按你的订阅情况二选一。

### 路径 ①：Pro / Max 订阅登录（最省心）

如果你已经付费订阅了 Claude Pro 或 Max，直接：

```bash
claude
```

首次启动会提示你按回车打开浏览器，完成 OAuth 授权后回到终端，看到欢迎界面即登录成功。

验证登录状态：

```bash
# 在 Claude Code 交互界面内输入
/status
```

**预期结果**：显示你的账号邮箱、订阅类型、当前会话模型、剩余额度上下文窗口等信息。

### 路径 ②：API Key 方式（适合企业 / 无订阅用户）

去 console.anthropic.com → Settings → API Keys → Create Key，复制以 `sk-ant-` 开头的密钥。然后：

```bash
export ANTHROPIC_API_KEY=sk-ant-xxxxxx你的密钥xxxxxx
```

为避免每次开终端都要 export，写入 shell 配置：

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

> **安全提醒**：切勿把 API Key 提交进 git、写进项目里的 `.env` 并推到公开仓库。一旦泄露立刻在控制台吊销重建。

**常见问题**：
- 浏览器授权页打不开（无图形界面服务器）→ 用 API Key 方式，或在本地浏览器授权后复制粘贴终端提示的授权码。
- `401 Unauthorized` → Key 输错或已过期；订阅用户检查是否还在订阅期内。

---

## 第四步：环境诊断 /doctor

Claude Code 内置了体检命令，强烈建议装完先跑一次：

在交互界面内输入：

```
/doctor
```

它会逐项检查：Node 版本、CLI 版本、OS 兼容性、网络连通性、认证状态、git 是否可用、权限配置是否健康。每项给出 ✓ 或 ✗ 与修复建议。

**预期结果**：全部 ✓，显示 "Your Claude Code setup looks healthy!"。

**常见问题**：
- 网络项 ✗ → 回到第一步 1.3 配代理。
- 认证项 ✗ → 回到第三步重新登录或重新设置 API Key。
- git 项 ✗ → 安装 git：`sudo apt install git`（Debian/Ubuntu）或 `brew install git`（macOS）。

---

## 第五步：第一个项目实战——待办命令行工具

现在环境齐活，我们来用 Claude Code 端到端做一个真实项目：一个 Node.js 写的命令行待办工具 `todo`，支持 `add` / `list` / `done` 三个子命令，数据存在本地 JSON 文件，最后加上单元测试。整个过程我们只说需求，代码交给 Claude Code。

### 5.1 建项目并进入

```bash
mkdir ~/my-todo && cd ~/my-todo
git init                          # Claude Code 强依赖 git，务必初始化
claude                            # 启动交互界面
```

> 为什么强调 `git init`？Claude Code 大量功能（差异查看、回滚、安全护栏）都建立在 git 之上。没有 git 仓库，它的能力会大打折扣。

### 5.2 第一次提需求

在交互界面里直接输入这段话（不用学任何特殊语法，自然语言即可）：

```
帮我用 Node.js 做一个命令行待办工具。
要求：
1. 单文件 todo.js，用 #!/usr/bin/env node 作为 shebang。
2. 子命令：todo add "内容" 添加任务；todo list 刓出所有任务；todo done <序号> 标记完成。
3. 数据存在同目录 .todos.json 文件里，没有就自动创建。
4. 不要用任何第三方依赖，只用 Node 内置模块。
5. 每个任务有 id、text、done 三个字段。
```

按回车，观察 Claude Code 的行为：它会先用工具读取目录、查看是否已有文件，然后写出 `todo.js`，并解释每段代码。完成后会在终端显示创建的文件与改动。

**预期结果**：项目目录下出现 `todo.js`。Claude Code 通常还会顺手把它标记为可执行 `chmod +x`。

### 5.3 运行验证

暂时退出交互界面（Ctrl+C 两次，或输入 `/exit`），在普通 shell 测试：

```bash
node todo.js add "读完 Claude Code 入门教程"
node todo.js add "用 Claude Code 做第一个项目"
node todo.js list
node todo.js done 1
node todo.js list
```

**预期结果**：`list` 先显示两条未完成任务；`done 1` 后再次 `list`，第一条被标记为 `[x]` 完成，并能看到 `.todos.json` 文件被创建。

### 5.4 回去修 bug / 加功能

回到 Claude Code（再次 `claude`），用 `@` 引用文件来精确定位上下文：

```
看一下 @todo.js，现在 list 是按插入顺序显示的。帮我改成：未完成的排前面，已完成的排后面；并且每行前面显示序号。
```

Claude Code 会读取 `todo.js`，定位到 list 相关逻辑，给出修改。

### 5.5 加单元测试

```
给 @todo.js 加单元测试，用 Node 内置的 node:test 和 node:assert，不要引入 jest。把测试逻辑抽到一个可测的纯函数模块里（比如把任务管理逻辑放到单独文件），保证测试不依赖文件系统副作用。
```

**预期结果**：Claude Code 会建议把核心逻辑（增删改查）重构为一个纯函数模块，再写测试文件。然后它会主动提示你运行：

```bash
node --test
```

看到 `tests N passed (N)` 即测试全绿。

> 这一步体现了 Claude Code 的一个关键习惯：**让它自己运行验证**。修改代码后，如果有测试命令，它会主动跑测试并把结果反馈进上下文，形成"改→测→改"的闭环，而不是让你手动验证。

---

## 第六步：理解 settings.json 与 .claude 目录

跑通项目后，了解配置体系能让你后续用得更顺。Claude Code 的配置分三个层级，优先级从高到低：

| 层级 | 路径 | 用途 |
|------|------|------|
| 企业级 | `/Library/Application Support/ClaudeCode/managed-settings.json`（macOS）等 | 公司统一下发的强制策略 |
| 用户级 | `~/.claude/settings.json` | 你的个人全局偏好 |
| 项目级 | `<项目>/.claude/settings.json` | 随仓库提交、团队共享 |
| 本地级 | `<项目>/.claude/settings.local.json` | 个人覆盖，应加入 `.gitignore` |

一个典型的用户级 `~/.claude/settings.json` 长这样：

```json
{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(node --test)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl:*)"
    ]
  },
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:7890"
  }
}
```

- `model`：默认模型。
- `permissions.allow`：**预授权**这些命令，执行时不再每次弹窗确认——这是减少打断、提升流畅度的核心配置。
- `permissions.deny`：硬禁止，任何情况都不许执行。
- `env`：注入环境变量（如代理）。

此外还有两个重要文件：
- **`CLAUDE.md`**：项目级的"长期记忆"，写在仓库根目录。里面记录项目约定、技术栈、命令、注意事项。Claude Code 每次启动会自动读入。本教程第一个项目里，你可以让它执行 `/init` 自动生成一份 `CLAUDE.md`。
- **`~/.claude/CLAUDE.md`**：你的全局个人记忆，所有项目共享。

在交互界面输入 `/init`，Claude Code 会扫描项目并起草一份 `CLAUDE.md`，你确认后它就落盘。

---

## 第七步：常用斜杠命令速查

掌握这几个，日常就够用了：

| 命令 | 作用 |
|------|------|
| `/help` | 查看所有命令 |
| `/status` | 查看账号、模型、额度 |
| `/doctor` | 环境自检 |
| `/config` | 打开/编辑配置 |
| `/clear` | 清空当前会话上下文（换任务前必用，省 Token） |
| `/compact` | 压缩上下文（会话太长时用，保留要点） |
| `/cost` | 查看本次会话 Token 消耗 |
| `/init` | 为当前项目生成 CLAUDE.md |
| `/login` `/logout` | 切换账号 |

还有两个非斜杠的交互技巧：
- 输入 `@` 会弹出文件选择器，引用具体文件给 Claude Code 当上下文。
- 输入 `#` 开头的一句话，会把它追加进 `CLAUDE.md` 作为长期记忆。

---

## 常见报错速查表

| 报错 | 原因 | 解决 |
|------|------|------|
| `command not found: claude` | 二进制不在 PATH | 修复 PATH（见方式 B 常见问题） |
| `EACCES permission denied` | npm 全局目录无写权限 | 见 1.2 改 prefix |
| `401 Unauthorized` | 认证失败 | 重新 `/login` 或检查 API Key |
| `ENOTFOUND api.anthropic.com` | DNS/网络不通 | 配置 `HTTPS_PROXY` |
| `Node version too old` | Node < 18 | 用 fnm 升级到 20 |
| `Overloaded` / `529` | 服务端过载 | 稍等重试，或切其他模型 |

---

## 整体上手流程图

下面这张图概括了从零到跑通第一个项目的完整路径，遇到卡点可对照定位你在哪一环：

```text
flowchart TD
    A[零基础起点] --> B{环境自检}
    B -->|Node≥18?| C1[✓ 继续]
    B -->|否| C2[fnm install 20]
    C2 --> B
    C1 --> D{npm 权限正常?}
    D -->|否| E[改全局 prefix]
    E --> D
    D -->|是| F[安装 Claude Code]
    F --> G{网络通?}
    G -->|否| H[配置 HTTPS_PROXY]
    H --> G
    G -->|是| I[首次认证]
    I --> J{Pro/Max 订阅?}
    J -->|是| K1[claude 浏览器登录]
    J -->|否| K2[设置 ANTHROPIC_API_KEY]
    K1 --> L[/doctor 体检全绿/]
    K2 --> L
    L --> M[mkdir 项目 + git init]
    M --> N[claude 启动 + 提需求]
    N --> O[Claude Code 写代码]
    O --> P[node 运行验证]
    P --> Q{符合预期?}
    Q -->|否| R[回交互界面描述问题修 bug]
    R --> P
    Q -->|是| S[/init 生成 CLAUDE.md]
    S --> T[✅ 第一个功能落地]
```

---

## 小结

走到这里，你已经完成了零基础到"能交付一个功能"的完整闭环：环境自检、安装、认证、体检、用自然语言驱动开发、运行验证、配置体系。Claude Code 的核心理念是——**你只描述意图，它负责读代码、改代码、跑测试、反馈结果**。把繁琐的机械操作交给它，把判断和决策留给自己。后续要深入，可以从斜杠命令、`CLAUDE.md` 记忆体系、`-p` 非交互自动化、Hooks、Subagent 这些方向逐个解锁。

## 延伸阅读

- **官方文档总览**：`docs.anthropic.com/en/docs/claude-code/overview` —— 所有功能的权威入口。
- **设置项完整参考**：`docs.anthropic.com/en/docs/claude-code/settings` —— `settings.json` 每个字段的含义。
- **权限模型**：`docs.anthropic.com/en/docs/claude-code/iam` —— `allow` / `deny` 规则的完整语法。
- **CLI 命令行参数**：`claude --help` —— 非交互模式的全部 flag。
- **GitHub 仓库**：`github.com/anthropics/claude-code` —— Issue、Changelog、社区讨论。

## 参考来源

1. [Anthropic Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code/overview) — 安装、配置、命令的权威说明，本文安装方式与斜杠命令的主要依据。
2. [Claude Code Settings 官方参考](https://docs.anthropic.com/en/docs/claude-code/settings) — settings.json 三级配置层级与环境变量注入规范。
3. [@anthropic-ai/claude-code — npm](https://www.npmjs.com/package/@anthropic-ai/claude-code) — npm 全局安装的官方包页面与版本信息。
4. [Anthropic 官方博客：Claude Code 发布](https://www.anthropic.com/news/claude-code) — 产品定位与设计理念。
5. [Claude Code GitHub 仓库](https://github.com/anthropics/claude-code) — 问题追踪与版本更新日志。

## 训练营适用性评估

- **适合的训练营类型**：① 零基础开发者入门营（重点）；② 企业内部 AI 编程赋能营的"破冰第一课"；③ 高校编程实践课导论模块；④ 转岗/跨界人员的 AI 工具速成营。
- **不适合**：已有 Claude Code 使用经验的中高级营（内容会过于基础，应直接进阶到 Hooks / Subagent / MCP）。
- **预计教学时长**：讲授 + 跟做约 **90–120 分钟**。其中环境自检与安装 30 分钟、认证与体检 15 分钟、第一个项目实战 45–60 分钟、配置体系讲解 15 分钟。
- **前置作业建议**：学员课前自行完成 Node 安装与 Anthropic 账号注册，可节省 20 分钟课堂时间。
- **考核点**：能独立让 Claude Code 产出一个可运行、带测试的小工具，并正确配置 `permissions.allow` 减少弹窗。

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