<!-- title: 免Node原生装通Claude Code -->

# 免装 Node：用原生安装器跑通 Claude Code 首个项目

## 概述

本教程面向**完全零基础**的新手，目标是用 2026 年官方推荐的**原生安装器（Native Installer）**在 10 分钟内装通 Claude Code，并完成第一个可运行的项目。你将学到：为什么现在不再需要 Node.js 和 npm、三平台（macOS / Linux / Windows）的一键安装命令、登录认证与配置体系、第一段对话与第一次代码改动，以及用 Claude Code 从零写出一个"下载文件夹自动整理器"。全程无需任何前置编程经验，跟着命令复制粘贴即可。

## 适用人群与前置条件

**适用人群**：第一次接触命令行工具、第一次使用 AI 编程助手、想快速验证 Claude Code 是否值得长期使用的人。

**前置条件**：

- 一台 macOS 13+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+ 或 Alpine 3.19+ 的电脑，内存 4GB 以上。
- 一个能联网的终端（macOS 的"终端"、Windows 的"PowerShell"、Linux 的 shell）。
- 一个 Anthropic 账号：Claude Pro / Max / Team / Enterprise 订阅、或 Console（API 预付额度）、或 Bedrock / Vertex / Foundry 企业云、或公司自建的 Claude apps gateway（SSO）。
- **不需要**安装 Node.js、npm、Git（虽然推荐装 Git for Windows，下文会解释）。

> 这是本教程最大的"反直觉"点：旧版教程几乎都以 `npm install -g @anthropic-ai/claude-code` 开头，要求你先装一整套 Node 运行时。2026 年起，官方文档已把**原生安装**列为**推荐（Recommended）**方式，npm 退居备选。

## 第一步：理解三种安装方式，并选原生

在动手之前，先花两分钟搞清楚"我到底在装什么"。Claude Code 现在有四条主流安装路径，区别如下：

| 方式 | 是否需要 Node.js | 是否自动更新 | 适用平台 | 推荐度 |
|------|:---:|:---:|------|:---:|
| 原生安装器 | 否 | 是（后台静默） | macOS / Linux / Windows / WSL | ⭐⭐⭐⭐⭐ |
| Homebrew | 否 | 否（手动 `brew upgrade`） | macOS / Linux | ⭐⭐⭐⭐ |
| WinGet | 否 | 否（手动 `winget upgrade`） | Windows | ⭐⭐⭐⭐ |
| apt / dnf / apk | 否 | 否（跟随系统包管理） | Debian / Fedora / RHEL / Alpine | ⭐⭐⭐ |
| npm | **是**（需 Node 18+） | 半自动 | 全平台 | ⭐⭐ |

**原生安装器的三个核心优势**：

1. **零依赖**：安装脚本会下载一个把整个运行时打包进来的独立二进制，不再依赖系统里的 Node 版本，也就不会出现"Node 升级后 Claude Code 突然不能用"的问题。
2. **后台自动更新**：原生安装会在后台保持最新版本，你不用每隔几天手动 `npm update`，也不会被某个有重大回退的版本坑到。
3. **环境干净**：不会往全局 `node_modules` 里塞东西，卸载也只需一条命令，不污染系统。

**什么时候才选 npm？** 只有当你身处一个被锁死的内网环境、必须用私有 npm registry 镜像，或团队已有 Node 工具链流水线时，才退回到 npm。

## 第二步：用一行命令完成原生安装

根据你的操作系统，复制对应的一条命令到终端执行即可。

**macOS / Linux / WSL**：

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

**Windows PowerShell**（推荐，现代 Windows 默认终端）：

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

**Windows CMD**（如果你还在用老式命令提示符）：

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

> **怎么判断我在哪个终端？** 提示符前面带 `PS`（例如 `PS C:\Users\you>`）就是 PowerShell，用第二条命令；只有 `C:\Users\you>` 就是 CMD，用第三条。在 PowerShell 里敲 `&&` 会报错 "The token '&&' is not a valid statement separator"，这正是你用错终端的信号。

