Claude Code 完整安装与配置指南（含 CC-Switch 多供应商切换工具）

Claude Code 完整安装与配置指南（含 CC-Switch 多供应商切换工具）

前言

Claude Code 是由 Anthropic 推出的终端级 AI 编程助手，能够让开发者通过自然语言进行代码生成、代码审查、Git 提交管理等操作。本文将详细介绍从环境准备到完整运行 Claude Code 的全部步骤，并对每个操作解释其背后的原因，帮助新手不仅知道"怎么装"，更理解"为什么这样装"。

环境要求：Node.js 18.0 及以上版本，支持 Windows 10/11、macOS 10.15+ 及主流 Linux 发行版。

---

第一步：下载并安装 Node.js

操作步骤

访问 Node.js 中文镜像站下载安装包：

📦 下载地址：https://nodejs.cn/download/

选择 LTS（长期支持）版本 ，下载对应系统的安装包（Windows 选 .msi，macOS 选 .pkg），双击运行，一路点击 "Next" 完成安装。

安装完成后，打开终端（CMD / PowerShell / Git Bash），验证安装是否成功：

node --version
npm --version

如果两条命令都能正常输出类似 v20.xx.x 和 10.xx.x 的版本号，说明安装成功。

为什么需要这一步？

Claude Code 是一个基于 Node.js 构建的 CLI 工具，它依赖 Node.js 的 JavaScript 运行时环境和 npm（Node Package Manager）包管理器来下载、安装和运行。简单来说，没有 Node.js，npm 就无法工作，而 Claude Code 必须通过 npm 来安装。

选择 LTS 版本 而非最新版的原因是：LTS 版本经过了长期的稳定性验证，在生产环境和企业开发中兼容性最好，能有效避免因 Node.js 自身 Bug 导致的安装失败或运行异常。

使用 nodejs.cn 而非 nodejs.org 下载，是因为官方网站在国内访问速度较慢甚至可能无法打开，中文镜像站提供了完全一致的安装包，下载速度更快。

---

第二步：通过 npm 安装 Claude Code

2.1 设置 npm 淘宝镜像源（永久生效）

在终端中执行以下命令：

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

可以验证是否配置成功：

npm config get registry
# 应输出：https://registry.npmmirror.com/

为什么需要这一步？

npm 的默认官方源 https://registry.npmjs.org 服务器位于海外，国内用户访问时经常遇到下载速度极慢甚至超时中断的问题。registry.npmmirror.com 是淘宝团队维护的国内高速镜像，同步频率高、覆盖完整，能大幅提升包的下载速度。

npm config set 命令会将镜像源地址写入用户级的 npm 配置文件（~/.npmrc），因此只需要执行一次，之后所有 npm 安装都会自动走国内镜像，无需每次手动指定。

⚠️ 重要提示 ：旧版淘宝镜像地址 registry.npm.taobao.org 已废弃，请务必使用新地址 registry.npmmirror.com。

2.2 全局安装 Claude Code

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

参数说明：

• install（可简写为 i）：安装指定的包
• -g（global）：全局安装，安装后的命令可在系统任意目录下使用
• @anthropic-ai/claude-code：Claude Code 的 npm 包名

为什么是全局安装？

带 -g 参数的全局安装会将 Claude Code 的可执行文件注册到系统 PATH 环境变量中。这意味着无论你当前在哪个项目目录，都可以直接在终端中输入 claude 来启动它，无需在每个项目中重复安装。

如果省略 -g（本地安装），Claude Code 只会被安装到当前项目的 node_modules 目录中，无法在全局范围调用。

2.3 验证安装

claude --version

如果输出版本号（如 v1.0.xx），说明安装成功。

如果提示 'claude' 不是内部或外部命令，常见原因及解决方案：

• Windows 用户：确保以管理员身份运行终端，或检查 Node.js 是否正确加入 PATH
• 权限问题：可以尝试重新执行安装命令，或检查 npm 全局安装路径的权限设置

---

第三步：安装 CC-Switch 配置管理工具（可选但推荐）

操作步骤

访问 CC-Switch 的 GitHub Releases 页面，下载对应系统的安装包：

📦 下载地址：https://github.com/farion1231/cc-switch/releases/download/v3.14.1/CC-Switch-v3.14.1-Windows.msi

（macOS 用户可下载 .dmg 文件，Linux 用户可下载 .deb 或 .AppImage 文件）

下载完成后双击安装包，按提示完成安装。

什么是 CC-Switch？为什么推荐安装？

