<!-- title: Claude Code 原生安装与首日配置 -->

## 概述

本教程面向零基础用户，目标是在 macOS、Windows、Linux 三大平台用官方**原生安装器**装好 Claude Code，完成登录认证，建立"用户级—项目级—本地级"三层 `settings.json` 配置体系与权限围栏，并用一个真实可运行的小项目验证整套环境。全程只复制粘贴命令，不需要任何前置经验。适用人群：从未用过命令行的开发者、运维、网优、学生。预计 60 分钟读完并跑通。

## 前置条件

在开始之前，确认你已经具备以下条件：

- **操作系统**：macOS 12+、Windows 10+（强烈建议配合 WSL2）、或主流 Linux 发行版（Ubuntu 20.04+/CentOS 8+）。
- **网络环境**：终端能访问 `claude.ai` 与 `api.anthropic.com`；国内网络通常需要代理。
- **账号**：二选一——Anthropic Console 账号（按 token 计费）或 Claude Pro/Max 订阅账号（包月额度）。
- **终端**：macOS 用系统自带 Terminal 或 iTerm2；Windows 用 PowerShell 或 WSL；Linux 自带。
- **可选**：Node.js 18+，仅在你想用 npm 安装方式时才需要。

> 提示：如果你完全没用过终端，可先通读官方的 Terminal guide for new users（见文末参考来源），它专门为零基础用户讲解如何打开终端。

---

## 第一部分：三平台原生安装

### 1.1 为什么优先用原生安装器

2025 年起，Anthropic 官方主推**原生安装器（native installer）**，相比传统的 `npm install -g @anthropic-ai/claude-code` 有三个明显优势：

1. **不依赖 Node.js**——单文件二进制，下载即用。
2. **不污染全局 npm**——不会在 `npm list -g` 里塞入巨型依赖。
3. **版本自管理**——内置更新器，`claude update` 一键升级，无需手动 `npm install`。

原生安装器首次安装通常 30 秒内完成。下面分平台给出命令。

### 1.2 macOS / Linux / WSL 安装

打开终端，执行：

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

**预期结果**：脚本会下载二进制文件到 `~/.local/bin/claude`（部分系统是 `/usr/local/bin`），并提示你将对应目录加入 `PATH`。安装结束后执行版本检查：

```bash
claude --version
```

正常情况下会输出类似 `2.x.x` 的版本号。

**常见问题与解决**：

| 现象 | 原因 | 解决 |
|------|------|------|
| `claude: command not found` | PATH 未刷新 | `export PATH="$HOME/.local/bin:$PATH"`，并写入 `~/.zshrc` 或 `~/.bashrc` 后 `source` 一次 |
| `curl: (7) Failed to connect to claude.ai` | 网络不通/被墙 | 配置代理：`export https_proxy=http://127.0.0.1:7890` 后重试 |
| 下载到一半中断 | 网络抖动 | 重新执行同一条命令，安装器会续传覆盖 |

### 1.3 Windows PowerShell 安装

以普通用户身份打开 PowerShell（不需要管理员），执行：

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

**预期结果**：脚本把程序下载到 `%LOCALAPPDATA%\Programs\claude`，并自动把该路径写入用户级 `PATH`。**关闭并重新打开**一个 PowerShell 窗口后，`claude --version` 应能正常输出版本号。

**常见问题与解决**：

