<!-- title: Claude Code原生安装与首个项目工程化 -->

## 概述

本教程面向**从未用过 Claude Code、但已有基础终端和 Git 经验**的开发者。学习目标只有一个：在 30 分钟内，用 2026 年官方推荐的「原生安装」方式装好 Claude Code，完成正确的认证决策，并把一个真实代码库初始化成「工程化」的 Claude Code 项目——写好 `CLAUDE.md`、配好权限、跑通第一个由 AI 交付的功能。我们不写"hello world"，我们交付一个**可运行、可提交**的功能。

## 前置条件

在开始前，请确认你具备以下基础和环境：

- **终端基础**：能熟练使用 `cd`、`ls`、`git`，知道如何打开命令行。
- **一个代码项目**：任何带 Git 仓库的真实工程（Node、Python、Go、Java 均可），不要求多复杂，但要有结构。
- **账户**：Claude Pro/Max/Team/Enterprise 订阅，**或** Claude Console（API 预付费）账户，**或** 企业云（Amazon Bedrock / Google Vertex AI / Microsoft Foundry）访问权限，三者其一即可。
- **系统要求**：macOS、Linux、WSL 或 Windows（Windows 原生建议预装 Git for Windows，以便 Claude Code 使用 Bash 工具）。
- **可选但强烈推荐**：Visual Studio Code 或 JetBrains IDE（本教程不依赖，但工作流会更顺）。

---

## 核心理念：为什么 2026 年要「原生安装」而非 npm

很多 2024–2025 年的旧教程会教你 `npm install -g @anthropic-ai/claude-code`。这个命令在 2026 年**依然有效**，但已不再是官方首选。原因有三：

1. **依赖污染**：npm 全局安装要求本机有 Node.js ≥ 18，且 Claude Code 版本与全局 npm 包管理纠缠，升级时容易踩版本坑。
2. **自动更新缺失**：npm 全局包不会自动更新，你需要手动 `npm update -g`，容易停留在有已知问题的旧版本。
3. **原生安装更轻**：官方提供的 `curl | bash`、`winget`、`brew --cask`、`apt/dnf/apk` 等原生通道，在后台**自动更新**，始终保持在最新稳定版，且与系统包管理器一致。

> **决策原则**：能用原生安装就用原生安装；只有在受限环境（无 root、无法执行 curl 脚本、必须用 npm 工作区）时才回退到 npm。

---

## 步骤 1：环境准备与系统检查

在安装前，先做一次环境体检，避免后面踩坑。

**macOS / Linux / WSL：**

```bash
# 检查 shell 与基础工具
echo $SHELL          # 期望 /bin/zsh 或 /bin/bash
git --version        # 期望有输出，没有就装 git
which curl           # 必须存在
```

**Windows（PowerShell）：**

```powershell
$PSVersionTable.PSVersion   # 期望 5.1+ 或 PowerShell 7+
git --version               # 推荐安装 Git for Windows
```

**常见问题：**

