<!-- title: 原生安装实战：零依赖跑通首个项目 -->

## 概述

本教程面向零基础读者，目标是**用一条命令、不装 Node.js、不碰 npm，在 15 分钟内把 Claude Code 跑起来并交付一个可运行的小项目**。我们会以 Anthropic 2025 年 10 月正式 GA（General Availability）的**原生安装器（Native Installer）**为主线，因为它把过去"先装 Node 18+、再用 npm 全局安装、再配 PATH"的三步链路压缩成了一条 curl / PowerShell 命令，是 2026 年官方首推的安装方式。学完你将掌握：安装、首次认证、目录初始化、CLAUDE.md 记忆文件、第一次有效对话、以及一个能直接跑的 TODO CLI 实战。

## 前置条件

- 一台 macOS、Linux 或 Windows（含 WSL / PowerShell）机器，**不需要预装 Node.js**——这是原生安装器相对 npm 路径最大的区别。
- 4GB 以上内存、稳定的网络。
- 一个可用的浏览器（首次登录要用）。
- 一个 Claude 账号（免费层即可起步，Pro / Max / Console API key 任选一种登录方式）。
- 终端基础：会 `cd` 切目录、会复制粘贴命令即可。如果你连终端都没怎么用过，先用 `Terminal`（macOS）或 `PowerShell`（Windows）打开一个窗口跟着敲就行。

---

## 第一步：理解安装路径的演进

在过去很长一段时间，Claude Code 只有一种官方安装方式：

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

这条命令的背后是一整套隐性依赖链：你需要先有 Node.js 18+，需要 `npm`，需要全局写入权限，Windows 下还要解决 `claude` 命令不在 PATH 里的"command not found"问题。对零基础用户，这条链路上的任何一环卡住，整套体验就断了。

2025 年 10 月，Anthropic 宣布**原生安装器正式 GA**。它把 Claude Code 打包成一个自包含的可执行文件，安装脚本只做三件事：下载二进制、放进标准目录、写入 PATH。**没有 Node.js，没有 npm，没有全局权限纠葛**。2026 年，它已成为官方文档的推荐路径，Homebrew、WinGet、`apt` 等包管理器作为补充，npm 退居"兜底方案"。

理解这段演进的意义在于：网上大量 2024–2025 年中段的教程仍在教 `npm install`，而你今天应当首选原生安装器，避免老路径带来的环境问题。

---

## 第二步：安装 Claude Code

### macOS / Linux / WSL（一条 curl 命令）

打开终端，粘贴并回车：

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

**预期结果**：脚本会自动识别你的操作系统与 CPU 架构（Intel / Apple Silicon / x86_64 / arm64），下载对应的二进制文件到 `~/.local/bin/claude`（或系统约定的 bin 目录），并把该目录追加到你的 shell PATH。

安装完成后**新开一个终端窗口**（让 PATH 生效），然后验证：

```bash
claude --version
```

正常情况下会打印出一行版本号，例如 `2.x.x`。看到版本号即代表安装成功。

### Windows（一条 PowerShell 命令）

以管理员或普通用户身份打开 PowerShell，执行：

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

脚本会把 `claude.exe` 放到用户目录下的约定位置并写入用户级 PATH。完成后**新开一个 PowerShell 窗口**，验证：

```powershell
claude --version
```

### 备选方案（按需选用）

- **Homebrew（macOS）**：`brew install --cask claude-code`，适合已经在用 brew 管理软件的人。
- **WinGet（Windows）**：`winget install Anthropic.ClaudeCode`，适合企业内网用 winget 统一分发的场景。
- **npm 兜底**：`npm install -g @anthropic-ai/claude-code`，仅在上述方法都不可用时使用，且需要 Node.js 18+。

> 三种信息源交叉印证：Anthropic 官方 setup 文档把"Native Install"列为推荐项；tokenmix 与 morphllm 的 2026 安装指南均确认原生安装器为默认路径；deepwiki 的安装章节同样标注 npm 为 fallback。

---

## 第三步：首次认证登录