- **执行策略报错**（`running scripts is disabled`）：执行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`，再重试。
- **中文路径乱码**：把项目目录放在纯英文路径下（如 `D:\projects\`），避免 `C:\Users\张三\` 这类路径。
- **想用 WSL**：在 WSL 里按 1.2 节的 Linux 命令安装，体验更顺滑。

### 1.4 备选：npm 全局安装

如果你所在企业网络只能走内网 npm 镜像、或已经装好 Node.js 18+，也可以用经典方式：

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

国内开发者常配合镜像加速：

```bash
npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code
```

安装后同样执行 `claude --version` 验证。这种方式升级用 `claude update` 或 `npm install -g @anthropic-ai/claude-code@latest`。

---

## 第二部分：登录认证

### 2.1 两条认证路径

Claude Code 支持两种认证方式，按你的账号类型选择：

**路径 A：订阅登录（Pro/Max 包月）**

```bash
claude
```

首次进入会询问认证方式，选择 **Claude account**，终端会输出一个 URL 并尝试自动打开浏览器。在浏览器里完成 claude.ai 授权后，回到终端即登录成功。这种方式按订阅额度计费，**不需要任何 API Key**，最适合个人开发者日常使用。

**路径 B：API Key（按量计费）**

先到 `console.anthropic.com` 创建一个 API Key（以 `sk-ant-` 开头），然后：

```bash
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxxxxx"
claude
```

按 token 用量计费，适合脚本、CI/CD 自动化或多人共享一个 key 的场景。建议把 export 写进 shell 配置文件持久化。

### 2.2 验证登录是否成功

```bash
claude
> /status
```

**预期结果**：`/status` 会显示当前登录账号、所用模型、订阅或 API 状态、剩余额度等信息。看到账号信息即代表登录成功。

**常见问题与解决**：

- **`Invalid API key`**：检查 key 是否完整复制（不要漏掉前缀和尾部字符）、是否包含换行。
- **浏览器没有自动弹出**：手动复制终端里的 URL 粘贴到浏览器。
- **`Unable to verify authentication`**：多为网络问题，确认代理对 `api.anthropic.com` 生效。

---

## 第三部分：三层配置体系

Claude Code 的强大之处在于它的配置是**分层叠加**的。完整优先级从高到低是：企业托管（managed）> 项目本地 > 项目共享 > 用户全局。入门阶段只需掌握后三层。

### 3.1 三个配置文件的位置与职责

| 层级 | 路径 | 用途 | 是否提交 git |
|------|------|------|--------------|
| **用户全局** | `~/.claude/settings.json` | 个人默认值：主题、默认模型、通用放行规则 | 否 |
| **项目共享** | `<项目根>/.claude/settings.json` | 团队统一配置，clone 即生效 | **是** |
| **项目本地** | `<项目根>/.claude/settings.local.json` | 个人覆盖、含密钥的 env，互不干扰 | 否（需 gitignore）|

> 关键认知：**同名配置，高优先级覆盖低优先级**。这意味着你可以把团队规范放项目共享层、把个人密钥放本地层，两者互不污染。

### 3.2 用斜杠命令可视化配置

进入交互会话后，三个命令覆盖 90% 的日常配置需求：

- `/config`——打开设置面板，切换主题、默认模型、通知方式。
- `/permissions`——查看、新增、删除权限规则。
- `/model`——快速切换当前会话模型。

新手优先用斜杠命令，熟练后再直接编辑 JSON 文件。

### 3.3 手写一个用户级 settings.json

用编辑器打开 `~/.claude/settings.json`（不存在就新建），写入：

```json
{
  "model": "claude-sonnet-4-6",
  "theme": "dark",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Read(./**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./**/*.pem)"
    ],
    "defaultMode": "default"
  },
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "8192"
  }
}
```

**权限规则语法**统一为 `ToolName(specifier)`：

- **精确匹配**：`Bash(npm test)` 只放行这一条命令。
- **前缀/通配**：`Bash(npm run *)` 放行所有 `npm run` 脚本。
- **路径范围**：`Read(./src/**)` 放行 `src` 目录下全部文件。
- **deny 优先**：即使 allow 放行了某类操作，deny 仍会拦截。

**四种权限模式**（由 `defaultMode` 或启动参数 `--permission-mode` 控制）：

| 模式 | 行为 | 适用场景 |
|------|------|----------|
| `default` | 每个写操作都询问 | 入门首选，最安全 |
| `acceptEdits` | 自动接受文件编辑，命令仍询问 | 批量改代码 |
| `plan` | 只读规划，绝不改文件 | 方案设计、代码审查 |
| `bypassPermissions` | 跳过所有检查 | 仅限一次性沙箱容器 |

> 安全建议：入门阶段保持 `default`，把危险命令（`rm -rf`、`git push --force`）和敏感文件（`.env`、`*.pem`、`*.key`）写进 `deny`，形成"白名单 + 黑名单"双保险。

---

## 第四部分：第一个项目（实战案例）

目标：从零让 Claude Code 生成一个**"中文 Markdown 转 HTML 预览"的命令行小工具**——单文件、零依赖、可直接运行。整个过程不需要你写一行代码。

### 4.1 建立项目

```bash
mkdir md2html && cd md2html
git init
claude
```

进入交互会话后，你会在 `md2html` 目录里启动 Claude Code。

### 4.2 用一句话下达需求

在交互框里输入：

```
帮我写一个 Node.js 单文件脚本 md2html.js：读取命令行参数指定的 .md 文件，
把标题、无序列表、有序列表、加粗、行内代码、代码块转换成 HTML，
输出同名的 .html 文件，并在终端打印生成路径。不要使用任何第三方依赖，
纯标准库实现。
```

### 4.3 预期结果

Claude Code 会按以下步骤工作：

1. 用 `Write` 工具创建 `md2html.js`。
2. 顺手创建一个 `sample.md` 示例文件方便测试。
3. 询问是否执行 `node md2html.js sample.md`——由于 `defaultMode=default`，这里需要你**按 y 批准**。
4. 批准后生成 `sample.html`，终端打印"已生成 sample.html"。

你可以在新窗口用浏览器打开 `sample.html` 查看渲染效果。

### 4.4 验证与排错

手动复跑一次，确认脚本独立可用：

```bash
node md2html.js sample.md
```

**常见问题与解决**：

- **提示权限被拦（`EACCES` 或 Permission denied）**：在 `/permissions` 面板把 `Bash(node md2html.js *)` 加入 allow；或直接对这一条按 y 放行并选择"始终允许"。
- **生成的 HTML 中文乱码**：回会话里告诉 Claude "在 `<head>` 加上 `<meta charset='utf-8'>`"，它会自动改文件。
- **想要实时预览**：追加一句"加一个 `--watch` 参数，文件变化时自动重新生成"，让 Claude 增强功能。
- **想看它怎么思考**：输入 `/model` 切换模型，或在需求里加"先解释你的实现思路再写代码"。

### 4.5 把权限固化进项目共享配置

为了让团队成员 clone 后共享同一套放行规则，编辑项目根的 `.claude/settings.json`：

```json
{
  "permissions": {
    "allow": [
      "Bash(node md2html.js *)",
      "Bash(git add:*)",
      "Bash(git commit:*)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  }
}
```

然后提交：

```bash
git add .claude/settings.json md2html.js sample.md
git commit -m "init: md2html 工具与项目权限配置"
```

> 同时务必把 `.claude/settings.local.json` 加入 `.gitignore`，避免把个人密钥提交到仓库。这就是"共享层进 git、本地层不进 git"的实践要点。

---

## 工作流程图

下面这张图概括了从环境检查到首项目落地的完整流程，可作为你的"首日上手脚册"打印对照：

```text
flowchart TD
    A[前置检查: 网络 / 账号 / 终端] --> B{选择安装方式}
    B -->|macOS/Linux/WSL| C[curl 原生安装器]
    B -->|Windows| D[irm 原生安装器]
    B -->|已有 Node.js| E[npm 全局安装]
    C --> F[claude --version 验证]
    D --> F
    E --> F
    F --> G[登录认证]
    G --> G1[订阅登录: 浏览器授权]
    G --> G2[API Key: export ANTHROPIC_API_KEY]
    G1 --> H[/status 确认账号]
    G2 --> H
    H --> I[配置: 用户级 settings.json]
    I --> I1[设默认模型 / 主题]
    I --> I2[配 allow 白名单]
    I --> I3[配 deny 黑名单]
    I1 --> J[建项目目录 + git init]
    I2 --> J
    I3 --> J
    J --> K[claude 下需求]
    K --> L[审批权限 + 运行]
    L --> M{验证通过?}
    M -->|否, 继续追问修改| K
    M -->|是| N[权限固化进项目共享配置]
    N --> O[git add + commit]
```

---

## 延伸阅读

- **Claude Code 官方快速入门**：`code.claude.com/docs/en/quickstart`——官方权威的首会话演练。
- **Terminal guide for new users**：`code.claude.com/docs/en/terminal-guide`——零基础如何打开终端、跑通第一条命令。
- **Advanced setup**：`code.claude.com/docs/en/setup`——系统要求、平台细节、版本管理与卸载。
- **Configure permissions**：`code.claude.com/docs/en/permissions`——细粒度权限规则、模式与托管策略的完整说明。
- 进阶可继续关注：CLAUDE.md 项目记忆、Hooks 自动化、Skills 自定义技能、MCP 服务器集成等主题（后续教程展开）。

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适用训练营类型** | "AI 编程入门营""开发者工具速成营""通信/网优工程师 AI 提效营""高校新生数字化素养营" |
| **学员基础要求** | 零基础可学，会复制粘贴命令即可；有终端经验者 30 分钟可跑通 |
| **建议教学时长** | 集中讲授 45 分钟 + 动手实操 60 分钟 + 答疑 15 分钟，共约 2 课时 |
| **交付物** | 每位学员产出一个可运行的 md2html 小工具 + 一份个人 settings.json 配置文件 |
| **考核点** | ① `claude --version` 正常；② `/status` 显示已登录；③ 能用一句话让 Claude 生成并运行代码；④ 能正确区分三层配置文件的提交策略 |
| **常见卡点** | 国内网络代理、Windows 执行策略、API Key 复制不完整——建议讲师提前准备代理与备用账号 |

---

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — 官方快速入门，首会话演练权威流程。
2. [Terminal guide for new users - Claude Code Docs](https://code.claude.com/docs/en/terminal-guide) — 零基础用户打开终端、安装与首次交互的分步指南。
3. [Advanced setup - Claude Code Docs](https://code.claude.com/docs/en/setup) — 系统要求、平台安装细节、版本管理与卸载。
4. [Configure permissions - Claude Code Docs](https://code.claude.com/docs/en/permissions) — 细粒度权限规则、四种模式与可纳入版本控制的托管策略。
5. [How to Install Claude Code in 2026 (Mac, Windows, Linux) - Claudify](https://claudify.tech/blog/install-claude-code) — 三平台原生安装器命令与两分钟快速安装实践。

---

> 本文由「51学通信」站长爱卫生（微信：gprshome201101）整理，聚焦让零基础开发者真正跑通第一个 Claude Code 项目。

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