<!-- title: Claude Code 三种安装法横评与首跑 -->

# Claude Code 三种安装法横评：原生脚本为何成首选

## 概述

本教程面向第一次接触 Claude Code 的零基础开发者。2026 年官方已把**原生安装脚本（`install.sh`）**列为首推方式——零依赖、免装 Node.js、后台自动更新。本教程横向对比原生脚本、npm、Homebrew 三种安装法，带你完成从选型、安装、认证到跑通第一个项目的全流程，并附三法对比表、故障排查与一个可运行的实战项目。读完即可独立搭建并验证自己的 Claude Code 环境。

## 前置条件

正式动手前，先核对清单，避免中途卡壳：

| 项目 | 要求 | 说明 |
|------|------|------|
| 操作系统 | macOS 13+ / Ubuntu 20.04+ / Debian 10+ / Windows 10(1809+) + WSL | Windows 推荐 WSL，PowerShell 原生安装也支持 |
| 内存 | ≥ 4GB（8GB 更佳） | 本地只跑 CLI，AI 推理在云端 |
| 网络 | 需稳定连接 Anthropic 云 API | 不需要 GPU |
| 账号 | Claude Pro / Max / Teams / Enterprise，或 Console API Key | 免费版 Claude.ai **不含** Claude Code |
| 终端 | Bash / Zsh / PowerShell | 任一即可 |
| Node.js | 仅 npm 装法需要 18+ | 原生脚本与 Homebrew 装法**不需要** |

一句话：**只要你有一个 Claude 付费/API 账号、能上网的电脑，五分钟就能装好。**

---

## 正文：三种安装法横评

### 方法 A：原生安装脚本（官方首推，零依赖）

这是 2026 年 Anthropic 主要测试和维护的方式。它把一个独立的 Claude Code 二进制直接放进系统 PATH，**不依赖 Node.js、不依赖 npm**，并且在后台自动更新。

**macOS / Linux：**

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

**Windows（PowerShell，管理员身份）：**

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

**预期结果：**

```
Downloading Claude Code... 100%
Installing to ~/.local/bin/claude
Adding to PATH...
✓ Installation complete. Run `claude` to get started.
```

整个过程通常不到一分钟。装完打开一个**新终端窗口**让 PATH 生效，然后验证：

```bash
claude --version
claude doctor
```

`claude doctor` 会自检环境并报告任何配置问题，新手第一次跑用它最稳。

**常见问题：**

- *`command not found: claude`*：八成是 PATH 没刷新。**新开一个终端窗口**即可；若仍不行，重跑一次安装脚本。
- *`Network Error` / 超时*：网络或防火墙拦截了脚本下载。先确认能访问 `claude.ai`；企业内网可配置代理（见下文 npm 小节）。

### 方法 B：npm 全局安装（需 Node.js，可锁版本）

如果你团队里 npm 是标准工作流、或需要把 Claude Code **锁在某个特定版本**，用 npm：

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

