保姆级 Claude Code 安装教程

📝 本章学习目标

本章聚焦零基础用户，手把手拆解 Claude（Claude Code，Anthropic 推出的 AI 编程助手）的全平台安装、配置、登录与避坑流程。通过本章学习，你将：

• 掌握 Windows/macOS/Linux 三大系统的环境依赖安装；
• 精通 Claude Code 的两种官方安装方式（脚本一键安装、npm 全局安装）；
• 学会环境变量配置、登录认证、国内网络适配等核心操作；
• 解决安装中 90% 的常见报错（权限不足、网络超时、命令未找到等）；
• 完成安装后快速上手基础功能，实现 "从 0 到 1" 使用 Claude Code。

一、引言：为什么选 Claude Code？安装前必看

1.1 Claude Code 核心价值

Claude Code 是 Anthropic 推出的终端 AI 编程工具，基于 Claude 3.5 Sonnet 大模型，主打 "代码生成、项目重构、调试排错、文档编写" 四大核心能力，相比其他 AI 工具，具备 3 大优势：

• 深度代码理解：支持百万行级项目分析，精准理解复杂业务逻辑；
• 终端无缝集成：无需切换窗口，直接在 VS Code、终端中调用，提升开发效率；
• 多模态能力：支持文本、代码、文件上传，可直接生成完整项目结构。

据 2026 年 4 月开发者社区数据，Claude Code 全球安装量超200 万，70% 以上的开发者将其作为日常编程辅助工具，尤其适合前端、后端、全栈开发场景。

1.2 本章结构概览

为确保零基础用户能循序渐进掌握，本章将严格按照 "环境准备→分系统安装→登录配置→国内适配→报错解决→上手使用→进阶优化 " 的逻辑展开，全程无跳跃、无省略，每一步均附命令 + 截图说明 + 注意事项。

plaintext

📊 安装前认知 → 环境依赖安装（Git+Node.js）→ Windows/macOS/Linux分系统安装 → 登录认证与配置 → 国内网络适配 → 常见报错解决 → 基础功能上手 → 进阶优化与最佳实践

1.3 安装前核心须知（必看！）

1. 设备要求：

   • 系统：Windows 10+/macOS 12+/Linux（Ubuntu 20.04+）；
   • 内存：≥4GB（推荐 8GB 及以上，避免模型加载卡顿）；
   • 网络：需联网（登录与 AI 交互需调用 Anthropic 接口，国内需特殊适配）；
   • 权限：安装过程需管理员权限 （Windows）或sudo 权限（macOS/Linux）。

2. 版本要求：

   • Node.js：v18.0+（推荐 v20.x LTS），低版本会导致安装失败或功能异常；
   • Git：v2.30+，用于依赖包拉取与版本控制；
   • Claude Code：优先安装最新稳定版（截至 2026 年 5 月，最新版 v24.13.0）。

3. 费用说明：

   • Claude Code 安装免费，但登录使用需 **Claude Pro 订阅（20 美元 / 月）** 或企业账号，免费版仅支持有限功能。

二、核心概念解析（零基础必懂）

2.1 关键工具定义

• Git：分布式版本控制工具，Claude Code 安装时需依赖 Git 拉取配置文件与依赖包，确保安装过程中资源下载完整。
• Node.js ：基于 Chrome V8 引擎的 JavaScript 运行环境，Claude Code（CLI 工具）强依赖 Node.js 运行，所有安装方式均需先安装 Node.js。
• npm：Node.js 自带的包管理器，用于全局安装 Claude Code 及管理依赖包，无需单独安装，随 Node.js 一起安装。
• Claude Code CLI ：Claude 的终端客户端，安装后可在终端输入claude命令启动，支持对话、代码生成、文件操作等功能。

2.2 安装方式对比（新手推荐优先选 "脚本一键安装"）

表格

安装方式	适用系统	优点	缺点	推荐指数
官方脚本一键安装	macOS/Linux/Windows（PowerShell）	命令极简、自动配置环境变量、无依赖冲突	国内网络可能超时，需特殊适配	⭐⭐⭐⭐⭐
npm 全局安装	全平台	兼容性强、可指定版本、便于升级卸载	需手动配置环境变量、易出现权限报错	⭐⭐⭐⭐