原生安装器装好之后，二进制本身只是一个壳，真正驱动它的是你的 Claude 账号或 API key。第一次运行 `claude` 会进入引导式登录。

在任意目录执行：

```bash
claude
```

首次启动会出现认证选择菜单，常见有三种方式：

1. **Claude 账号登录（推荐给个人用户）**：选择后会弹出一个浏览器窗口，要求你登录 claude.ai 并授权。授权成功后终端会自动跳回，显示欢迎信息。这种方式走 Pro / Max 订阅额度，不需要单独配 API key。
2. **Console API Key**：在 Anthropic Console 申请一个 `sk-ant-...` 开头的 key，通过环境变量注入：
   ```bash
   export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
   ```
   Windows PowerShell 用 `$env:ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"`。适合按 token 计费、想精确控成本的开发者。
3. **企业单点登录（SSO）**：如果公司配发了 Bedrock 或 Vertex 的接入方式，按引导选择对应 provider 并填 endpoint 即可。

**预期结果**：登录成功后，终端底部会出现一条输入框，光标闪烁，等待你的第一条指令。此时你已进入 Claude Code 的交互式会话（REPL）。

### 常见问题

- **浏览器没自动弹出**：复制终端里打印的那段 `https://claude.ai/oauth/...` 链接，手动粘到浏览器打开即可。
- **公司网络拦截 claude.ai**：设置 HTTPS 代理，`export HTTPS_PROXY=http://your-proxy:port`。
- **登录后报 401 / unauthorized**：多半是系统时间不准（OAuth 对时间敏感），校准系统时钟后重试 `/login`。

---

## 第四步：创建第一个项目目录

Claude Code 的工作单位是"目录"——你 `cd` 到哪里，它就认为哪里是当前项目。我们来建一个干净的练习目录：

```bash
mkdir ~/my-first-claude-project && cd ~/my-first-claude-project
```

Windows：

```powershell
mkdir $HOME\my-first-claude-project ; cd $HOME\my-first-claude-project
```

进入目录后再次启动：

```bash
claude
```

此时 Claude Code 会意识到这是一个"空的新项目"，并在会话开始时给你一些初始化建议。

---

## 第五步：用 `/init` 生成 CLAUDE.md 记忆文件

CLAUDE.md 是 Claude Code 的**项目记忆文件**——一段纯 Markdown，每次会话开始时会被自动注入到上下文里，告诉模型这个项目的约定、技术栈、命令、风格偏好。它对输出质量的影响是所有配置项里最大的。

在 REPL 里输入：

```
/init
```

**预期结果**：Claude 会扫描当前目录（虽然现在是空的），并基于你和它的一两句交互，生成一份 `CLAUDE.md` 草稿，内容通常包括：项目概述、技术栈、构建/测试命令、代码风格约定。

由于目录是空的，生成的会是模板。我们手动把它改成下面这样，为接下来的实战做准备：

```markdown
# 项目：my-first-claude-project

## 概述
一个用于学习 Claude Code 的练习项目，第一个交付物是一个命令行 TODO 工具。

## 技术栈
- 语言：Node.js（仅运行时需要，开发可依赖 Claude Code 安装器自带的运行环境，或本机 Node）
- 无外部依赖，仅用 Node 标准库（fs、path）

## 约定
- 数据文件存放在项目根目录的 todos.json
- 所有用户可见文案使用中文
- 函数与变量命名使用英文 snake_case

## 常用命令
- 运行：node todo.js
- 测试：手动运行 `node todo.js add "买菜"` 后查看 todos.json
```

保存后，**下一次**启动 `claude` 时，这份内容会自动进入上下文，你会发现它"天然就知道"要用 Node、要用中文、数据存 `todos.json`。

> 记忆文件是分层的：项目根 `CLAUDE.md`（进版本库，团队共享）→ 父目录 `CLAUDE.md`（个人偏好）→ `~/.claude/CLAUDE.md`（全局偏好，所有项目生效）。越靠下层越通用，越靠上层越具体。

---

## 第六步：第一次有效对话与实战项目

现在让 Claude Code 帮我们从零写出第一个可运行程序。在 REPL 里输入：

