<!-- title: 终端零基础：三平台三形态装通Claude Code -->

## 概述

本教程专为"从来没正经打开过终端"的开发者设计。你将用一套统一的思路，在 macOS、Windows、Linux 上完成 Claude Code 的安装、首次认证、第一个会话、第一处代码改动与第一次 Git 提交，并理解终端 CLI、桌面 App、IDE 扩展三种入口的取舍。学完后你能独立把 Claude Code 跑在一个真实项目里，并让它"记住"这个项目的规矩。

适用人群：从未用过命令行的产品/运营转码者、习惯纯 IDE 的前端同学、第一次接触 AI 编程助手的在校生，以及需要在多平台部署给团队演示的技术负责人。无需任何 Claude API 或大模型前置知识。

## 前置条件

在动手之前，你只需要三样东西：

- **一个能上网的电脑**：macOS、Windows 10/11、或任意主流 Linux 发行版均可，不必提前装好 Node.js。
- **一个 Anthropic 账号**：Claude Pro / Max / Team / Enterprise 订阅、Claude Console（API 预付费额度）、或企业云（Amazon Bedrock / Google Vertex AI / Microsoft Foundry）任选其一。第一次启动时才登录，不用提前申请密钥。
- **一个用来练手的项目目录**：可以是一个空文件夹，也可以是你手头已有的代码仓库。Claude Code 会按需读取你的文件，你不必手动"喂"上下文给它。

唯一一个强烈建议（仅 Windows 原生环境）是安装 **Git for Windows**：它自带 Bash，让 Claude Code 的文件操作更顺滑；没装也能用，只是会退回到 PowerShell 作为默认 shell。

---

## 第一步：先选入口——三种形态怎么挑

Claude Code 在 2026 年已经不是"只有命令行"。同一个账号、同一套记忆，可以从下面三个入口任意进入。先搞清楚自己适合哪一个，能省掉后面一半的劝退感。

| 形态 | 适合谁 | 优点 | 短板 |
| --- | --- | --- | --- |
| 终端 CLI | 后端、运维、想做自动化和 CI 的人 | 功能最全，支持 `-p` 批处理、hooks、脚本编排 | 需要面对命令行 |
| 桌面 App（Mac/Windows） | 不想碰终端、习惯图形界面的同学 | 安装即用、可视化会话管理、可同时开多个项目工作区 | 不能直接写脚本编排 |
| IDE 扩展（VS Code / JetBrains） | 已有主力编辑器的开发者 | 在编辑器里看 diff、一键接受改动、与断点调试联动 | 仍需本机装好 CLI 内核 |

本教程主线走**终端 CLI**（它是一切的基础，桌面 App 和 IDE 扩展在底层都依赖它），并在每一步标注"用桌面 App / IDE 扩展时这里有什么不同"。这样无论你最后选哪个，都能对照得上。

## 第二步：安装——三平台各一行命令

官方现在**首推原生安装器**（native installer），它最大的好处是**后台自动更新**，你装完后再也不用关心升级问题。下面按平台给出命令，复制对应那一行即可。

### macOS / Linux / WSL（Windows 子系统）

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

这条命令会下载安装脚本、把 `claude` 命令放到你的 `PATH` 里，并开启后台静默更新。

### Windows 原生（PowerShell）

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

> **新手最容易卡在这里的一个坑**：PowerShell 和 CMD 是两个不同的东西。如果你执行 `irm ...` 时报 `'irm' is not recognized`，说明你其实在 CMD 里；反过来，如果你执行带 `&&` 的命令时报 `The token '&&' is not a valid statement separator`，说明你其实在 PowerShell 里。判断方法很简单——提示符前缀是 `PS C:\>` 就是 PowerShell，只有 `C:\>` 就是 CMD。本教程的 Windows 命令默认针对 PowerShell。

### Windows 原生（CMD，仅当确实在用 CMD 时）