| 现象 | 原因 | 解决 |
|------|------|------|
| `'irm' is not recognized` | 你在 CMD 里跑了 PowerShell 命令 | 改用 PowerShell，或用 CMD 专用命令 |
| `&& is not a valid statement separator` | 你在 PowerShell 里用了 CMD 语法 | 看提示符：`PS C:\` 是 PowerShell，`C:\` 是 CMD |
| `curl` 不存在（Windows CMD） | Windows CMD 的 curl 是别名 | 用官方提供的 CMD 专用安装脚本 |

> **小贴士**：判断你在哪个 shell 的最快方法——看提示符。`PS C:\Users\you>` 是 PowerShell，`C:\Users\you>` 是 CMD。两者安装命令不同，别混用。

---

## 步骤 2：原生安装——四种主流方式详解

Claude Code 在 2026 年支持以下安装通道，按平台选择即可。

### 方式 A：curl 脚本（macOS / Linux / WSL，官方首选）

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

执行后，脚本会下载与系统架构匹配的二进制，放入用户级目录（通常是 `~/.local/bin` 或 `~/.claude`），并尝试写入 `PATH`。**此方式后台自动更新**，安装完一次即可长期使用。

### 方式 B：Windows 原生

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

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

> 注意：WSL 环境请用方式 A 的 Linux 脚本，**不要**用 Windows 脚本，否则会装到 Windows 侧而非 Linux 发行版内。

### 方式 C：包管理器（brew / winget / apt / dnf / apk）

```bash
# macOS Homebrew
brew install --cask claude-code            # 稳定通道（约滞后一周）
brew install --cask claude-code@latest     # 最新通道
```

```powershell
# Windows WinGet
winget install Anthropic.ClaudeCode
```

```bash
# Linux
sudo apt install claude-code        # Debian/Ubuntu
sudo dnf install claude-code        # Fedora/RHEL
sudo apk add claude-code            # Alpine
```

> **关键差异**：`brew --cask`、`winget`、`apt/dnf/apk` 安装的版本**不会自动更新**，你需要定期手动 `brew upgrade claude-code` / `winget upgrade Anthropic.ClaudeCode`。只有 curl 脚本和 Windows 原生脚本会自动更新。如果你希望"装完不管"，优先选 curl 脚本。

### 方式 D：npm（回退方案，仅限受限环境）

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

需要 Node.js ≥ 18，无自动更新，需手动 `npm update -g @anthropic-ai/claude-code`。

### 验证安装

```bash
claude --version
```

看到版本号输出即安装成功。如果提示 `command not found`，多半是 `PATH` 未生效——重开终端，或手动把安装目录加入 `PATH`。

---

## 步骤 3：多路径认证——新手最容易选错的一步

Claude Code **必须登录**才能使用，但它支持多种账户类型，新手最常在这一步困惑。下面帮你做一次清晰的决策。

### 认证方式全景

| 认证方式 | 适合谁 | 计费模型 | 首次登录行为 |
|---------|-------|---------|------------|
| **Claude Pro/Max/Team/Enterprise**（推荐） | 个人与团队开发者 | 按订阅套餐，Claude Code 用量计入套餐额度 | 浏览器跳转授权 |
| **Claude Console（API）** | 需要精确成本控制、程序化调用的开发者 | 按 token 预付费 credits | 自动创建一个名为 "Claude Code" 的 workspace 用于成本追踪 |
| **Amazon Bedrock / Vertex AI / Microsoft Foundry** | 企业合规、数据驻留要求 | 走云厂商账单 | 需配置环境变量与厂商凭证 |

### 登录操作

安装后，在任意目录执行：

```bash
claude
```

首次运行会提示你选择账户并引导到浏览器完成授权。授权完成后，凭证会**安全存储在本机**，之后无需重复登录。

如果后续要切换账户或重新认证，在已运行的会话内输入：

```
/login
```

### 决策建议

- **不确定选哪个？** 选订阅（Pro/Max）。它最省心，不用算 token，适合 90% 的开发者。
- **公司给你报销 API？** 选 Console。首次登录会自动建好 "Claude Code" workspace，便于集中查成本。
- **公司有数据合规要求？** 选 Bedrock/Vertex/Foundry，让流量走你公司的云账号，不经过 Anthropic 直连。

> **重要**：凭证存储是系统级的（macOS 用 Keychain，Linux 用 Secret Service，Windows 用 Credential Manager）。**不要**把 `ANTHROPIC_API_KEY` 之类的密钥硬编码进 shell 配置文件并提交到 Git——这是新手最常见的安全事故。

---

## 步骤 4：启动首个会话并完成「环境自检」

进入你的项目目录并启动：

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

你会看到一个提示符，上方显示**版本号、当前模型、工作目录**。先做三件事验证环境就绪：

```
/help
```

查看所有可用命令。

```
what can Claude Code do?
```

让 Claude 自述能力，顺便验证它真的读懂了你的项目。

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

这是最关键的自检——如果 Claude 能准确概括你的项目用了哪些技术、入口在哪、目录结构如何，说明它能正常读取你的文件系统，环境完全就绪。

如果这一步 Claude 回答得驴唇不对马嘴，多半是**当前目录不是 Git 仓库根目录**，或目录权限有问题。回到步骤 1 检查 `git status`。

---

## 步骤 5：工程化初始化——把项目"改造"成 Claude Code 项目

这是本教程区别于普通入门教程的核心。光会启动 Claude Code 不够，你要让它在**这个项目里**持续高效、不出格、可复现。三件套缺一不可。

### 5.1 创建 `CLAUDE.md`（项目记忆与规约）

`CLAUDE.md` 是放在仓库根目录的 Markdown 文件，Claude Code 在**每次会话启动时**自动读取它。它相当于给 AI 的"项目说明书 + 行为准则"。

在一个**已有项目**里，最快的生成方式是让 Claude 自己写：

```
/init
```

Claude 会扫描代码库，生成一份初版 `CLAUDE.md` 草稿，覆盖：项目概述、技术栈、常用命令、目录结构、编码规范。**审阅并修订它**，重点补充三块：

1. **绝对规约**：用祈使句写明禁止事项，例如"不要自动 commit"、"修改代码后必须运行 `npm test`"。
2. **常用命令**：把测试、构建、lint 命令列清楚，避免 Claude 瞎猜。
3. **领域知识**：项目特有的业务规则、术语、外部依赖版本约束。

一份合格的 `CLAUDE.md` 不超过 200 行——太长会持续占用上下文窗口，反而拖慢响应、增加成本。

### 5.2 配置 `settings.json` 权限（安全护栏）

Claude Code 默认在修改文件、执行命令前**征求你许可**。但每次都确认很烦。通过 `.claude/settings.json` 可以预授权"安全操作"，把"高危操作"严格拦截。

在项目根目录创建 `.claude/settings.json`：

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Read(//**)",
      "Edit(src//**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Read(.env)",
      "Edit(.env)"
    ]
  }
}
```