```
帮我实现一个命令行 TODO 工具，文件名 todo.js。要求：
1. 支持 add "内容" 增加待办
2. 支持 list 列出所有待办
3. 支持 done <序号> 标记完成
4. 数据存到 todos.json
5. 不引入任何第三方依赖
遵循 CLAUDE.md 里的约定。
```

**预期结果**：Claude Code 会创建 `todo.js`，写入实现，并提示你可以怎么运行。一份典型实现大约 60 行，核心是 `fs.readFileSync` / `fs.writeFileSync` 读写 JSON。

退出 REPL（按两次 `Ctrl+C` 或输入 `/exit`），在终端验证：

```bash
node todo.js add "买菜"
node todo.js add "写周报"
node todo.js list
node todo.js done 1
node todo.js list
```

**预期输出**：

```
$ node todo.js list
1. [完成] 买菜
2. [未完成] 写周报
```

同时项目根目录会出现一个 `todos.json`，内容随操作更新。

这就完成了一个最小闭环：**需求 → 对话 → 代码 → 运行 → 验证**。对零基础读者，这条闭环跑通的意义远大于程序本身——你证明了可以用自然语言驱动一个真实的工程产物。

---

## 第七步：常用交互命令速查

进入 REPL 后，以 `/` 开头的是斜杠命令，以 `@` 开头的是文件引用。下面是最常用的一组：

| 命令 | 作用 |
|------|------|
| `/init` | 扫描项目并生成 CLAUDE.md 草稿 |
| `/memory` | 快速编辑各层 CLAUDE.md |
| `/clear` | 清空当前会话上下文（保留 CLAUDE.md） |
| `/help` | 查看所有命令 |
| `/login` | 重新登录或切换账号 |
| `/config` | 打开设置（主题、模型、权限等） |
| `/exit` | 退出 REPL |
| `@todo.js` | 把某个文件内容显式喂给上下文 |
| `Esc Esc` | 回溯编辑上一条消息 |

记住一个心法：**上下文是有限的资源**。当对话变长、模型开始"忘事"或答非所问时，第一反应应当是 `/clear` 重新开始一个干净会话，而不是继续追问。

---

## 工作流程全景

```text
flowchart TD
    A[打开终端] --> B[curl / PowerShell 一键安装]
    B --> C{claude --version<br/>能看到版本?}
    C -- 否 --> D[检查 PATH / 重开终端 / 查看常见问题]
    D --> B
    C -- 是 --> E[cd 到项目目录]
    E --> F[claude 启动 REPL]
    F --> G[首次认证 /login]
    G --> H[/init 生成 CLAUDE.md]
    H --> I[编辑 CLAUDE.md 写明约定]
    I --> J[自然语言提需求]
    J --> K[Claude 生成/修改代码]
    K --> L[退出 REPL 运行验证]
    L --> M{运行符合预期?}
    M -- 否 --> J
    M -- 是 --> N[交付 ✅]
```

---

## 实战案例完整复盘

把上面几步串起来，完整的从零到可运行过程如下，你可以照着逐行复制：

```bash
# 1. 安装（macOS/Linux）
curl -fsSL https://claude.ai/install.sh | bash

# 2. 新开终端，验证
claude --version

# 3. 建项目目录
mkdir ~/my-first-claude-project && cd ~/my-first-claude-project

# 4. 启动并登录
claude
#    -> 浏览器登录 claude.ai 授权

# 5. 在 REPL 内初始化记忆
/init
#    -> 用编辑器把 CLAUDE.md 改成第六步前的模板，保存

# 6. 在 REPL 内提需求，让它生成 todo.js
#    （粘贴第六步的需求块）

# 7. 退出 REPL（Ctrl+C 两次）

# 8. 终端验证
node todo.js add "买菜"
node todo.js list
```

这套流程的价值在于它的**可复现性**：换一台新机器，换一个新项目，只要把第 5、6 步的内容换掉，剩下的命令一字不改。这也是为什么"原生安装器 + /init + CLAUDE.md"被视作 2026 年最值得固化的入门基线。

---

## 常见问题与解决方案