```batch
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

### 备选安装方式（按平台挑一个）

如果原生安装器在你的网络环境里跑不通，或你公司有更严格的软件来源要求，可以改用包管理器：

- **macOS（Homebrew）**：`brew install --cask claude-code`。注意 Homebrew 版**不会自动更新**，需要定期手动 `brew upgrade claude-code`。还有个 `claude-code@latest` 追最新版，`claude-code` 则是稳定通道（通常落后约一周，会跳过有重大回归的版本）。
- **Windows（WinGet）**：`winget install Anthropic.ClaudeCode`，同样需要手动 `winget upgrade Anthropic.ClaudeCode`。
- **Linux 发行版**：Debian/Ubuntu 用 `apt`、Fedora/RHEL 用 `dnf`、Alpine 用 `apk`，仓库地址见官方 setup 页。
- **npm（最传统的方式，现已不推荐）**：`npm install -g @anthropic-ai/claude-code`。需要先装好 Node.js 18+，且不会自动更新。

### 验证安装

安装完成后，在任意终端里执行：

```bash
claude --version
```

看到一串版本号（如 `1.x.x`）即代表命令已经在 `PATH` 里就绪。如果提示 `command not found` 或"不是内部或外部命令"，说明安装脚本没能把 `claude` 写进 PATH——解决办法见文末常见问题。

## 第三步：首次认证——一次登录，长期记住

在终端里直接输入 `claude` 启动：

```bash
claude
```

第一次运行会弹出登录流程，按提示在浏览器里完成授权。三选一：

1. **Claude 订阅账号（Pro / Max / Team / Enterprise，推荐）**：直接用你的 claude.ai 账号登录，额度走订阅套餐。
2. **Claude Console（API 预付费额度）**：首次登录时，Console 会自动给你建一个叫 "Claude Code" 的 workspace，方便集中看花费。
3. **企业云（Bedrock / Vertex AI / Foundry）**：走公司已有的云账号和预算池。

登录成功后，凭证会**安全地存在本机**，之后再也不用重复登录。想换账号或重新认证时，在已运行的会话里输入斜杠命令：

```text
/login
```

> 用桌面 App / IDE 扩展时：这一步通常被做成了一个"Sign in"按钮，点一下同样会跳浏览器，逻辑完全一致。

## 第四步：在项目里启动第一次会话

登录后，**先 `cd` 到你的项目目录，再启动 `claude`**——这一点很关键，Claude Code 把"当前工作目录"当作它的活动范围。

```bash
cd /path/to/your/project
claude
```

回车后你会看到一条提示信息，上面标着版本号、当前使用的模型、以及当前工作目录。到这里，你已经"装通"了。

在会话里随时可以输入：

- `/help` —— 列出所有可用命令
- `/resume` —— 恢复之前某次对话（Claude Code 会自动保留历史会话）
- `/clear` —— 清空当前上下文，开始干净的一轮
- `/init` —— 让 Claude 扫描项目并生成一份 `CLAUDE.md` 记忆文件（第八步详讲）

> 对终端零基础的同学：所谓"会话"，就是一个一直在等的输入框。你打字回车就是提问，`/` 开头的是命令。`Ctrl+C` 退出当前输入、连按两次彻底退出。

## 第五步：第一次提问——让它先"读懂"你的代码

别急着让它写代码。先用自然语言问它"这个项目是干嘛的"，这是验证"它确实能看见你的文件"的最快方式：

```text
what does this project do?
```

Claude 会自己去找 README、package.json、入口文件，然后给你一段总结。接着可以追问更具体的：

```text
what technologies does this project use?
where is the main entry point?
explain the folder structure
```

你甚至可以直接问它自己的能力边界：

```text
what can Claude Code do?
can Claude Code work with Docker?
```

如果你在练习目录里还没有任何项目，那就在下一步直接让它从零造一个。

## 第六步：第一处代码改动——批准机制是核心

让它干一件真实的小事：

```text
add a hello world function to the main file
```

Claude Code 的处理顺序永远是：

1. 找到合适的文件；
2. **把拟改动以 diff 形式展示给你看**；
3. 等你批准；
4. 才真正落盘。

这是它和"无脑改文件"工具最大的区别——**任何修改文件的操作，它都会先征求你同意**。你可以逐条批准，也可以对当前会话开启"Accept all"模式（信任它一次性改）。对零基础同学，建议先保持逐条确认，看几次 diff 就能建立起对它行为的信任感。

## 第七步：用 Git 提交——把改动变成对话

如果你的目录已经是个 Git 仓库，Claude Code 可以用自然语言操作 Git：

```text
commit the changes with a descriptive message
```

它会自己 `git add` 相关文件、生成符合规范的 commit message、再 `git commit`。如果目录还**不是** Git 仓库，先让它初始化：

```text
initialize a git repo and make the first commit
```

> 一个容易忽略的细节：Claude Code 的很多高级能力（看 diff、回滚、分支切换）都依赖底层有 Git。所以即便你只是拿它写小练习，也建议先 `git init`。

## 第八步：给项目装上"记忆"——CLAUDE.md

到这里你已经能完整跑通一轮。最后一步是让它**记住这个项目的规矩**，避免每次都从头解释。

在会话里执行：

```text
/init
```

它会扫描项目结构，在根目录生成一份 `CLAUDE.md`，内容通常包括：项目是做什么的、用什么技术栈、目录怎么组织、构建/测试/运行命令分别是什么、有什么需要遵守的约定。

你也可以手动维护它。比如在 `CLAUDE.md` 里写：

```markdown
# 项目说明
这是一个用 Python 写的命令行待办工具。