**预期结果**：脚本会下载约几十 MB 的二进制，安装到用户目录下，并把 `claude` 命令加入 PATH。安装完成后，终端通常会提示你"重开一个终端"或"重新加载 shell 配置"以让 PATH 生效。重开后输入：

```bash
claude --version
```

看到一串版本号（例如 `2.1.181` 之类）就说明二进制已就位。

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

- **报错 `syntax error near unexpected token '<'` 或 HTTP 403**：通常是 `curl` 被代理或防火墙改写，或下载到了一个 HTML 错误页。先排查代理设置（见下文环境变量），再重试；若依旧失败，参考官方"Troubleshoot installation"页对照错误码。
- **重开终端后 `claude: command not found`**：PATH 没刷新。手动 `source ~/.zshrc`（macOS）或 `source ~/.bashrc`（Linux），或干脆注销重新登录。
- **Windows 提示 `irm is not recognized`**：说明你在 CMD 里，改用上面的 CMD 命令；或直接用 PowerShell。
- **Windows 上 Bash 工具不可用**：原生 Windows 下，Claude Code 默认用 Bash 工具执行命令；若没装 Git for Windows，它会自动降级为用 PowerShell 作为 shell 工具。建议装一个 [Git for Windows](https://git-scm.com/download/win) 以获得最佳体验；WSL 用户则无需关心。

## 第三步：首次登录认证

在任意目录下启动交互式会话：

```bash
claude
```

首次运行会提示你登录。根据账号类型，有四种主流方式：

1. **Claude 订阅（Pro / Max / Team / Enterprise）**：推荐，按提示在浏览器里完成授权，凭据会保存在本地，之后无需重复登录。
2. **Console（API 预付额度）**：登录后系统会自动在 Console 里建一个名为 "Claude Code" 的 workspace，方便集中查看花费。
3. **企业云（Bedrock / Vertex AI / Foundry）**：通过环境变量切换，下文配置环节会讲。
4. **公司自建 gateway（SSO）**：管理员预先配好 gateway URL，`/login` 会直接跳到企业 SSO 登录页。

登录后想换账号或重新认证，在运行中的会话里输入：

```
/login
```

**常见问题**：如果你所在地区不在 Anthropic 支持范围内，登录会失败；这种情况下可考虑通过 Bedrock / Vertex 等受支持的云渠道接入，或使用公司自建的 gateway。

## 第四步：建立配置心智模型（新手最容易跳过的一步）

很多人装完就直接开干，结果项目里的设置和全局设置打架。Claude Code 的配置遵循一套**作用域（Scope）优先级**，理解它能少踩 80% 的坑：

```
Managed（最高，企业强制，不可被覆盖）
   ↓
命令行参数（临时会话覆盖）
   ↓
Local（本地，仅当前仓库、自己用）
   ↓
Project（项目，提交到 git、全队共享）
   ↓
User（最低，你自己所有项目通用）
```

对应的物理文件位置：

| 作用域 | 文件 / 位置 | 影响范围 | 是否随 git 共享 |
|------|------|------|:---:|
| User | `~/.claude/settings.json` | 你自己，所有项目 | 否 |
| Project | `.claude/settings.json` | 仓库的所有协作者 | 是 |
| Local | `.claude/settings.local.json` | 你自己，仅当前仓库 | 否（自动 gitignore） |
| Managed | 服务器下发 / plist / 注册表 / system managed-settings.json | 全组织 / 全机 | 由 IT 部署 |

**新手最常用的两个配置入口**：

1. **`/config` 命令**：在会话里输入 `/config` 打开标签式设置界面，可查看状态、改主题、改模型等。从 v2.1.181 起，还能直接单条修改：`/config verbose=true`。
2. **环境变量**：写到 `~/.claude/settings.json` 的 `env` 字段，或直接 export 到 shell。新手最该知道的几个：

| 变量 | 作用 |
|------|------|
| `ANTHROPIC_API_KEY` | 用 API Key 认证（替代交互登录） |
| `ANTHROPIC_MODEL` | 指定默认模型，例如 `claude-sonnet-4-6` |
| `ANTHROPIC_BASE_URL` | 自定义 API 端点（走代理 / 网关时用） |
| `CLAUDE_CODE_USE_BEDROCK` / `CLAUDE_CODE_USE_VERTEX` | 设为 `1` 切换到 Bedrock / Vertex |
| `MAX_THINKING_TOKENS` | 控制推理（思考）预算 |
| `DISABLE_AUTOUPDATER` | 设为 `1` 关闭自动更新 |

**企业内网 / 代理场景**：如果你必须走公司代理，可在 `~/.claude/settings.json` 里这样写：

```json
{
  "env": {
    "HTTPS_PROXY": "http://proxy.company.com:8080",
    "HTTP_PROXY": "http://proxy.company.com:8080"
  }
}
```

**常见问题**：设置了 `ANTHROPIC_MODEL` 却没生效？检查是否被 Project 或 Local 层的同名设置覆盖了——优先级是 Local > Project > User。

## 第五步：开启第一段对话

进入你打算工作的项目目录（没有项目也没关系，新建一个空文件夹即可）：

```bash
mkdir ~/hello-cc && cd ~/hello-cc
claude
```

启动后会看到版本号、当前模型和工作目录显示在提示符上方。先输入：

```
/help
```

你会看到所有可用命令。然后试着用自然语言提问——Claude Code 会按需读取你的文件，你**不需要手动喂上下文**：

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

**常用会话命令速查**：

| 命令 | 作用 |
|------|------|
| `/clear` | 清空当前对话历史（释放上下文） |
| `/help` | 查看命令列表 |
| `/login` | 切换 / 重新认证账号 |
| `/config` | 打开设置界面 |
| `/exit` 或 `Ctrl+D` | 退出 Claude Code |
| `/resume` | 恢复之前的某段对话 |

**Shell 层（终端里直接敲）也记住这几条**：

```bash
claude                    # 启动交互模式
claude "修一下构建报错"     # 跑一次性任务后退出
claude -p "解释这个函数"    # 单次查询模式（适合脚本）
claude -c                 # 继续当前目录最近的对话
claude -r                 # 恢复历史对话
```

**新手提示**：提问要具体。与其说"修一下 bug"，不如说"修复用户输错密码后看到白屏的登录 bug"——细节越足，结果越准。

## 第六步：第一次代码改动与权限机制

让 Claude Code 真正动起来：

```
add a hello world function to the main file
```

它会：找到合适的文件 → 展示拟修改的 diff → **请求你批准** → 执行编辑。Claude Code 在改文件前**永远会先征求许可**，你可以逐条批准，也可以为整个会话开启 "Accept all"（全部接受）模式。

> **权限模式简述**：默认是"逐条放行"；想批量信任某类只读操作（如 `npm test`、`git status`），可在 `/config` 里把对应命令加入 allow 列表，减少打扰。生产环境建议保持默认谨慎模式，不要无脑全开。

## 第七步：用自然语言玩转 Git

Claude Code 把 Git 变成了对话：

```
what files have I changed?          # 我改了哪些文件
commit my changes with a message    # 用合适的信息提交
create a new branch called feature/cleanup
show me the last 5 commits
help me resolve merge conflicts     # 帮我解决冲突
```

它会替你执行 `git` 命令并解释结果，对新手非常友好。

---

## 完整工作流：一张图看懂从安装到出活

```text
flowchart TD
    A[选择安装方式<br/>原生 / Homebrew / WinGet / npm] --> B[运行一行安装命令]
    B --> C[claude --version<br/>验证二进制就位]
    C --> D[claude 首次启动<br/>浏览器登录认证]
    D --> E[/config 与 settings.json<br/>配置作用域与代理]
    E --> F[cd 进入项目目录<br/>claude 启动会话]
    F --> G[自然语言提问<br/>理解代码库]
    G --> H[描述任务<br/>审阅 diff → 批准]
    H --> I[Git 提交 / 测试<br/>收尾]
    I --> J{满意?}
    J -->|否| G
    J -->|是| K[交付]
```

---

## 实战案例：从零造一个"下载文件夹自动整理器"

我们把前面学的全部串起来，做一个真实可用的小工具：自动把混乱的 `~/Downloads` 按文件类型分拣到 `图片/文档/安装包/压缩包/其他` 子文件夹。

### 1. 准备工作目录

```bash
mkdir ~/dl-organizer && cd ~/dl-organizer
claude
```

### 2. 把需求"说人话"地告诉 Claude Code

在会话里粘贴：

```
帮我用 Python 写一个下载文件夹整理器 organize.py：
1. 默认目标目录是 ~/Downloads，可用 --target 参数覆盖。
2. 按扩展名分到这些子文件夹：图片(.jpg/.png/.gif/.webp)、文档(.pdf/.docx/.xlsx/.pptx/.txt/.md)、安装包(.dmg/.exe/.msi/.deb)、压缩包(.zip/.tar/.gz/.rar/.7z)，其余归入"其他"。
3. 用 --dry-run 预览要移动的文件但不真正移动。
4. 移动前打印日志，遇到同名文件自动加 _1、_2 后缀避免覆盖。
5. 代码要带中文注释，并配一个 run.sh 示例脚本。
```

### 3. 预期产出（Claude Code 会生成类似下面的代码）

**`organize.py`**（节选）：

```python
#!/usr/bin/env python3
"""下载文件夹自动整理器：按扩展名把文件分拣到子文件夹。"""
import argparse
import shutil
from pathlib import Path

# 扩展名 → 目标子文件夹的映射表
CATEGORIES = {
    "图片":   [".jpg", ".jpeg", ".png", ".gif", ".webp"],
    "文档":   [".pdf", ".docx", ".xlsx", ".pptx", ".txt", ".md"],
    "安装包": [".dmg", ".exe", ".msi", ".deb"],
    "压缩包": [".zip", ".tar", ".gz", ".rar", ".7z"],
}

def classify(suffix: str) -> str:
    """根据扩展名返回归类名，匹配不到则返回'其他'。"""
    for name, exts in CATEGORIES.items():
        if suffix.lower() in exts:
            return name
    return "其他"

def unique_path(dest_dir: Path, filename: str) -> Path:
    """若目标已存在同名文件，自动追加 _1、_2 后缀。"""
    target = dest_dir / filename
    if not target.exists():
        return target
    stem, ext = Path(filename).stem, Path(filename).suffix
    i = 1
    while True:
        candidate = dest_dir / f"{stem}_{i}{ext}"
        if not candidate.exists():
            return candidate
        i += 1

def main():
    parser = argparse.ArgumentParser(description="整理下载文件夹")
    parser.add_argument("--target", default=str(Path.home() / "Downloads"))
    parser.add_argument("--dry-run", action="store_true", help="只预览不移动")
    args = parser.parse_args()

    root = Path(args.target).expanduser()
    if not root.is_dir():
        raise SystemExit(f"目录不存在: {root}")

    moved = 0
    for f in root.iterdir():
        if not f.is_file():
            continue
        category = classify(f.suffix)
        dest_dir = root / category
        dest_dir.mkdir(exist_ok=True)
        dest = unique_path(dest_dir, f.name)
        action = "预览移动" if args.dry_run else "移动"
        print(f"[{action}] {f.name} -> {category}/{dest.name}")
        if not args.dry_run:
            shutil.move(str(f), str(dest))
        moved += 1
    print(f"完成，共处理 {moved} 个文件。")

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

**`run.sh`**：

```bash
#!/usr/bin/env bash
# 先预览，确认无误后再去掉 --dry-run 真正执行
python3 organize.py --target ~/Downloads --dry-run
```

### 4. 让 Claude Code 帮你自测

```
帮我建一个临时测试目录 /tmp/dltest，放几个假文件（a.png、report.pdf、setup.exe、x.zip、weird.xyz），然后跑 organize.py --target /tmp/dltest 验证分拣结果，最后把测试目录删掉。
```

你会看到 Claude Code 自动执行 Bash 工具、打印分拣日志、确认每个文件落到了正确子文件夹。这种"描述意图 → 它写代码 → 它跑测试 → 你看结果"的闭环，正是 Claude Code 的核心用法。

### 5. 收尾

```
用 git 初始化仓库，写一个简短 README，然后提交。
```

至此，你已经完整走过了：安装 → 登录 → 配置 → 提问 → 生成代码 → 自测 → Git 交付的全流程。

---

## 新手高频踩坑速查

| 现象 | 原因 | 解决 |
|------|------|------|
| `claude: command not found` | PATH 未刷新 | `source ~/.zshrc` 或重开终端 / 重登录 |
| 装完不更新 | 用了 Homebrew / WinGet / apt | 手动 `brew upgrade claude-code` / `winget upgrade ...` |
| 登录卡住 / 403 | 地区不支持或代理拦截 | 走 Bedrock/Vertex，或配 `HTTPS_PROXY` |
| 设置改了没生效 | 被更高优先级作用域覆盖 | 按 Managed>CLI>Local>Project>User 逐层排查 |
| 命令总被打断要确认 | 权限逐条放行 | 在 `/config` 把只读命令加入 allow 列表 |
| Windows 里 Bash 工具缺失 | 没装 Git for Windows | 装 Git for Windows，或接受降级为 PowerShell |

---

## 延伸阅读

- **官方 Quickstart（最权威的入门）**：<https://code.claude.com/docs/en/quickstart>
- **官方 Advanced Setup（系统要求 / 多平台 / 卸载）**：<https://code.claude.com/docs/en/setup>
- **官方 Settings（配置作用域与环境变量）**：<https://code.claude.com/docs/en/settings>
- **Claude Code Tutorial for Beginners 2026（第三方完整图文教程）**：<https://dev.to/ayyazzafar/claude-code-tutorial-for-beginners-2026-from-installation-to-building-your-first-project-1lma>
- **How to Install Claude Code: Complete Setup Guide 2026**：<https://www.nxcode.io/resources/news/install-claude-code-setup-guide-2026>

---

## 训练营适用性评估

- **适合的训练营类型**：面向在校生、转行开发者、企业新员工的"AI 编程启蒙营""DevOps 入门营""效率工具上手营"；也适合作为任何进阶训练营（Skill 开发、MCP 开发、自动化）的第 0 课前置。
- **教学时长**：约 **1.5–2 小时**（讲解 30 分钟 + 跟练 60 分钟 + 排障答疑 30 分钟）。建议每位学员现场跑通"下载文件夹整理器"作为结业小作业。
- **分组建议**：按操作系统分组（mac / Win / Linux），每组配一名熟悉该平台 PATH 与代理配置的助教，可把现场排障时间压缩一半。

## 参考来源

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. [Claude Code settings - Claude Code Docs](https://code.claude.com/docs/en/settings) — 配置作用域、settings.json、环境变量清单。
4. [How to Install Claude Code: Complete Setup Guide 2026 — nxcode.io](https://www.nxcode.io/resources/news/install-claude-code-setup-guide-2026) — 第三方 2026 多平台安装图文指南。
5. [Claude Code Tutorial for Beginners 2026 — dev.to](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)