2.3 技术架构概览（简单了解即可）

plaintext

┌─────────────────────────────────────────┐
│              终端/VS Code（用户交互层）  │
│        输入命令/对话 → 输出结果/代码     │
├─────────────────────────────────────────┤
│              Claude Code CLI（核心层）   │
│   解析命令 → 调用本地依赖 → 发起AI请求  │
├─────────────────────────────────────────┤
│              环境依赖层（支撑层）        │
│      Node.js（运行环境）+ Git（资源拉取） │
├─────────────────────────────────────────┤
│              Anthropic云端服务（AI层）    │
│        大模型推理 → 返回结果 → 数据加密  │
└─────────────────────────────────────────┘

三、第一步：环境依赖安装（Git+Node.js，全系统通用）

3.1 安装 Git（版本控制工具）

3.1.1 Windows 系统安装 Git

1. 打开浏览器，访问 Git 官网：https://git-scm.com/；
2. 点击首页 "Download for Windows"，自动下载64 位安装包（Git for Windows/x64 Setup）（若为 ARM64 设备，选择对应版本）；
3. 双击安装包，全程点击 "Next"（默认配置），无需修改任何参数（新手避免自定义配置导致异常）；
4. 安装完成后，取消 "View Release Notes" 勾选，点击 "Finish" 结束安装；
5. 验证安装 ：按下Win+R，输入cmd打开命令提示符，输入以下命令，输出版本号即成功：

bash

运行

git --version
# 示例输出：git version 2.45.1.windows.1

3.1.2 macOS 系统安装 Git

macOS 自带 Git，若未安装或版本过低，通过 Homebrew 安装：

1. 打开 "终端"（Launchpad→其他→终端）；
2. 输入以下命令安装（需联网）：

bash

运行

brew install git

1. 验证安装：终端输入以下命令，输出版本号即成功：

bash

运行

git --version
# 示例输出：git version 2.45.1

3.1.3 Linux 系统（Ubuntu）安装 Git

1. 打开终端，输入以下命令更新软件源：

bash

运行

sudo apt update

1. 输入以下命令安装 Git：

bash

运行

sudo apt install git -y

1. 验证安装：终端输入以下命令，输出版本号即成功：

bash

运行

git --version
# 示例输出：git version 2.45.1

3.2 安装 Node.js（v18+，推荐 v20.x LTS）

3.2.1 Windows 系统安装 Node.js

1. 打开浏览器，访问 Node.js 官网：https://nodejs.org/；
2. 首页选择LTS（长期支持版，推荐 v20.x），点击 "Windows Installer (.msi)" 下载 64 位安装包；
3. 双击安装包，全程点击 "Next"，默认配置即可（自动添加环境变量，无需手动配置）；
4. 安装完成后，验证安装：打开命令提示符（cmd），输入以下命令，均输出版本号即成功：

bash

运行

node --version
# 示例输出：v20.12.2
npm --version
# 示例输出：10.5.0

3.2.2 macOS 系统安装 Node.js

两种方式，推荐 Homebrew 安装（简单无报错）：

方式一：Homebrew 安装（推荐）

1. 打开终端，输入以下命令：

bash

运行

brew install node

1. 验证安装：终端输入以下命令：

bash

运行

node --version
# 示例输出：v20.12.2
npm --version
# 示例输出：10.5.0

方式二：官网下载安装包

1. 访问https://nodejs.org/，下载 macOS LTS 版（.dmg）；
2. 双击安装，拖拽 Node.js 到应用程序，自动配置环境变量；
3. 验证安装（同方式一）。

3.2.3 Linux 系统（Ubuntu）安装 Node.js

1. 打开终端，输入以下命令安装 Node.js（v20.x）：

bash

运行

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install nodejs -y

1. 验证安装：终端输入以下命令：

bash

运行

node --version
# 示例输出：v20.12.2
npm --version
# 示例输出：10.5.0

3.3 环境依赖安装常见报错解决