## 常用命令
- 运行：`python -m todo`
- 测试：`pytest`

## 约定
- 所有新增函数必须有 docstring
- 提交信息使用中文
```

之后每次启动 `claude`，它会**自动读入这份文件作为长期上下文**。你想让它改风格、遵守规范、记得某个固定命令，写在 `CLAUDE.md` 里一劳永逸。这正是 Claude Code"项目记忆"的根基。

---

## 实战案例：从零生成一个可运行的命令行小工具

我们把上面八步串成一个完整闭环。假设你在桌面新建了一个空文件夹 `my-first-cc`，目标是让 Claude Code 给你写一个 Python 命令行"番茄钟"小工具，并跑通、提交。

**1. 进入目录并启动**

```bash
cd ~/Desktop/my-first-cc
claude
```

**2. 一句话下达任务**

```text
用 Python 写一个命令行番茄钟工具：输入 pomodoro start 开始一个 25 分钟计时，时间到打印提醒；项目用 argparse 处理参数，带一个简单的测试文件，再帮我 git init 并提交。
```

**3. 逐条批准它的改动**。你会看到它依次创建 `pomodoro.py`、`test_pomodoro.py`，并展示 diff，确认即可。

**4. 让它跑测试**

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

它自己调用 `python -m pytest`，把结果贴给你。

**5. 生成记忆文件**

```text
/init
```

得到一份描述这个番茄钟项目的 `CLAUDE.md`。

**6. 用自然语言提交**

```text
git init，把所有文件提交，commit message 写中文
```

整个流程走完，你手上就有了一个**能跑、有测试、有版本管理、有项目记忆**的真实项目——从空文件夹到可交付，全程只用自然语言指挥。

## 全流程架构图

```mermaid
flowchart TD
    A[选择入口: 终端CLI / 桌面App / IDE扩展] --> B[原生安装器安装]
    B --> B1{平台?}
    B1 -->|macOS/Linux/WSL| C1["curl -fsSL claude.ai/install.sh \| bash"]
    B1 -->|Windows PowerShell| C2["irm claude.ai/install.ps1 \| iex"]
    B1 -->|备选| C3["Homebrew / WinGet / apt / npm"]
    C1 --> D[claude --version 验证]
    C2 --> D
    C3 --> D
    D --> E[claude 首次启动 -> 浏览器登录]
    E --> F[cd 到项目目录 -> claude]
    F --> G[第一次提问: what does this project do?]
    G --> H[下达改动任务 -> 逐条批准 diff]
    H --> I[/init 生成 CLAUDE.md 记忆/]
    I --> J[自然语言 Git 提交]
    J --> K[可交付的真实项目]
