<!-- title: 原生安装器跑通首个API -->

## 概述

## 前置条件

- **操作系统**:macOS 13+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+、Alpine 3.19+
- **硬件**:4 GB+ 内存,x64 或 ARM64 处理器
- **网络**:联网即可;`curl`/`irm` 能访问 `claude.ai`
- **账号**:Claude Pro / Max / Team / Enterprise 订阅,或 [Claude Console](https://console.anthropic.com/)(API 预付额度)。注意:**免费 claude.ai 计划不含 Claude Code 权限**
- **Python 3.10+**(实战项目用 FastAPI;可选但建议)
- **Git**(强烈建议,用于 `/commit`、PR 等工作流)
- **ripgrep**:通常随 Claude Code 内置,搜索失败时再单独排查

## 一、用原生安装器安装(无需 Node.js)

2026 年起,官方文档推荐的首选安装方式是**原生安装器(native installer)**——它直接下载与平台匹配的原生二进制,装到 `~/.local/bin/claude`,**不再依赖 Node.js/npm**。这是与旧版 `npm install -g` 路线最大的区别。

### 操作说明

**macOS / Linux / WSL:**

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

**Windows PowerShell:**

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

**Windows CMD:**

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

可选渠道与包管理器(适合企业统一分发或习惯 `brew`/`winget` 的用户):

```bash
brew install --cask claude-code        # macOS,两个 cask:claude-code(稳定)/ claude-code@latest(最新)
winget install Anthropic.ClaudeCode     # Windows,需手动 winget upgrade
# Debian/Ubuntu:apt;Fedora/RHEL:dnf;Alpine:apk(均为签名仓库,详见官方 setup 文档)
```

### 预期结果

原生安装会**在后台自动更新**,保持最新版。安装完成后验证:

```bash
claude --version     # 打印版本号,如 2.1.x
claude doctor        # 深度体检:二进制路径、更新状态、权限、网络等
```

`claude doctor` 是排查"装好了但用不了"类问题的第一利器——它会列出最近一次更新尝试的结果以及可用的修复建议。

### 常见问题与解决

| 报错 | 原因 | 解决 |
|------|------|------|
| `command not found: claude` | `~/.local/bin` 不在 PATH | `export PATH="$HOME/.local/bin:$PATH"` 写入 `~/.zshrc` 或 `~/.bashrc`,重开终端 |
| `The token '&&' is not a valid statement separator` | 你在 PowerShell 却用了 CMD 命令 | 提示符有 `PS C:\` 即 PowerShell,改用 `irm` 命令 |
| `'irm' is not recognized` | 你在 CMD 却用了 PowerShell 命令 | 提示符是 `C:\` 即 CMD,改用 CMD 那条命令 |
| `syntax error near unexpected token '<'` / 403 | 代理/防火墙/公司网络拦截 | 见官方 [Troubleshoot installation](https://code.claude.com/docs/en/troubleshoot-install) 的错误对照表 |
| Alpine 上启动异常(musl) | 缺运行时库 | `apk add libgcc libstdc++ ripgrep`,并在 settings.json 设 `"USE_BUILTIN_RIPGREP": "0"` |

> 小贴士:WinGet / Homebrew / apt 安装的版本**默认不会自动更新**,需要定期手动 `winget upgrade` / `brew upgrade claude-code`。想让它后台自动升级,可在 settings.json 设 `"CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "1"`(apt/dnf/apk 仍需手动,因要提权)。

## 二、首次启动与登录

### 操作说明

在任意目录运行:

```bash
claude
```

首次启动会引导你在浏览器完成登录。会话内切换账号或重新认证用:

```
/login
```

可选的账号类型(任选其一):

- **Claude Pro / Max / Team / Enterprise**(订阅,推荐)
- **Claude Console**([console.anthropic.com](https://console.anthropic.com/),API 预付额度计费;首次登录会自动创建一个名为 "Claude Code" 的 workspace 用于成本归集)
- **第三方云**:Amazon Bedrock、Google Vertex AI、Microsoft Foundry(企业)

### 预期结果

登录后凭据会**持久化存储在本地**,之后无需再次登录。会话启动后,你会看到版本号、当前模型、工作目录显示在提示符上方。输入 `/help` 查看全部命令,`/resume` 恢复历史会话。

### 常见问题

- **"free plan does not include Claude Code"**:免费 claude.ai 不含权限,需升级到 Pro/Max 或使用 Console 预付额度。
- **公司网络登录失败**:确认能访问 `claude.ai` 与 `api.anthropic.com`;部分企业需配置出口代理,见官方 [Network configuration](https://code.claude.com/docs/en/network-config)。

## 三、核心配置三件套:模型、记忆、权限

装好只是起点。三个配置决定后续每一次会话的体验:**模型选择**、**`CLAUDE.md` 项目记忆**、**权限策略**。

### 1. 选择模型

会话内 `/model` 切换模型(如 Opus / Sonnet / Haiku 对应不同能力与速度)。日常编码默认即可;复杂重构或架构设计可临时切到更强模型。

### 2. 写好 `CLAUDE.md`(项目记忆)

`CLAUDE.md` 是一个特殊文件,**每次会话开始都会被自动读取**,给 Claude 提供"代码里推断不出来"的持久上下文。零成本起步方式:

```
/init
```

`/init` 会分析你的代码库(构建系统、测试框架、代码模式),生成一份起始 `CLAUDE.md`,你再据此精修。示例(节选自官方最佳实践):

```markdown
# Code style
- 使用 ES modules(import/export),不用 CommonJS(require)
- 尽可能解构导入(如 import { foo } from 'bar')

# Workflow
- 一连串改动结束后务必做类型检查
- 为性能考虑,优先跑单个测试而非整套
```

**关键原则:精简。** 每一行都问自己"删掉它,Claude 会犯错吗?"如果不会,就删。官方明确指出:**过长的 `CLAUDE.md` 会让 Claude 忽略你真正的指令**——重要规则会被噪声淹没。把它像代码一样对待:出错时复查、定期修剪、改完观察 Claude 行为是否真的变了。

放置位置与作用域:

| 位置 | 作用 |
|------|------|
| `~/.claude/CLAUDE.md` | 全局,所有会话生效 |
| `./CLAUDE.md`(项目根) | 提交进 git,团队共享 |
| `./CLAUDE.local.md` | 个人本地笔记,加入 `.gitignore` 不共享 |
| 父目录 / 子目录 | 单仓多模块时自动/按需加载 |

`CLAUDE.md` 还支持 `@path/to/import` 语法引入其它文件(如 `@README.md`、`@package.json`)。

### 3. 配置权限(减少打断又不失控)

默认情况下,Claude Code 对**任何可能修改系统的操作**(写文件、跑 Bash、调 MCP)都会请求批准——安全但繁琐。三种降打扰方式,按需选用:

- **Auto mode**(`Shift+Tab` 切换):用一个独立的分类器模型审核命令,**只拦截高风险动作**(越权、未知基础设施、被恶意内容驱动的操作),放行常规工作。
- **权限白名单**(`/permissions`):把你确信安全的命令加入白名单,如 `npm run lint`、`git commit`。
- **沙箱**(`/sandbox`):OS 级隔离,限制文件系统与网络访问,让 Claude 在边界内更自由地操作。

settings.json(项目级 `.claude/settings.json`)示例:

```json
{
  "autoUpdatesChannel": "stable",
  "permissions": {
    "allow": ["Bash(uvicorn *)", "Bash(pytest *)", "Bash(git add:*)", "Bash(git commit:*)"]
  }
}
```

### 常见问题

- **"明明 CLAUDE.md 里写了,它还是不照做"**:八成是文件太长,规则被淹没。精简到只剩"删掉就会犯错"的条款;对最关键的几条加 `IMPORTANT` / `YOU MUST` 强调;若需要**每次零例外**执行,改用 [Hooks](https://code.claude.com/docs/en/hooks-guide) 而非 CLAUDE.md(CLAUDE.md 是建议性的,Hooks 是确定性的)。

## 四、建立正确的工作流认知

在动手写第一个项目前,先内化两个反直觉的最佳实践——它们决定你用 Claude Code 的上限:

**1. 先探索,再计划,再编码。** 不要让 Claude 直接跳进编码,容易解错题。用**计划模式(Plan Mode)**把"调研/规划"与"执行"分离:先让 Claude 只读文件、回答问题、产出实现计划(`Ctrl+G` 可在编辑器里直接改计划),再退出计划模式让它照计划编码并跑测试。一句话能描述清楚的 diff(改个 typo、加一行日志)则**跳过计划**直接做。

**2. 给 Claude 一个"可验证的检查"。** 这是"你盯着的会话"与"你能离开的会话"的分水岭。提供一个能返回 pass/fail 的检查——测试套件、构建退出码、linter、或一张可对比的浏览器截图——让 Claude 自己跑、自己读结果、自己迭代到通过。否则 Claude 只能凭"看起来做完了"停下,你就成了那个验证回路。

```text
# 好(带验证)
写一个 validate_email 函数。示例:user@example.com→True,user@.com→False。
实现后跑测试并修到全绿。

# 差(无验证)
实现一个校验邮箱的函数。
```

## 五、实战案例:15 分钟构建并跑通 FastAPI 短链接 API

下面把上面所有概念串起来,做一个**完整、可运行、可测试、可提交**的"首个真实项目":一个带数据校验与 SQLite 持久化的短链接 REST API。

### 5.1 建项目并启动 Claude Code

```bash
mkdir shorturl-api && cd shorturl-api
git init
claude                # 启动会话
```

进入会话后,先用**计划模式**描述需求(按两次 `Shift+Tab` 进入,或输入时它会建议),让 Claude 先调研再产出计划:

```text
我要做一个短链接 API。技术栈:FastAPI + SQLite + Pydantic。
功能:POST /shorten 生成短码(6位随机),GET /{code} 302 跳转原链接,GET /stats/{code} 看点击数。
要求:输入用 Pydantic 校验(URL 必填、合法),用 TestClient 写测试,实现完跑 pytest 修到全绿。
先给我实现计划,确认后再写码。
```

### 5.2 让 Claude 生成 `CLAUDE.md`

```
/init
```

随后让 Claude 根据本项目实际精修,例如约定"用 `uvicorn` 本地跑、`pytest` 测试、代码风格遵循 PEP 8"。

### 5.3 生成并审视代码

Claude 会产出约三个文件。下面给出参考实现(你也可以直接让 Claude 写并对照):

**`requirements.txt`:**
```
fastapi
uvicorn[standard]
pytest
httpx
```

**`main.py`:**
```python
from fastapi import FastAPI, HTTPException, RedirectResponse
from pydantic import BaseModel, HttpUrl, Field
import sqlite3, string, secrets

app = FastAPI(title="Short URL API")
CODE_LEN = 6
ALPHABET = string.ascii_letters + string.digits

class ShortenIn(BaseModel):
    url: HttpUrl = Field(..., description="要缩短的长链接")

def db() -> sqlite3.Connection:
    conn = sqlite3.connect("shorturl.db", check_same_thread=False)
    conn.execute("""CREATE TABLE IF NOT EXISTS links(
        code TEXT PRIMARY KEY, url TEXT NOT NULL, hits INTEGER DEFAULT 0)""")
    return conn

def new_code() -> str:
    return "".join(secrets.choice(ALPHABET) for _ in range(CODE_LEN))

@app.post("/shorten")
def shorten(body: ShortenIn):
    conn = db()
    code = new_code()
    conn.execute("INSERT INTO links(code,url) VALUES(?,?)", (code, str(body.url)))
    conn.commit()
    return {"short_url": f"http://localhost:8000/{code}", "code": code}

@app.get("/{code}")
def redirect(code: str):
    conn = db()
    row = conn.execute("SELECT url FROM links WHERE code=?", (code,)).fetchone()
    if not row:
        raise HTTPException(status_code=404, detail="code not found")
    conn.execute("UPDATE links SET hits = hits + 1 WHERE code=?", (code,))
    conn.commit()
    return RedirectResponse(row[0], status_code=302)

@app.get("/stats/{code}")
def stats(code: str):
    conn = db()
    row = conn.execute("SELECT url, hits FROM links WHERE code=?", (code,)).fetchone()
    if not row:
        raise HTTPException(status_code=404, detail="code not found")
    return {"code": code, "url": row[0], "hits": row[1]}
```

**`test_main.py`(TestClient 测试):**
```python
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_create_and_redirect():
    r = client.post("/shorten", json={"url": "https://example.com/long/path"})
    assert r.status_code == 200
    code = r.json()["code"]
    redir = client.get(f"/{code}", follow_redirects=False)
    assert redir.status_code == 302
    assert redir.headers["location"] == "https://example.com/long/path"

def test_invalid_url_rejected():
    assert client.post("/shorten", json={"url": "not-a-url"}).status_code == 422

def test_stats_increments_hits():
    code = client.post("/shorten", json={"url": "https://x.io"}).json()["code"]
    client.get(f"/{code}", follow_redirects=False)
    client.get(f"/{code}", follow_redirects=False)
    assert client.get(f"/stats/{code}").json()["hits"] == 2

def test_unknown_code_404():
    assert client.get("/nope").status_code == 404
```

### 5.4 安装依赖、跑测试、起服务

```bash
python -m venv .venv && source .venv/bin/activate     # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pytest -v                                              # 应全绿 4 passed
uvicorn main:app --reload                              # 启动开发服务
```

另开终端验证端到端:

```bash
curl -X POST localhost:8000/shorten -H "Content-Type: application/json" \
     -d '{"url":"https://www.anthropic.com"}'
# {"short_url":"http://localhost:8000/Ab3xZ9","code":"Ab3xZ9"}

curl -i localhost:8000/Ab3xZ9            # HTTP/1.1 302 + Location: https://www.anthropic.com
curl localhost:8000/stats/Ab3xZ9         # {"code":"Ab3xZ9","url":"...","hits":1}
```

### 5.5 提交

回到 Claude Code 会话:

```text
测试全绿了,帮我 commit,描述要清晰。
```

Claude 会读取 diff、生成提交信息并(如已在白名单)执行 `git commit`。若你已装 `gh` CLI,可继续说"开一个 PR"。

> 这就是"首个真实项目"的完整闭环:**安装 → 登录 → 配置(模型/CLAUDE.md/权限)→ 计划模式调研 → 实现 → 测试验证 → 提交**。整个过程你可以走开喝杯咖啡,因为测试是那个可验证的检查。

## 整体工作流程图

```text
flowchart TD
    A[运行原生安装器<br/>curl/irm 一行命令] --> B[claude --version / claude doctor<br/>验证安装]
    B --> C[claude 首次启动 → 浏览器登录<br/>Pro/Max 或 Console]
    C --> D[核心配置三件套]
    D --> D1[/model 选模型]
    D --> D2[/init 生成并精修 CLAUDE.md]
    D --> D3[/permissions 权限白名单 / auto mode / sandbox]
    D1 --> E[计划模式 Plan Mode<br/>先探索再计划]
    D2 --> E
    D3 --> E
    E --> F[退出计划模式 → 照计划编码<br/>FastAPI + Pydantic]
    F --> G[跑可验证检查<br/>pytest / curl]
    G --> H{通过?}
    H -- 否 --> F
    H -- 是 --> I[/commit 提交 + 开 PR]
```

## 延伸阅读

- **官方 Quickstart**:[code.claude.com/docs/en/quickstart](https://code.claude.com/docs/en/quickstart) — 首跑引导官方版
- **Advanced setup**:[code.claude.com/docs/en/setup](https://code.claude.com/docs/en/setup) — 系统要求、各平台安装、版本管理、卸载、签名校验
- **Best practices**:[code.claude.com/docs/en/best-practices](https://code.claude.com/docs/en/best-practices) — 上下文管理、CLAUDE.md、权限、并行扩展
- **CLAUDE.md 记忆**:[code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory) — 放置位置、import 语法、何时改用 Skills/Hooks

## 训练营适用性评估

- **适用类型**:**零基础入门营 / 全栈 Bootcamp 第一课 / 企业内部 AI 编码工具赋能首日**。本教程刻意做到"一行命令装好、一个会话跑通",降低第一天的挫败感。
- **教学时长**:讲师演示 + 学员跟做,**约 45–75 分钟**。其中安装登录 15 分钟、配置三件套 15 分钟、FastAPI 实战 20–40 分钟(取决于学员 Python 基础)。
- **评估验收点**:① `claude doctor` 无报错;② `pytest` 全绿;③ `curl` 端到端拿到 302 与点击数;④ 产出一个干净的 git commit。
- **进阶衔接**:本营结束后可顺接"CLAUDE.md 进阶"、"Skills 开发"、"Hooks 护栏"、"MCP 服务器"等专题营,形成从入门到工程化的完整路径。

## 参考来源

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) — 官方系统要求、各平台原生安装、版本/渠道管理、签名校验、卸载
3. [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) — 官方最佳实践:上下文管理、CLAUDE.md、权限、验证闭环
4. [Claude Code Tutorial 2026: Complete Setup and Workflow Guide](https://baeseokjae.github.io/posts/claude-code-tutorial-2026/) — 第三方完整教程,覆盖安装、记忆、Skills、Hooks、MCP
5. [How to Install Claude Code: Complete Setup Guide (2026)](https://www.nxcode.io/resources/news/install-claude-code-setup-guide-2026) — 第三方 2026 安装与 API key 配置图文指南

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