1. 报错："brew command not found"（macOS）

   • 原因：未安装 Homebrew（macOS 包管理器）；
   • 解决：终端输入以下命令安装 Homebrew：

   bash

   运行

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 报错："node --version 无输出"（Windows）

   • 原因：Node.js 未添加到系统环境变量；
   • 解决：① 右键 "此电脑"→"属性"→"高级系统设置"→"环境变量"；② 在 "系统变量" 中找到 "Path"，点击 "编辑"；③ 新增 Node.js 安装路径（默认：C:\Program Files\nodejs\）；④ 重启命令提示符，重新输入node --version验证。

3. 报错："npm install 权限不足"（macOS/Linux）

   • 原因：当前用户无管理员权限；
   • 解决：命令前加sudo（输入电脑密码，输入时无显示，直接回车即可）。

四、第二步：分系统安装 Claude Code（核心步骤）

4.1 Windows 系统安装 Claude Code（两种方式）

4.1.1 方式一：PowerShell 脚本一键安装（推荐）

1. 按下Win+X，选择 "Windows PowerShell（管理员）"（必须管理员权限，否则报错）；
2. 复制以下命令，粘贴到 PowerShell 中，回车执行：

powershell

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

1. 等待安装完成（全程自动，约 1-3 分钟，取决于网络），无报错即安装成功；
2. 验证安装：PowerShell 中输入以下命令，输出版本号即成功：

powershell

claude --version
# 示例输出：@anthropic-ai/claude-code/24.13.0 win32-x64 node-v20.12.2

4.1.2 方式二：npm 全局安装（备选）

1. 以管理员身份打开 PowerShell 或命令提示符（cmd）；
2. 输入以下命令，执行安装：

bash

运行

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

1. 若报错 "执行策略限制"，先执行以下命令解除限制，再重新安装：

powershell

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

1. 验证安装 ：输入claude --version，输出版本号即成功。

4.2 macOS 系统安装 Claude Code（两种方式）

4.2.1 方式一：终端脚本一键安装（推荐）

1. 打开终端（Launchpad→其他→终端）；
2. 复制以下命令，粘贴到终端，回车执行：

bash

运行

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

1. 等待安装完成（约 1-2 分钟），若提示 "PATH 未配置" ，复制终端给出的echo命令，粘贴回车，自动配置环境变量；
2. 验证安装：终端输入以下命令：

bash

运行

claude --version
# 示例输出：@anthropic-ai/claude-code/24.13.0 darwin-x64 node-v20.12.2

4.2.2 方式二：npm 全局安装（备选）

1. 终端输入以下命令：

bash

运行

sudo npm install -g @anthropic-ai/claude-code

1. 输入电脑密码（输入无显示，直接回车），等待安装完成；
2. 验证安装（同方式一）。

4.3 Linux 系统（Ubuntu）安装 Claude Code

4.3.1 方式一：终端脚本一键安装（推荐）

1. 打开终端，输入以下命令：

bash

运行

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

1. 等待安装完成，若提示权限不足 ，命令前加sudo：

bash

运行

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

1. 验证安装：

bash

运行

claude --version

4.3.2 方式二：npm 全局安装（备选）

1. 终端输入以下命令：

bash

运行

sudo npm install -g @anthropic-ai/claude-code

1. 验证安装（同方式一）。

4.4 安装后必做：配置环境变量（解决 "claude 命令未找到"）

无论哪种安装方式，若输入claude --version提示 "命令未找到"，均为环境变量未配置，按以下步骤解决：

4.4.1 Windows 系统配置环境变量

1. 右键 "此电脑"→"属性"→"高级系统设置"→"环境变量"；
2. 在 "用户变量" 中找到 "Path"，点击 "编辑"；
3. 新增 Claude Code 安装路径（默认：C:\Users\你的用户名\.local\bin）；
4. 重启终端，输入claude --version验证。

4.4.2 macOS/Linux 系统配置环境变量

1. 终端输入以下命令，编辑配置文件：

bash

运行

# macOS
nano ~/.zshrc
# Linux
nano ~/.bashrc

1. 粘贴以下内容（添加环境变量）：

bash

运行

