首页 › tutorials › 原生安装器跑通首个API

概述

前置条件

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

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

操作说明

macOS / Linux / WSL:

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

Windows PowerShell:

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

Windows CMD:

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

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

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 文档)

预期结果

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

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 的错误对照表
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 仍需手动,因要提权)。

二、首次启动与登录

操作说明

在任意目录运行:

claude

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

/login

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

预期结果

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

常见问题

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

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

1. 选择模型

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

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

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

/init

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

# 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)都会请求批准——安全但繁琐。三种降打扰方式,按需选用:

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

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

常见问题

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

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

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

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

# 好(带验证)
写一个 validate_email 函数。示例:[email protected]→True,[email protected]→False。
实现后跑测试并修到全绿。

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

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

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

5.1 建项目并启动 Claude Code

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

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

我要做一个短链接 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:

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 测试):

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 安装依赖、跑测试、起服务

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                              # 启动开发服务

另开终端验证端到端:

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 会话:

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

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

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

整体工作流程图

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]

延伸阅读

训练营适用性评估

参考来源

  1. Quickstart - Claude Code Docs — 官方首跑引导,安装/登录/第一个会话八步走
  2. Advanced setup - Claude Code Docs — 官方系统要求、各平台原生安装、版本/渠道管理、签名校验、卸载
  3. Best practices for Claude Code — 官方最佳实践:上下文管理、CLAUDE.md、权限、验证闭环
  4. Claude Code Tutorial 2026: Complete Setup and Workflow Guide — 第三方完整教程,覆盖安装、记忆、Skills、Hooks、MCP
  5. How to Install Claude Code: Complete 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学通信知识星球海报-扫码加入

📎 本分类最新文章