**语义说明**：

- `allow`：命中这些模式的命令**自动放行**，不再弹确认。
- `deny`：命中这些模式的命令**直接拒绝**，连确认机会都不给——这是你的"红线"。
- 顺序很重要：`deny` 优先级高于 `allow`，所以即便你 allow 了 `Bash(git:*)`，deny 里的 `Bash(git push:*)` 依然会被拦。

> **权限层级**：Claude Code 的 settings 有三层——用户级（`~/.claude/settings.json`，全局）、项目级（`.claude/settings.json`，进仓库共享）、本地项目级（`.claude/settings.local.json`，不进仓库，存个人偏好）。把团队共识放 `settings.json`，把个人机器差异（比如不同的测试脚本路径）放 `settings.local.json`，并在 `.gitignore` 里忽略后者。

### 5.3 把 `.claude/` 纳入版本控制

```bash
git add CLAUDE.md .claude/settings.json
git commit -m "chore: init Claude Code project context and permissions"
```

这样团队成员 `git pull` 后，开箱即用——同样的规约、同样的权限护栏、同样的记忆。**`settings.local.json` 和 `.env` 永远不要提交。**

---

## 步骤 6：交付第一个功能——并验证工程化是否生效

现在用一个真实小任务验证整条链路。假设你在一个 Node.js 项目里，让它新增一个"健康检查"端点：

```
在 src/routes 下新增一个 health 路由，GET /health 返回 JSON { status: "ok", timestamp: 当前ISO时间 }，
并在 app 入口注册它。完成后运行 npm test 验证，不要自动 commit。
```

**预期行为**：

1. Claude 先读 `CLAUDE.md` 和相关文件，理解项目结构。
2. 它会找到 `src/routes`、找到入口文件。
3. **展示拟修改**，逐个征求你许可（命中 `allow` 的 `Edit(src/**)` 可能自动放行）。
4. 写完代码后，运行 `npm test`（命中 `allow`，自动放行）。
5. **不会**自动 `git commit`——因为 `CLAUDE.md` 里写了禁止，且 `git push` 在 `deny` 里。

如果它试图 `git push` 或读 `.env`，你会看到**权限被拒绝**——这证明你的工程化护栏生效了。如果它试图自动 commit，说明 `CLAUDE.md` 的规约没生效，回去检查文件位置是否在仓库根目录。

---

## 常见问题与排障

**Q：`claude` 命令装完提示 command not found？**
A：`PATH` 没刷新。重开终端；或在当前 shell 手动 `source ~/.zshrc`（macOS）/ `source ~/.bashrc`（Linux）。确认安装路径（curl 脚本会在结束时打印）。

**Q：登录后立刻报 401 / 认证失败？**
A：多半是凭证过期或存储异常。会话内 `/login` 重新授权。企业用户检查 `ANTHROPIC_BASE_URL`、`AWS_PROFILE`、`CLAUDE_CODE_OAUTH_TOKEN` 等环境变量是否冲突。

**Q：公司网络挡住了浏览器跳转？**
A：终端会显示一个 URL 和授权码，手动复制到能上网的浏览器打开，输入授权码即可，不依赖自动跳转。

**Q：Claude 总是自动 commit 怎么办？**
A：`CLAUDE.md` 加一行"不要自动执行 git commit，只在我明确要求时提交"，并检查 `.claude/settings.json` 的 `allow` 里有没有误放 `Bash(git commit:*)`。

**Q：Native 安装和 npm 装的会冲突吗？**
A：会。两者都在 `PATH` 里时，谁在前谁先生效。建议二选一，先 `npm uninstall -g @anthropic-ai/claude-code` 再用原生安装。

**Q：Windows 上 Claude Code 总用 PowerShell 而不是 Bash？**
A：装 Git for Windows。装了之后 Claude Code 会优先用其自带的 Bash，跨平台脚本兼容性更好。

---

## 实战案例：从零交付一个 Express 健康检查端点

把上面所有步骤串起来，下面是一个完整的、可复现的实战。

**起点**：一个最小 Express 项目，结构如下：

```
myapp/
├── package.json
├── src/
│   ├── app.js          # express() 实例
│   └── routes/
│       └── users.js
└── test/
    └── health.test.js  # 空文件，待补充
```

**操作序列：**