export PATH="$HOME/.local/bin:$PATH"

1. 按Ctrl+O保存，Ctrl+X退出；
2. 终端输入以下命令生效：

bash

运行

# macOS
source ~/.zshrc
# Linux
source ~/.bashrc

1. 验证安装：claude --version。

五、第三步：登录认证与基础配置（安装后必做）

5.1 登录 Claude Code（需 Claude Pro 订阅）

1. 终端（Windows PowerShell/macOS 终端 / Linux 终端）输入以下命令启动 Claude Code：

bash

运行

claude

1. 首次启动自动弹出浏览器登录页面，输入 Anthropic 账号密码登录（无账号需先注册并订阅 Claude Pro，20 美元 / 月）；
2. 登录成功后，返回终端，显示 "Welcome to Claude Code!"，即可开始对话。

5.2 基础配置（修改默认参数）

1. 终端输入以下命令，生成配置文件：

bash

运行

claude config

1. 按提示修改参数（如默认模型、对话温度、最大 token），新手默认即可；
2. 配置文件路径：
   • Windows：C:\Users\你的用户名\.claude.json；
   • macOS/Linux：~/.claude.json。

5.3 国内网络适配（解决登录超时 / 接口请求失败）

国内用户直接登录可能出现 "登录超时 " 或 "AI 请求失败"，需配置网络代理：

5.3.1 Windows 系统配置代理

1. 打开 "设置"→"网络和 Internet"→"代理"；
2. 开启 "使用代理服务器"，输入代理地址和端口（需自行准备合规代理）；
3. 保存后，重新登录 Claude Code。

5.3.2 macOS/Linux 系统配置代理

1. 终端输入以下命令，临时配置代理（重启终端失效）：

bash

运行

# 替换为你的代理地址和端口
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

1. 永久配置（重启生效）：

bash

运行

# macOS
nano ~/.zshrc
# Linux
nano ~/.bashrc
# 粘贴以下内容
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
# 保存生效
source ~/.zshrc  # 或source ~/.bashrc

六、第四步：常见报错全解（90% 问题一站式解决）

6.1 安装阶段报错

1. 报错："curl 命令未找到"（macOS/Linux）

   • 原因：未安装 curl；
   • 解决：

   bash

   运行

   # macOS
   brew install curl
   # Ubuntu
   sudo apt install curl -y

2. 报错："npm ERR! network timeout"（网络超时）

   • 原因：国内网络访问 npm 仓库慢；
   • 解决：切换 npm 镜像为淘宝镜像：

   bash

   运行

   npm config set registry https://registry.npmmirror.com/

3. 报错："权限不足，无法写入文件"（全系统）

   • 解决：Windows 用管理员身份运行终端；macOS/Linux 命令前加sudo。

6.2 启动 / 登录阶段报错

1. 报错："claude 命令未找到"

   • 解决：参考 4.4 节，配置环境变量并重启终端。

2. 报错："登录页面无法打开 / 超时"

   • 解决：参考 5.3 节，配置合规网络代理。

3. 报错："AI 请求失败，接口错误"

   • 原因：未登录或订阅过期；
   • 解决：重新登录，检查 Claude Pro 订阅状态。

6.3 使用阶段报错

1. 报错："模型加载失败，内存不足"

   • 原因：设备内存＜4GB；
   • 解决：关闭其他占用内存的程序，或升级设备内存。

2. 报错："生成代码乱码 / 格式错误"

   • 解决：终端编码设置为 UTF-8：

   bash

   运行

   # Windows PowerShell
   chcp 65001
   # macOS/Linux
   export LC_ALL=en_US.UTF-8

七、第五步：基础功能上手（安装后快速体验）

7.1 发起对话（文本交互）

1. 终端输入claude启动；
2. 直接输入问题，回车发送，示例：

plaintext

你好，我是前端开发者，帮我写一个HTML5登录页面

1. Claude Code 自动返回代码，复制即可使用。

7.2 代码生成（核心功能）

1. 输入指令，指定生成代码的语言和需求，示例：

plaintext

用Vue3写一个待办事项列表，包含新增、删除、标记完成功能