⚠️ **铁律：不要用 `sudo`。** `sudo npm install -g` 是权限灾难的起点（`EACCES` 错误、文件属主错乱）。正确做法是用 nvm 把 Node 装到家目录：

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# 关闭重开终端
nvm install 22
nvm use 22
node --version          # 应输出 v22.x.x
npm install -g @anthropic-ai/claude-code
```

更新也走 npm：

```bash
npm update -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code@latest   # 装指定版本
```

**常见问题：**

- *`Node.js version too old`*：`node --version` 低于 18。用 nvm 装 22。
- *`EACCES` 权限错误*：禁用 sudo，改用 nvm（如上）。
- *国内拉不动 npm*：换源或设代理：
  ```bash
  npm config set registry https://registry.npmmirror.com/
  # 或走代理
  npm config set proxy http://your-proxy:8080
  npm config set https-proxy http://your-proxy:8080
  ```

### 方法 C：Homebrew（仅 macOS，brew 党首选）

macOS 用户若已习惯 `brew`，一行搞定：

```bash
brew install --cask claude-code
```

更新：

```bash
brew upgrade --cask claude-code
```

适合**已经在用 Homebrew 管理全机软件**的 Mac 用户，更新与其他 cask 统一。Linux/Windows 不适用。

### 三法横评对比表

| 维度 | 原生脚本 | npm | Homebrew |
|------|:--------:|:---:|:--------:|
| 依赖 Node.js | ❌ 不需要 | ✅ 需要 18+ | ❌ 不需要 |
| 安装命令 | `curl … install.sh` | `npm i -g …` | `brew install --cask …` |
| 自动更新 | ✅ 后台静默 | ❌ 手动 | ❌ 手动（brew upgrade） |
| 版本锁定 | ❌ | ✅ 可 `@版本` | ⚠️ 较弱 |
| 跨平台 | mac/Linux/Win | 全平台 | 仅 macOS |
| 适合人群 | 零基础首选 | CI/CD、锁版本团队 | brew 重度用户 |
| 官方推荐度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |

**选型结论**：个人开发、第一次装 → **原生脚本**；CI/CD 流水线、要钉死版本 → **npm**；Mac 上 everything-in-brew → **Homebrew**。

### 第四步：认证登录

装好后必须认证。在任意目录运行：

```bash
claude
```

首次会自动打开默认浏览器，登录你的 Anthropic 账号并授权。两种方式：

- **浏览器登录（默认）**：适合个人电脑，Pro/Max/Teams/Enterprise 通用。
- **API Key（无头/CI/远程服务器）**：
  ```bash
  export ANTHROPIC_API_KEY=sk-ant-your-key-here
  claude
  ```
  Key 在 [console.anthropic.com](https://console.anthropic.com/) 生成。订阅版（Pro/Max）按月含额度；API Key 按 token 计费。

> 远程服务器或 WSL 里浏览器打不开时，直接用 API Key 方式登录最省心。

---

## 实战案例：从空目录到一个可运行的命令行小工具

目标：用刚装好的 Claude Code，**从零搭一个 Python 命令行"待办管理器"**，验证整套环境跑通。

**第 1 步：建项目目录并初始化 Git（方便随时回滚）**

```bash
mkdir ~/todo-cli && cd ~/todo-cli
git init
echo "# Todo CLI" > README.md
```

**第 2 步：启动交互会话**

```bash
claude
```

进入会话后，Claude Code 已读取当前目录结构。输入任务：

```
> 用 Python 写一个命令行待办管理器 todo.py：
> 支持 add/list/done/delete 四个子命令，数据存到 todos.json。
> 给 add/list 写好用法说明，list 按未完成在前排序。
```

**预期结果：** Claude Code 会定位到合适文件、提出改动，并在修改前**逐一请求你确认**。你可在 diff 视图中逐处接受或拒绝。最终生成 `todo.py`：

```python
import json, sys, os
from pathlib import Path

DB = Path(__file__).parent / "todos.json"

def load():
    return json.loads(DB.read_text()) if DB.exists() else []

def save(todos):
    DB.write_text(json.dumps(todos, ensure_ascii=False, indent=2))

def main():
    args = sys.argv[1:]
    if not args or args[0] in ("-h", "--help"):
        print("用法: todo.py [add <text> | list | done <id> | delete <id>]")
        return
    cmd, todos = args[0], load()
    if cmd == "add":
        text = " ".join(args[1:])
        todos.append({"id": len(todos)+1, "text": text, "done": False})
        save(todos); print(f"✓ 已添加 #{len(todos)}: {text}")
    elif cmd == "list":
        todos.sort(key=lambda t: t["done"])          # 未完成在前
        for t in todos:
            mark = "[x]" if t["done"] else "[ ]"
            print(f"{mark} #{t['id']} {t['text']}")
    elif cmd == "done":
        for t in todos:
            if t["id"] == int(args[1]): t["done"] = True
        save(todos); print(f"✓ 已完成 #{args[1]}")
    elif cmd == "delete":
        todos = [t for t in todos if t["id"] != int(args[1])]
        save(todos); print(f"✓ 已删除 #{args[1]}")

if __name__ == "__main__":
    main()
