<!-- title: 跨平台装通Claude Code首个任务 -->

# 跨平台装通 Claude Code：从安装到跑通首个任务

## 概述

本教程面向零基础读者，目标只有一个：**在你的操作系统上把 Claude Code 装通、登录、验证，并在一个真实项目里跑通第一个任务**。学完你将能：在 Windows、macOS、Linux 三大平台上选择正确的安装路线；用一条命令完成原生安装并自检；完成浏览器登录认证；在项目目录里发起会话、提问、改代码、用 Git 提交，最后学会续跑与清理上下文。全程不假设你用过命令行，每个步骤都给出具体命令、预期输出与排错方案。

## 前置条件

- 一台 Windows 10 1809+、macOS 13+ 或主流 Linux（Ubuntu 20.04+ / Debian 10+ / Fedora / Alpine 3.19+）机器，x64 或 ARM64，4 GB 以上内存
- 一个 Claude 账号：Pro / Max / Team / Enterprise 订阅，或 Claude Console（API 预付费额度）。免费 Claude.ai 计划不含 Claude Code 访问权限
- 可联网的终端环境；若在中国大陆，需自备稳定的网络出口（Claude Code 需要访问 Anthropic 服务）
- 可选：Windows 用户安装 [Git for Windows](https://git-scm.com/downloads/win)，以启用 Bash 工具

## 第零步：先选对路线，再敲命令

Claude Code 在三大系统上都支持原生运行，但安装命令和后续行为不同。**不要盲目复制网上的 `npm install -g`**——原生安装器才是官方首选，它会自动后台升级、自带二进制和 ripgrep。

| 系统 | 推荐安装方式 | 是否自动升级 | 何时用它 |
| --- | --- | --- | --- |
| macOS | 原生脚本 / Homebrew | 原生：是；Homebrew：否 | 通用首选，Homebrew 适合已用 brew 管理工具的人 |
| Linux / WSL | 原生脚本 / apt/dnf/apk | 原生：是；包管理器：否 | 服务器、容器、WSL2 |
| Windows 原生 | PowerShell 或 CMD 脚本 / WinGet | 原生：是；WinGet：否 | Windows 本地项目 |
| Windows WSL2 | 在 WSL 里跑 Linux 脚本 | 原生：是 | 需要 Linux 工具链或沙箱执行 |

一条判断原则：**你的项目文件在哪个文件系统里，就在哪个系统里装**。Windows 原生项目用原生 Windows；跨平台/Linux 工程用 WSL2。

## 第一步：macOS 安装

打开「终端」，任选一种：

**A. 原生脚本（推荐，自动升级）**

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

**B. Homebrew（已用 brew 管理软件的人）**

```bash
brew install --cask claude-code          # stable 渠道，约落后一周，跳过有重大回归的版本
# 或
brew install --cask claude-code@latest   # latest 渠道，第一时间拿到新版本
```

**预期结果**：脚本下载平台二进制并链接到 `~/.local/bin/claude`。安装完成后，新开一个终端窗口，输入 `claude --version` 应输出版本号。

**常见问题**：

- `zsh: command not found: claude`——`~/.local/bin` 不在 PATH。在 `~/.zshrc` 末尾加 `export PATH="$HOME/.local/bin:$PATH"`，再 `source ~/.zshrc`。
- Homebrew 装的是旧版本——`brew upgrade claude-code` 手动升级；`brew cleanup` 清理旧版本占用的磁盘。

## 第二步：Linux 安装（含 WSL2）

**A. 原生脚本（最省心）**

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

**B. 包管理器（Debian/Ubuntu 示例，stable 渠道）**

```bash
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update && sudo apt install claude-code
```

升级用 `sudo apt update && sudo apt upgrade claude-code`。Fedora/RHEL 用 dnf 仓库，Alpine 用 apk 仓库，命令结构类似。

**Alpine / musl 系特别注意**：原生安装器依赖 `libgcc`、`libstdc++`、`ripgrep`：

```bash
apk add libgcc libstdc++ ripgrep
```

并在 `~/.claude/settings.json` 里设置：

```json
{ "env": { "USE_BUILTIN_RIPGREP": "0" } }
```

否则搜索功能可能静默失效。

**预期结果**：`claude --version` 正常输出版本号。

## 第三步：Windows 安装

先确认你在哪种终端——提示符 `PS C:\>` 是 PowerShell，`C:\>` 没有 `PS` 是 CMD。两边的命令不一样，复制错会报错。

**A. 原生安装**

PowerShell：

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

CMD：

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

**B. WinGet**

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

WinGet 不会自动升级，定期跑 `winget upgrade Anthropic.ClaudeCode`。注意：Claude Code 运行时 Windows 会锁定可执行文件，升级可能失败，按提示关闭后重试。

**强烈建议同时安装 Git for Windows**：它提供 Git Bash，让 Claude Code 用上完整的 Bash 工具。没装的话，Claude Code 会退回到 PowerShell 工具。如果装了 Git 但 Claude Code 找不到 bash.exe，在 `settings.json` 里指定路径：

```json
{ "env": { "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" } }
```

**何时用 WSL2 而不是原生 Windows**：当你的项目依赖 Linux 工具链（Docker、原生编译、特定脚本），或你需要沙箱执行命令时，打开 WSL 终端，按上面「Linux 安装」的步骤走。记住——**在 WSL 里安装和启动 `claude`，而不是在 PowerShell/CMD 里**。

**常见问题**：

- `The token '&&' is not a valid statement separator`——你在 PowerShell 里跑了 CMD 命令，换成 `irm ... | iex`。
- `'irm' is not recognized`——你在 CMD 里跑了 PowerShell 命令，换成 CMD 那条。
- `syntax error near unexpected token '<'`、`403`、其他 curl 错误——多半是网络出口问题或脚本被中间设备改写，见官方排错页换备用安装方式。

## 第四步：验证安装

```bash
claude --version
```

要做更彻底的自检（PATH、权限、更新状态、配置健康度）：

```bash
claude doctor
```

`claude doctor` 会报告最近一次升级尝试的结果、npm 全局目录是否可写等信息，是装通后必跑的一道关。

## 第五步：登录认证

在任意目录启动交互式会话：

```bash
claude
```

首次启动会引导你在浏览器里完成登录。可选账号类型：

- Claude Pro / Max / Team / Enterprise（推荐）
- Claude Console（API 预付费额度；首次登录会自动创建一个 "Claude Code" 工作区用于成本汇总）
- Amazon Bedrock / Google Vertex AI / Microsoft Foundry（企业云）
- 组织自建的 Claude apps gateway（管理员预配网关 URL，`/login` 直接进 Cloud gateway 用企业 SSO 登录）

登录后凭证会存到本地，之后无需重复登录。要切换账号或重新认证，在运行中的会话里输入：

```text
/login
```

**预期结果**：终端回到 Claude Code 提示符，顶部显示版本号、当前模型和工作目录。

## 第六步：进入项目并启动会话

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

提示符上方会显示版本、模型、工作目录。输入 `/help` 看可用命令，`/resume` 继续上次对话。

**新手最该掌握的几个 shell 命令**（在普通终端里敲，不是会话内）：

| 命令 | 作用 |
| --- | --- |
| `claude` | 启动交互模式 |
| `claude "修个构建错误"` | 一次性任务，跑完即退 |
| `claude -p "解释这个函数"` | 单次查询，输出后退出 |
| `claude -c` | 继续当前目录最近一次对话 |
| `claude -r` | 恢复历史某次对话 |

## 第七步：第一问——让 AI 先读懂你的项目

不要一上来就让它改代码，先让它建立认知：

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

```text
what technologies does this project use?
```

```text
where is the main entry point?
```

```text
explain the folder structure
```

Claude Code 会按需读取项目文件，你不用手动喂数据。这一步的价值是：**先校准它对项目的理解，再下任务，准确率显著提高**。

## 第八步：第一次改代码

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

Claude Code 会：定位文件 → 展示拟改内容 → 请求你批准 → 落地编辑。**它永远在改文件前征求许可**。你可以逐条批准，也可以对本会话开启 "Accept all"。

小技巧：按 `Shift+Tab` 循环切换权限模式，在「逐条确认」与「自动接受」之间切换，平衡安全与效率。

## 第九步：用对话方式操作 Git

```text
what files have I changed?
```

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

```text
create a new branch called feature/quickstart
```

```text
show me the last 5 commits
```

Claude Code 会读你的 git 状态、生成规范的提交信息，但**真正执行 `git commit` 这类写操作前仍会征求许可**。按全局最佳实践，提交动作请你在确认后手动放行，不要让它无监督改写历史。

## 第十步：续跑与清理

长会话会让上下文变长、变贵。掌握这三个会话内命令：

```text
/clear      # 清空当前对话历史，重新开始
/help       # 查看所有命令与技能
/exit       # 退出（或按 Ctrl+D）
```

下次想接着干：`claude -c`（同目录续最近）或 `claude -r`（挑一条历史）。

## 实战案例：从零搭一个待办 CLI 并首次提交

目标：在空目录里，让 Claude Code 从零搭建一个 Node.js 命令行待办工具，并完成首次 Git 提交。

```bash
mkdir todo-cli && cd todo-cli
git init
claude
```

在会话里分步下指令（拆步比一句话全塞给它更可靠）：

```text
1. 初始化一个 Node.js 项目，入口 src/index.js
2. 实现 add/list/done 三个子命令，数据存到 ~/.todo-cli.json
3. 安装 commander 作为命令解析库
4. 写一个 README，包含安装与用法
5. 用 npm init -y 和 npm install 完成依赖
```

Claude Code 会逐项执行，每改一个文件都征求许可。完成后做首次提交：

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

它会基于 diff 生成提交信息并执行。最后验证：

```bash
node src/index.js add "跑通首个任务"
node src/index.js list
git log --oneline -1
```

**预期结果**：list 能看到刚才的待办，`git log` 显示一条由 AI 生成信息的提交。这就是一次完整的「安装→登录→首个任务→首次提交」闭环。

## 完整工作流

```text
flowchart TD
    A[选系统与安装路线] --> B{Windows?}
    B -- 原生 --> C1[PowerShell/CMD 脚本或 WinGet<br/>建议装 Git for Windows]
    B -- 是,需Linux --> C2[WSL2 里跑 Linux 脚本]
    B -- macOS --> C3[install.sh 或 brew cask]
    B -- Linux --> C4[install.sh 或 apt/dnf/apk]
    C1 --> D
    C2 --> D
    C3 --> D
    C4 --> D
    D[claude --version / claude doctor 自检] --> E[claude 启动 + 浏览器登录]
    E --> F[cd 进入项目目录 + claude]
    F --> G[第一问: 让 AI 读懂项目]
    G --> H[第一次改代码 逐条批准]
    H --> I[Git 对话式提交]
    I --> J[/clear 或 claude -c 续跑]
```

## 训练营适用性评估

- **适用类型**：零基础开发者训练营、企业新员工 AI 编程入门、跨平台开发团队统一上手培训。本教程是任何后续主题（Skills、MCP、Hooks、子代理）的地基，必须先跑通。
- **预计教学时长**：2–3 小时。其中安装与登录 30–45 分钟（含网络与权限排错），首个任务实战 60–90 分钟，答疑 30 分钟。
- **分组建议**：按操作系统分组，每组配一份对应的安装清单，避免 Windows 与 macOS 学员互相干扰。
- **考核点**：能独立完成 `claude doctor` 无报错、能跑通实战案例的 list 与首次 git 提交、能讲清 `claude -c` 与 `/clear` 的区别。

## 延伸阅读

- 官方终端指南（terminal guide）——给从没用过命令行的人
- 官方 Best Practices——如何写出更高效的指令
- 官方 Authentication 文档——Console 工作区、团队账号、企业 SSO 的完整说明
- 官方 Troubleshoot Installation——按报错信息匹配修复方案与备用安装方式
- 后续教程预告：Skills 开发、MCP 服务器、Hooks 自动化

## 参考来源

1. [Claude Code 官方快速入门（Quickstart）](https://code.claude.com/docs/en/quickstart) — 安装、登录、首个会话、Git 协作的官方权威步骤
2. [Claude Code 官方高级安装（Advanced setup）](https://code.claude.com/docs/en/setup) — 三大平台系统要求、原生/包管理器/npm 安装、版本管理与卸载
3. [How to Use Claude Code in Terminal — Windows, macOS, and Linux](https://www.how2shout.com/how-to/how-to-use-claude-code-in-terminal.html) — 跨平台（含 WSL）10 分钟装通的社区图文教程，覆盖 PowerShell、brew、winget
4. [Getting Started with Claude Code in 2026: Setup to First Commit](https://septimlabs.com/blog/getting-started-with-claude-code-2026) — 2026 年从安装到首次提交的五步实战博客
5. [Install Claude Code CLI: 5-Minute Setup Guide (2026)](https://blakecrosley.com/blog/claude-code-quickstart) — npm 安装、认证、CLAUDE.md 与权限配置的入门博客

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