1. 等待 10-30 秒，自动生成完整代码，包含 HTML、CSS、JS。

7.3 文件操作（上传文件分析 / 修改）

1. 终端输入/upload，选择本地文件（支持.js、.py、.txt 等）；
2. 输入指令，如 "帮我分析这个代码的错误并修复"；
3. Claude Code 自动分析文件内容，返回修改后的代码。

八、进阶优化与最佳实践（提升使用体验）

8.1 升级 Claude Code 到最新版

1. 终端输入以下命令：

bash

运行

# 脚本安装升级
curl -fsSL https://claude.ai/install.sh | bash
# npm安装升级
sudo npm install -g @anthropic-ai/claude-code@latest

8.2 卸载 Claude Code

1. 脚本安装卸载：

bash

运行

# macOS/Linux
rm -rf ~/.local/bin/claude
rm -rf ~/.claude.json
# Windows
rm -rf C:\Users\你的用户名\.local\bin\claude
rm -rf C:\Users\你的用户名\.claude.json

1. npm 安装卸载：

bash

运行

npm uninstall -g @anthropic-ai/claude-code

8.3 最佳实践

1. 优先用脚本一键安装：减少环境变量配置麻烦，兼容性更强；
2. 国内用户必配置代理：避免登录超时和 AI 请求失败；
3. 定期升级版本：获取最新功能和 bug 修复；
4. 大文件分批上传：避免内存不足导致卡顿。

九、本章小结

9.1 核心要点回顾

✅ 环境准备 ：全系统安装 Git（v2.30+）和 Node.js（v18+，推荐 v20.x LTS），验证版本无误；✅ 分系统安装 ：Windows 用 PowerShell 脚本 /npm 安装，macOS/Linux 用终端脚本 /npm 安装，管理员 /sudo 权限 是关键；✅ 环境变量配置 ：解决 "claude 命令未找到"，全系统通用配置方法；✅ 登录与适配 ：需 Claude Pro 订阅，国内用户配置代理解决网络问题；✅ 报错解决 ：覆盖安装、启动、使用阶段 90% 常见问题，一站式排查；✅ 上手与优化：掌握对话、代码生成、文件操作核心功能，定期升级提升体验。

9.2 零基础学习建议

1. 循序渐进：先完成环境依赖安装，再执行 Claude Code 安装，每一步验证成功后再进行下一步；
2. 复制命令：避免手动输入命令出错，直接复制教程中的命令粘贴到终端；
3. 善用报错解决：遇到问题先查看第六章报错解决，90% 问题可快速解决；
4. 多动手实践：安装完成后，多尝试对话、代码生成，熟悉 Claude Code 的使用逻辑。

9.3 下一章预告

下一章将深入讲解 Claude Code 的高级功能，包括：自定义指令配置、多文件项目生成、VS Code 插件集成、API 调用等，帮助你充分发挥 Claude Code 的编程辅助能力，提升开发效率。

十、课后练习（巩固所学）

练习一：环境依赖验证

1. 检查本机 Git 和 Node.js 版本，确保符合要求；
2. 若版本过低，完成升级并重新验证。

练习二：Claude Code 安装实操

1. 按照本章教程，在本机完成 Claude Code 安装；
2. 验证安装成功（claude --version输出版本号）；
3. 启动 Claude Code，完成登录（有订阅前提下）。

练习三：基础功能体验

1. 发起对话，让 Claude Code 介绍自己的功能；
2. 生成一段简单代码（如 HTML 页面、Python 函数）；
3. 上传一个本地文件，让 Claude Code 进行分析。

十一、参考资料

官方文档

1. Claude Code 官网：https://claude.com/product/claude-code；
2. 官方安装指南：https://claude.ai/install.sh；
3. Node.js 官网：https://nodejs.org/；
4. Git 官网：https://git-scm.com/。

推荐社区

1. Anthropic 开发者社区：https://console.anthropic.com/community；
2. GitHub Claude Code 仓库：https://github.com/anthropic-ai/claude-code；
3. 国内开发者社区（掘金、知乎）：搜索 "Claude Code 安装教程"，获取更多实操经验。