```

## 常见问题与解决方案

**Q1：`claude` 命令找不到（command not found）。**
安装脚本没能改写 PATH。临时方案是找到 `claude` 的实际安装路径用全路径执行；永久方案是把安装目录加入 PATH。macOS/Linux 通常加到 `~/.zshrc` 或 `~/.bashrc` 的 `export PATH=` 行；Windows 在"系统环境变量"里追加。重装一次原生安装器往往也能自动修复。

**Q2：Windows 下 `irm` 报错。**
说明你在 CMD 而非 PowerShell。改用 CMD 版命令，或搜索打开"PowerShell"再跑。

**Q3：第一次 `claude` 卡在登录，浏览器没弹。**
复制终端里显示的那个授权链接，手动粘到浏览器里打开；登录完会自动回调。

**Q4：网络受限/拉取 install.sh 超时。**
这属于内网受限环境的典型问题，通常需要配置代理（如设置 `HTTPS_PROXY` 环境变量）或换用 npm、Linux 包管理器等可走镜像源的安装方式。

**Q5：它改文件总是一改一大片，我看着慌。**
保持逐条确认而不是开 "Accept all"。每次只批准你看懂的 diff，几次下来你会很清楚它的行为模式。

**Q6：`/init` 生成的 CLAUDE.md 不准。**
它是基于扫描的初稿，直接手动编辑即可——这份文件归你管，Claude 每次启动都会读它。

## 延伸阅读

- 官方终端指南：如果你连 `cd` 都不熟，先读 Claude Code Docs 的 terminal guide。
- `/en/setup` 高级安装页：Linux 包管理器仓库地址、版本管理、卸载方法。
- `/en/authentication` 凭证管理：登录凭证存在哪、怎么换账号、多人共用机器的安全建议。
- `/en/memory` 与 `/en/settings`：CLAUDE.md 的完整写法和 settings.json 项目级配置。
- 桌面 App 文档 `/en/desktop` 与 IDE 扩展 `/en/vs-code`、`/en/jetbrains`：本文主线的图形界面补充。

## 训练营适用性评估

- **适合的训练营类型**：面向转码者、产品/运营学编程、企业新员工 AI 工具上手营、高校"AI 编程入门"选修。不适合已经有 CLI 经验的资深工程师进阶营（那些应直接进 Skills / MCP / hooks 主题）。
- **预计教学时长**：约 1.5–2 小时讲解 + 1 小时动手实操，共半天。
- **前置要求最低**：自带笔记本和账号即可，无需预装任何开发环境。
- **可衔接的下一课**：权限模式与项目配置入门、用 Subagent 搭代码评审、Skills 开发实战——本课是它们的公共前置。

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方快速入门，三平台原生安装命令与首次会话六步。
2. [Advanced setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 系统要求、Homebrew/WinGet/Linux 包管理器、版本管理与卸载。
3. [Claude Code Tutorial for Beginners (2026): From Installation to Building Your First Project](https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma) — 第三方入门教程，从安装到第一个项目的完整 walkthrough。
4. [How to Install Claude Code in 2026 (Mac, Windows, Linux)](https://claudify.tech/blog/install-claude-code) — 三平台两分钟安装速通与常见报错修复。
5. [How to Use Claude Code (Beginner Guide) - builder.io](https://www.builder.io/blog/how-to-use-claude-code) — 从安装到第一处代码改动的入门实战。

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