1. `cd myapp && claude` 启动。
2. `/init` 生成并修订 `CLAUDE.md`，补入"测试命令 `npm test`、入口 `src/app.js`、禁止自动 commit"。
3. 新建 `.claude/settings.json`，写入上文权限模板。
4. `git add CLAUDE.md .claude/settings.json && git commit -m "init claude code context"`。
5. 输入需求：

```
在 src/routes/ 新建 health.js，导出一个返回 {status:"ok", timestamp} 的 router，
在 src/app.js 注册到 /health，并在 test/health.test.js 用 supertest 写一个通过测试。
完成后跑 npm test，不自动 commit。
```

**预期结果**：Claude 新建 `src/routes/health.js`、修改 `src/app.js`、填充 `test/health.test.js`，运行 `npm test` 全绿，然后把改动留在工作区等你审查——整个流程一气呵成，且全程在权限护栏内。

**预期验证输出（示意）：**

```text
✓ GET /health 返回 200 且 body.status === "ok" (45ms)
1 passing
```

最后你亲自 `git add -A && git commit` 收尾。整个交付从"装好 Claude Code"到"绿测试 + 提交"不超过 30 分钟。

---

## 工作流程图

下面这张图把"从安装到交付首个功能"的完整路径可视化，可作为新手的心智模型。

```mermaid
flowchart TD
    A[环境自检<br/>git/curl/shell] --> B{选择安装方式}
    B -->|macOS/Linux/WSL| C1[curl install.sh]
    B -->|Windows| C2[irm install.ps1]
    B -->|包管理器| C3[brew/winget/apt]
    B -->|受限环境| C4[npm i -g]
    C1 --> D[claude --version 验证]
    C2 --> D
    C3 --> D
    C4 --> D
    D --> E{选择认证方式}
    E -->|个人/团队| F1[Pro/Max 订阅]
    E -->|精确控费| F2[Console API]
    E -->|企业合规| F3[Bedrock/Vertex/Foundry]
    F1 --> G[claude 启动 + 首个会话]
    F2 --> G
    F3 --> G
    G --> H["/init 生成 CLAUDE.md"]
    H --> I[配置 .claude/settings.json 权限]
    I --> J[git commit 工程化基线]
    J --> K[交付首个功能]
    K --> L{护栏是否拦截高危操作?}
    L -->|是| M[✅ 工程化生效]
    L -->|否| N[回查 CLAUDE.md/settings.json]
    N --> I
```

---

## 延伸阅读

- **Claude Code 官方文档首页**：`https://code.claude.com/docs/en/quickstart` —— 安装与认证的权威来源，本教程的基底。
- **Advanced setup**：`https://code.claude.com/docs/en/setup` —— 原生安装各通道、系统要求、企业部署细节。
- **Authentication**：`https://code.claude.com/docs/en/authentication` —— 五种认证路径的完整配置与凭证管理。
- **Explore the `.claude` directory**：官方文档里关于 `settings.json` 三层层级与权限语义的深入说明，工程化初始化的依据。
- 进阶方向：装好后，下一步值得学的是 **Skill 开发**（把重复任务封装成可复用技能）与 **MCP 服务器**（接入外部工具）。这两个主题把 Claude Code 从"助手"升级为"可扩展平台"。

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合的训练营类型** | 全栈/后端开发者入门营、AI 辅助开发训练营、企业内部开发效能培训、大学软件工程实践课 |
| **学员基础要求** | 会用终端和 Git，有一门后端语言基础；零 AI 工具经验可接受 |
| **建议教学时长** | 讲授 + 跟练 **90 分钟**（含 30 分钟实战交付）；可压缩到 60 分钟做"演示版"，或扩展到半天加 Skill/MCP 预习 |
| **实验产出** | 每人交付一个带 `CLAUDE.md` + 权限护栏 + 绿测试的工程化仓库，可作为后续所有课程的统一脚手架 |
| **不适合** | 完全无编程基础的人群（建议先补终端与一门语言）；纯前端且无后端项目可练的学员需另行准备 demo 仓库 |
| **衔接建议** | 本教程作为"第 0 课"，后续直接接 Skill 开发、MCP 集成、CI/CD 自动化三门进阶课 |

---

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速上手指南，本文安装、登录、八步流程的权威依据。
2. [Advanced setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 官方原生安装各通道（curl/winget/brew/apt）与系统要求的细节来源。
3. [Authentication - Claude Code Docs](https://code.claude.com/docs/en/authentication) — 官方认证方式全景，本文多路径认证决策表的依据。
4. [How to Install Claude Code: Complete Setup Guide (2026)](https://www.nxcode.io/resources/news/install-claude-code-setup-guide-2026) — 第三方 2026 安装指南，交叉验证 npm/系统要求/API key 设置。
5. [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) — 社区入门教程，提供从安装到首个项目的实践视角。

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