**Q：执行 `claude` 提示 `command not found`。**
A：原生安装器把二进制放进的是用户级 bin 目录，PATH 没刷新。彻底关闭所有终端窗口再开一个；仍不行就手动把 `~/.local/bin`（macOS/Linux）或用户 Scripts 目录（Windows）加入 PATH。

**Q：我以前用 `npm install -g` 装过旧版，要不要卸载？**
A：建议卸载以避免两套 `claude` 冲突：`npm uninstall -g @anthropic-ai/claude-code`，再用原生安装器重装。`which -a claude`（macOS/Linux）可以看到系统里有几个 claude。

**Q：登录后第一次对话就报错 / 转圈不出结果。**
A：检查网络与代理。Claude Code 走 HTTPS 到 `api.anthropic.com` 与 `claude.ai`，企业内网常拦截。设 `HTTPS_PROXY` 后 `/clear` 重试。

**Q：CLAUDE.md 写了但模型好像没遵守？**
A：检查文件确实在项目根目录、文件名大小写完全正确（`CLAUDE.md`，全大写）。`/memory` 可以看到当前生效的所有层级记忆。

**Q：原生安装器还需要 Node.js 吗？**
A：**安装和运行 Claude Code 本身不需要**。但如果你让它写的是 Node 程序（如本教程的 todo.js），那么运行那个程序时仍需本机有 Node.js——这是"运行你的代码"的需求，不是"运行 Claude Code"的需求。

---

## 训练营适用性评估

- **适用类型**：面向**编程零基础 / 工具入门**的半天制训练营，或更大型 AI 编程训练营的"第 0 课 / 破冰课"。也适合企业内训的新人 onboarding 第一节。
- **预计教学时长**：**1.5–2 小时**。其中安装与认证 30 分钟（含排错），CLAUDE.md 与记忆机制讲解 30 分钟，TODO 实战与自由探索 45 分钟，答疑 15 分钟。
- **学员产出验收标准**：能独立跑通 `claude --version` → 登录 → `/init` → 生成并运行 todo.js 的完整链路，并能口头复述 CLAUDE.md 的作用。
- **进阶衔接**：本课结束后，自然衔接"Skills 开发""MCP 服务器""Agent 自动化"等主题。建议本课作为整条 Claude Code 训练营链路的第一站。

---

## 延伸阅读

- Anthropic 官方 Quickstart 与 Advanced setup 文档：安装命令的权威来源，遇到分歧以官方为准。
- 官方 Memory 文档：深入理解 CLAUDE.md 的分层机制与自动学习。
- Terminal guide for new users：官方为"从没用过终端"的用户写的逐图教程，适合作为本课的兜底参考资料。
- Claude Code GitHub 仓库的 Release Notes：跟踪原生安装器的版本演进与已知问题。
- DataCamp《Writing the Best CLAUDE.md》：社区公认较扎实的 CLAUDE.md 撰写指南，可作为第二步进阶读物。

---

## 参考来源

1. [Advanced setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 官方安装方式总览，明确 Native Install 为推荐项、Homebrew/WinGet/npm 为补充与兜底。
2. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方首次运行与认证流程的权威步骤。
3. [How Claude remembers your project - Claude Code Docs](https://code.claude.com/docs/en/memory) — CLAUDE.md 分层记忆机制官方说明。
4. [Native installer for Claude Code is now generally available](https://www.eonmsk.com/2025/10/31/native-installer-for-claude-code-is-now-generally-available/) — 原生安装器 2025 年 10 月 GA 的新闻佐证，解释其零 Node 依赖特性。
5. [Claude Code Install 2026: Mac, Windows, Linux Setup Fixes](https://tokenmix.ai/blog/claude-code-install-mac-windows-linux-2026) — 2026 年跨平台安装与"command not found"等常见排错汇总。

---

> 本文由「51学通信」原创整理，站长爱卫生（微信：gprshome201101）持续输出通信与 AI 工程实战内容。Claude Code 的命令与行为以官方最新文档为准，安装器命令在不同版本间可能微调，动手前建议先 `claude --help` 核对一次。

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