```

**第 3 步：让 Claude Code 直接跑测试验证（交互会话里）**

```
> 运行 python todo.py add 买牛奶，再 add 写周报，然后 list，把输出贴给我
```

**预期结果：**

```
✓ 已添加 #1: 买牛奶
✓ 已添加 #2: 写周报
[ ] #1 买牛奶
[ ] #2 写周报
```

**第 4 步：用 `-p` 做一次性任务（非交互，适合脚本化）**

```bash
claude -p "给 todo.py 的 delete 命令补充越界 id 的健壮处理，并写一段 50 字内的注释说明改动"
```

`-p` 跑完即退出、直接输出结果，常用于快速提问和自动化。

**第 5 步（可选）：项目级配置 `.claude/settings.json`**

把团队共享的权限/模型约定提交进版本库：

```json
{
  "permissions": {
    "allow": ["read", "write", "shell"],
    "deny": ["shell:rm -rf *"]
  },
  "model": "claude-sonnet-4-6"
}
```

个人私有覆盖放在 `.claude/settings.local.json`（勿提交）。这样一个**可运行、可回滚、可协作**的 Claude Code 项目就成型了。

---

## 工作流程图

从选型到首跑的完整决策与执行链路：

```mermaid
flowchart TD
    Start([🚀 想用 Claude Code]) --> Check{核对前置条件<br/>账号+网络+OS}
    Check -->|不满足| Fix[补账号 / 装 WSL / 接网络]
    Fix --> Check
    Check -->|满足| Choose{选安装法}

    Choose -->|"个人/首装"| Native[原生脚本<br/>curl install.sh]
    Choose -->|"CI/锁版本"| NPM[npm i -g<br/>需 Node18+]
    Choose -->|"Mac brew 党"| Brew[brew install --cask]

    Native --> Verify
    NPM --> Verify
    Brew --> Verify

    Verify[claude --version<br/>claude doctor] --> Auth{认证}
    Auth -->|浏览器| Browser[登录 Pro/Max/Teams]
    Auth -->|无头/CI| Key[export ANTHROPIC_API_KEY]

    Browser --> Project[cd 项目目录<br/>运行 claude]
    Key --> Project

    Project --> Task[下任务 → 看 diff → 确认]
    Task --> Ship([✅ 首跑成功])
```

---

## 延伸阅读

- **官方文档（最权威）**：[code.claude.com/docs](https://code.claude.com/docs) —— 覆盖 MCP、hooks、无头自动化、多模型配置的进阶章节。
- **API 状态页**：[status.anthropic.com](https://status.anthropic.com) —— 遇到偶发慢/报错先看这里。
- **认证与计费细节**：[docs.anthropic.com/en/docs/claude-code/setup](https://docs.anthropic.com/en/docs/claude-code/setup) —— 浏览器登录 vs API Key 的官方说明。
- **进阶主题（后续轮次）**：Skills 自定义技能、MCP 服务器开发、Agent 无头批量模式、上下文管理与多文件重构——本系列后续逐篇展开。

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | **AI 编程入门营 / 全栈零基础营 / 企业数字化转型训练营**；任何想让学员"第一天就装好工具"的实战型训练营 |
| 学员基础要求 | 会用命令行、懂基本 Git 操作即可；无需 Node/Python 高级知识 |
| 预计教学时长 | **约 45–60 分钟**（含环境排查缓冲） |
| 动手实验占比 | 高（70% 动手 + 30% 讲解），三法任选其一装 + 跑通实战项目为结业标准 |
| 风险点 | 国内网络需准备代理/镜像；账号需提前开通 Pro/Max 或 API Key |
| 建议考核 | 学员提交 `claude doctor` 截图 + 实战项目 `list` 输出，二者皆绿即通过 |

## 参考来源

1. [How to Install Claude Code: Complete Setup Guide (2026) — NxCode](https://www.nxcode.io/resources/news/install-claude-code-setup-guide-2026) — 原生脚本/npm/Homebrew 三法、系统要求、认证与故障排查的完整对照（本文主要事实来源）。
2. [Claude Code Tutorial for Beginners 2026 — DEV Community](https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma) — 从安装到首个项目的初学者实战流程。
3. [How to Set Up Claude Code and Start Using It in 2026 — DevTools Review](https://devtoolsreview.com/tutorials/setup-claude-code/) — CLAUDE.md、权限与项目级配置的配置指南。
4. [Claude Code 官方文档 — Anthropic](https://code.claude.com/docs) — 原生安装脚本、认证、更新通道与进阶特性的权威说明。
5. [Claude Code Tutorial for Beginners - Complete 2026 Guide — CodeWithMukesh](https://codewithmukesh.com/blog/claude-code-for-beginners/) — 安装、命令与首个项目流程的补充教程。

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