CC-Switch 是一款跨平台桌面应用，用于统一管理和切换 Claude Code 的供应商配置 。如果你使用过 Claude Code，一定体验过手动编辑 settings.json 配置文件来填写 API Key 和 Base URL 的繁琐过程。

CC-Switch 内置了 50+ 供应商预设（包括 Anthropic 官方、SiliconFlow、OpenAI 等），选择预设后只需填写 API Key，一键即可生效。它的核心功能包括：

• 供应商一键切换：主界面或系统托盘秒级切换不同 API 供应商
• MCP 统一管理：跨应用管理 MCP 服务器配置
• 用量统计：Token 消耗追踪与成本监控
• 提示词管理 ：Markdown 编辑器，同步到 CLAUDE.md 文件

对于需要同时使用多个 API 供应商（如开发环境用官方、生产环境用第三方中转）的开发者来说，CC-Switch 可以大幅简化配置管理工作。

配置 API Key

打开 CC-Switch 桌面应用：

1. 在顶部应用切换器中，确认当前选中的是 Claude
2. 点击右上角的 + 按钮，打开添加供应商面板
3. 在「预设」下拉框中选择对应的供应商（如 Anthropic、SiliconFlow 等）
4. 填写你的 API Key
5. 保存配置，切换到新配置即可生效

💡 获取 API Key 的方式：

• 官方渠道：登录 Anthropic Console（https://console.anthropic.com），在 API Keys 页面创建密钥
• 第三方供应商（如 SiliconFlow）：登录对应平台的控制台，在 API 密钥管理页面获取

---

第四步：在项目文件夹中启动 Claude Code

操作步骤

在终端中进入你要开发的项目的根目录：

cd /path/to/your-project
claude

首次启动时，Claude Code 会引导你完成以下初始化流程：

1. 选择喜欢的主题（dark / light）
2. 确认安全须知
3. 选择默认的终端配置
4. 信任当前工作目录
5. 验证 API 连接是否正常

启动成功后，你就可以在终端中通过自然语言与 Claude Code 交互了。

为什么要在项目文件夹中运行？

Claude Code 是上下文感知的 AI 编程助手。当你从项目根目录启动它时，它会自动将整个项目的文件结构和代码作为上下文，从而能够：

• 理解项目架构和依赖关系
• 直接读取、修改项目中的文件
• 执行 git 命令管理版本
• 在项目目录下创建 .claude/CLAUDE.md 记忆文件，记录项目信息

如果不在项目目录中启动，Claude Code 没有可操作的代码上下文，大部分核心功能无法正常使用。

常用启动命令速查

命令	用途
claude	启动交互模式，进入对话式编程
claude "your task"	运行一次性任务，完成后返回结果
claude -p "query"	运行查询后自动退出
claude -c	继续最近的对话
claude commit	自动分析更改并创建 Git 提交

---

补充说明：npm 安装与原生安装的区别

本文介绍的 npm 安装方式是目前最通用、文档最丰富的安装方法，适合所有平台。不过需要说明的是，Anthropic 在 2026 年已推出原生安装方式，无需 Node.js 依赖，安装更简洁，且支持自动更新。

原生安装方式（适用于各平台）：

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

# Windows（PowerShell）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

如果你追求最新体验，可以尝试原生方式；如果希望最大程度兼容现有文档和教程，npm 方式依然是可靠的选择。两种方式安装的 Claude Code 功能完全一致。

---

常见问题排查

Q1：安装时报权限错误（Windows）

以管理员身份运行命令提示符或 PowerShell，然后重新执行安装命令。

Q2：claude 命令找不到

检查 npm 全局安装路径是否在系统 PATH 中：

npm root -g

Windows 下默认路径通常为 C:\Users\你的用户名\AppData\Roaming\npm，确保该路径已添加到系统环境变量中。

Q3：切换镜像后安装依然很慢

可以尝试清除 npm 缓存后重试：

npm cache clean --force

---

总结

步骤	核心操作	原因
安装 Node.js	从国内镜像下载 LTS 版本	Claude Code 的运行基础环境
配置淘宝镜像源	npm config set registry	加速国内 npm 包的下载
安装 Claude Code	npm install -g @anthropic-ai/claude-code	全局安装，可在任意目录使用
安装 CC-Switch	下载桌面应用并配置 API Key	可视化管理系统配置，一键切换供应商
启动使用	在项目目录下执行 claude	让 AI 获取项目上下文并开始工作

希望这篇指南能帮你顺利搭建 Claude Code 的开发环境。如果在安装过程中遇到其他问题，欢迎在评论区留言交流！