---
title: "Claude Code 国内安装：npm 镜像源、Windows 与 macOS 步骤"
canonical: https://relayswitch.ai/zh/guides/claude-code-install
generated: 2026-11-12T04:22:52.801Z
source: https://api.relayswitch.io/v1/catalog
base_url: https://api.relayswitch.io/v1
---

配置教程 · 核对于 2026-11-11

# Claude Code 国内安装

这篇只讲安装这一步：四种官方安装方式怎么选，用 npm 时怎么换镜像源，Windows 和 macOS 各自的命令，以及装不上时按报错原文怎么查。网络环境不在本文范围内，本站只提供 API 和计费，不提供任何网络接入服务。

## 01先选安装方式

Claude Code 的 [官方安装页](https://code.claude.com/docs/en/setup) 给了四种装法，装出来的是同一个程序，区别在安装包从哪里下载、之后怎么更新：

| 方式 | 前提 | 更新 |
| --- | --- | --- |
| 原生安装脚本（官方推荐） | 无；下载自 Anthropic 的服务器 | 后台自动更新 |
| Homebrew | 已装 Homebrew | `brew upgrade claude-code` |
| WinGet（Windows） | 已有 WinGet | `winget upgrade Anthropic.ClaudeCode` |
| npm | Node.js 22 或更高；文件来自 npm 的 registry | `npm install -g @anthropic-ai/claude-code@latest` |

“镜像源安装”说的是第四种。npm 从哪个地址下载包，由它的 `registry` 设置决定，默认是 https://registry.npmjs.org/；公司内网的私有源、[npmmirror](https://npmmirror.com) 这样的公共镜像，都是把这个设置换成另一个地址，属于 npm 的常规用法。另外三种方式下载的是 Anthropic 自己的安装包，不经过 npm，也就没有镜像源这回事。

顺带澄清一个常见的混淆：这里的镜像是 npm 包的镜像源，和网上说的“Claude 镜像站”不是一回事，本文不涉及后者。

## 02系统要求

-   操作系统：macOS 13.0 以上；Windows 10 1809 以上或 Windows Server 2019 以上；Ubuntu 20.04、Debian 10、Alpine 3.19 及以上。
-   硬件：内存 4 GB 起，x64 或 ARM64 处理器。
-   终端：Bash、Zsh、PowerShell 或 CMD。
-   npm 方式另需 Node.js 22 或更高。版本低一些时 npm 只打印一条 `EBADENGINE` 警告，安装照样完成，因为装下来的是原生程序，运行时不依赖你的 Node。

## 03第一步：检查 Node.js 和 npm

走 npm 这条路，先看两个版本号：

bash

1`node -v`

2`npm -v`

`npm -v` 打印的版本以 12 开头时要多做一件事。npm 12 默认不执行包的安装脚本，而 Claude Code 正是靠安装脚本把二进制放到位的，跳过之后运行 `claude` 会报 `claude native binary not installed`。官方给的办法是把它加进允许列表再安装：

bash

1`npm config get allow-scripts`

2`npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user`

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

第一条命令先看列表里原来有没有别的包，因为第二条会覆盖整个值；原来有的，用逗号一起写进引号里。npm 是 12.0.x 的，官方建议先升到 12.1 或更高。

## 04第二步：用 npm 镜像源安装

只对这一次安装用镜像源，在命令后面加参数：

bash

1`npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com`

想让以后的 npm 命令都走镜像源，写进用户配置：

bash

1`# 写入用户级配置（~/.npmrc），之后所有 npm 命令都走这个源`

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

3`npm config get registry`

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

5

6`# 换回官方源`

7`npm config delete registry`

`npm config set` 改的是用户级配置文件 `~/.npmrc`（Windows 是 `%USERPROFILE%\.npmrc`），对这台电脑上你的所有项目生效。两种写法怎么选：npm 方式装的 Claude Code 更新时也是调用 npm，用的是配置里的源，想让更新也走镜像源就用第二种。

安装时有四件事不要做，都出自官方文档：

-   不要加 `sudo`。更新时 Claude Code 不带 sudo 调用 npm，用 sudo 装的之后更新不了。
-   不要带 `--omit=optional`。二进制是作为“可选依赖”按平台下载的，略过它就什么都没装上。
-   不要带 `--ignore-scripts`。安装脚本负责把二进制放到位。
-   升级不要用 `npm update -g`，用 `npm install -g @anthropic-ai/claude-code@latest`。

镜像源和官方源之间可能有同步延迟。想确认镜像上的版本是不是最新，对比两边的版本号：

bash

1`npm view @anthropic-ai/claude-code version --registry=https://registry.npmmirror.com`

2`npm view @anthropic-ai/claude-code version --registry=https://registry.npmjs.org/`

用的是公司自建的源时还要注意一点：除了 `@anthropic-ai/claude-code` 本身，源里必须同步了全部八个 `@anthropic-ai/claude-code-*` 平台包，缺了对应平台的那个，装完同样报二进制不存在。registry 设置的完整说明在 [npm 的配置文档](https://docs.npmjs.com/cli/v11/using-npm/config)。

## 05Windows 步骤

原生 Windows 就能装，不需要 WSL，也不需要管理员权限。不走 npm 的话，三条命令任选其一，注意分清自己在 PowerShell 还是 CMD：提示符以 `PS C:\` 开头的是 PowerShell。

powershell

1`# PowerShell`

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

3

4`# CMD`

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

6

7`# WinGet`

8`winget install Anthropic.ClaudeCode`

走 npm 的话，命令和上一步完全一样。PowerShell 里如果报 `running scripts is disabled on this system`，是执行策略拦住了 npm 生成的 `.ps1` 启动脚本，放开当前用户的策略后重试：

powershell

1`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`

不想改策略，就把命令里的 `npm` 换成 `npm.cmd`，之后用 `claude.cmd` 启动，策略管不到 `.cmd`。

原生安装脚本把程序放在 `%USERPROFILE%\.local\bin\claude.exe`。装完提示这个目录不在 PATH 里时，照安装程序打印的办法加进去，再开一个新终端。Git for Windows 可装可不装：装了，Claude Code 用 Git Bash 执行命令；没装，用 PowerShell。

## 06macOS 与 Linux 步骤

不走 npm 的话，原生安装脚本或 Homebrew 二选一：

bash

1`# 原生安装脚本（macOS、Linux、WSL）`

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

3

4`# Homebrew`

5`brew install --cask claude-code`

原生安装脚本把程序放在 `~/.local/bin/claude`，之后在后台自动更新。Homebrew 有两个 cask：`claude-code` 跟稳定通道，通常比最新版晚一周左右；`claude-code@latest` 跟最新通道。Homebrew 装的不会自动更新，隔一段时间手动 `brew upgrade` 一次。

走 npm 的话，命令同第二步。遇到 `EACCES` 这类权限报错，不要加 sudo，按官方的建议改用原生安装脚本。WSL 里要在 WSL 的终端内安装，不是在 PowerShell 里。

## 07第三步：验证安装

开一个新的终端窗口（旧窗口的 PATH 还是安装前的）：

bash

1`claude --version`

2`claude doctor`

第一条打印出版本号就是装好了。第二条不启动会话，只做只读的检查：安装是否完整、配置文件有没有写错、上一次更新是否成功，有问题会连同建议一起列出来。

## 08安装失败：按报错原文对照

下表摘自官方的 [安装排错页](https://code.claude.com/docs/en/troubleshoot-install)，挑的是最常遇到的几条。左边是终端里的原文，直接搜你看到的那一句。

| 你看到的 | 原因 | 处理 |
| --- | --- | --- |
| `command not found: claude` | 安装目录不在 PATH 里，或者还在用旧终端 | 开新终端；仍然不行，把安装程序提示的目录加进 PATH |
| ``syntax error near unexpected token `<'`` | 安装地址返回的是一个网页，不是安装脚本 | 过几分钟重试，或换官方给的替代方式 Homebrew、WinGet |
| `curl: (22) … error: 403` | 同上，只是没有返回网页内容 | 同上；在公司网络里，先找网管确认防火墙有没有拦截下载 |
| `App unavailable in region` | 官方的解释：所在国家或地区不在 Anthropic 的 [支持列表](https://www.anthropic.com/supported-countries) 里 | 见官方排错页的说明 |
| `claude native binary not installed` | npm 没执行安装脚本，或没下载平台包 | npm 12 照第一步处理；去掉 --ignore-scripts 和 --omit=optional；自建源补齐平台包 |
| `running scripts is disabled` | PowerShell 执行策略拦住了 npm 的 .ps1 脚本 | 见 Windows 步骤 |
| `npm error code ENOTEMPTY` | 上一次安装留下了没清干净的目录 | 删掉旧目录再装，命令见表下 |
| `EACCES: permission denied` | 全局包目录不可写 | 不要加 sudo，改用原生安装脚本 |
| `'irm' is not recognized` | 在 CMD 里运行了 PowerShell 的命令 | 换用 CMD 那一条，或者打开 PowerShell |

`ENOTEMPTY` 的清理命令（macOS、Linux）：

bash

1`rm -rf "$(npm root -g)/@anthropic-ai/claude-code"`

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

表里没有的报错，官方排错页按原文还列了几十条。装好之后运行时的报错是另一类问题，按状态码查 [Claude Code 报错速查](https://relayswitch.ai/zh/fix/claude-code-api-error)。

## 09第四步：接入 API 密钥

装好只是第一半。Claude Code 启动后要么登录 claude.ai 账号，要么给它一个 API 密钥。用密钥这条路，在 [控制台](https://app.relayswitch.io/console?lang=zh) 用邮箱开通，USDT 或银行卡充值，最低 $10，然后设两个环境变量。macOS、Linux 和 WSL：

bash

1`export ANTHROPIC_BASE_URL="https://api.relayswitch.io/v1"`

2`export ANTHROPIC_AUTH_TOKEN="sk-relay-..."`

3`claude`

Windows PowerShell：

powershell

1`$env:ANTHROPIC_BASE_URL = "https://api.relayswitch.io/v1"`

2`$env:ANTHROPIC_AUTH_TOKEN = "sk-relay-..."`

3`claude`

写进配置文件、VS Code 扩展的写法、接通验证，在 [国内怎么用 Claude Code](https://relayswitch.ai/zh/guides/claude-code-china) 里一步步写了；逐个变量的说明见 [Claude Code 配置第三方 API](https://relayswitch.ai/zh/guides/claude-code)。下表是此刻目录里 Claude Code 能调用的 13 个 Claude id，价格渲染时读取，按 token 从预付余额扣费，没有倍率。

| 模型 | 开发商 | 输入 / 百万 | 输出 / 百万 |
| --- | --- | --- | --- |
| [Claude Fable 5.1](https://relayswitch.ai/zh/models/claude-fable-5.1)claude-fable-5.1 | Anthropic | $6.00≈ ¥40.82 | $30.00≈ ¥204.12 |
| [Claude Fable 5.2](https://relayswitch.ai/zh/models/claude-fable-5.2)claude-fable-5.2 | Anthropic | $4.00≈ ¥27.22 | $20.00≈ ¥136.08 |
| [Claude Fable 5](https://relayswitch.ai/zh/models/claude-fable-5)claude-fable-5 | Anthropic | $3.00≈ ¥20.41 | $15.00≈ ¥102.06 |
| [Claude Opus 5.5](https://relayswitch.ai/zh/models/claude-opus-5-5)claude-opus-5-5 | Anthropic | $2.716≈ ¥18.48 | $9.70≈ ¥66.00 |
| [Claude Sonnet 4.6](https://relayswitch.ai/zh/models/claude-sonnet-4-6)claude-sonnet-4-6 | Anthropic | $1.80≈ ¥12.25 | $9.00≈ ¥61.24 |
| [Claude Opus 4.6](https://relayswitch.ai/zh/models/claude-opus-4-6)claude-opus-4-6 | Anthropic | $1.80≈ ¥12.25 | $7.50≈ ¥51.03 |
| [Claude Opus 4.7](https://relayswitch.ai/zh/models/claude-opus-4-7)claude-opus-4-7 | Anthropic | $1.80≈ ¥12.25 | $7.50≈ ¥51.03 |
| [Claude Opus 4.8](https://relayswitch.ai/zh/models/claude-opus-4-8)claude-opus-4-8 | Anthropic | $1.80≈ ¥12.25 | $7.50≈ ¥51.03 |
| [Claude Opus 5](https://relayswitch.ai/zh/models/claude-opus-5)claude-opus-5 | Anthropic | $1.80≈ ¥12.25 | $7.50≈ ¥51.03 |
| [Claude Haiku 4.5](https://relayswitch.ai/zh/models/claude-haiku-4-5)claude-haiku-4-5 | Anthropic | $0.60≈ ¥4.08 | $3.00≈ ¥20.41 |
| [Claude Sonnet 5](https://relayswitch.ai/zh/models/claude-sonnet-5)claude-sonnet-5 | Anthropic | $1.20≈ ¥8.16 | $3.00≈ ¥20.41 |
| [Claude Sonnet 5.5](https://relayswitch.ai/zh/models/claude-sonnet-5-5)claude-sonnet-5-5 | Anthropic | $1.20≈ ¥8.16 | $3.00≈ ¥20.41 |
| [Claude Haiku 5.5](https://relayswitch.ai/zh/models/claude-haiku-5-5)claude-haiku-5-5 | Anthropic | $0.0582≈ ¥0.396 | $0.1455≈ ¥0.99 |

美元 / 百万 tokens，人民币参考价按 ECB 2026-11-11 汇率

## 常见问题

用 npm 镜像源装的 Claude Code 和官方安装的一样吗？

程序是同一个。按官方安装页，npm 包装的就是原生安装脚本装的那个二进制，通过按平台区分的可选依赖下载。区别在来源：镜像源是第三方维护的 registry 副本。在意这一点的，改用官方 registry 或原生安装脚本，官方安装页还写了校验二进制签名的办法。

必须先装 Node.js 吗？

只有 npm 这一种方式需要，要求 Node.js 22 或更高。原生安装脚本、Homebrew 和 WinGet 都不需要 Node.js。装好之后的 claude 是原生程序，运行时也不调用 Node。

安装时提示权限不足，可以加 sudo 吗？

不要。官方文档明确写了不要用 sudo npm install -g：Claude Code 更新自己时不带 sudo 调用 npm，用 sudo 装的之后无法自动更新。遇到 EACCES，改用原生安装脚本。

换了镜像源，以后怎么换回来？

运行 npm config delete registry，npm 回到默认的 https://registry.npmjs.org/。只想对这一次安装用镜像源，就不要改配置，在命令后面加 --registry 参数。

Windows 必须装 WSL 吗？

不必。Claude Code 支持原生 Windows（Windows 10 1809 以上），在 PowerShell 或 CMD 里安装，不需要管理员权限。Git for Windows 可装可不装：装了用 Git Bash 执行命令，没装用 PowerShell。

装好了，但没有 claude.ai 账号怎么用？

Claude Code 可以不登录 claude.ai，改用 API 密钥按 token 计费：设置 ANTHROPIC\_BASE\_URL 和 ANTHROPIC\_AUTH\_TOKEN 两个环境变量即可。本站的密钥用邮箱开通，USDT 或银行卡充值。

相关页面

-   [Claude Code 中转站](https://relayswitch.ai/zh/claude-code)
-   [国内怎么用 Claude Code](https://relayswitch.ai/zh/guides/claude-code-china)
-   [Claude Code 配置第三方 API](https://relayswitch.ai/zh/guides/claude-code)
-   [CC Switch 配置中转站](https://relayswitch.ai/zh/guides/cc-switch)
-   [Claude API 中转站](https://relayswitch.ai/zh/claude-api)
-   [Claude API Key 购买与充值](https://relayswitch.ai/zh/claude-api-key)
-   [Claude Code 报错速查](https://relayswitch.ai/zh/fix/claude-code-api-error)
-   [Claude Code 报错 403](https://relayswitch.ai/zh/fix/claude-code-403)
-   [Claude Code 封号](https://relayswitch.ai/zh/claude-code-fenghao)
-   [API 中转站怎么选](https://relayswitch.ai/zh/zhongzhuanzhan-tuijian)
-   [模型与价格](https://relayswitch.ai/zh/models)
-   [充值](https://relayswitch.ai/zh/pay)
-   [Claude Code 官方安装页](https://code.claude.com/docs/en/setup)
-   [Claude Code 官方安装排错页](https://code.claude.com/docs/en/troubleshoot-install)

## 装好了，就差一把密钥

邮箱开通，USDT 或银行卡充值，最低 $10。Base URL https://api.relayswitch.io/v1。

[Claude Code 中转站](https://relayswitch.ai/zh/claude-code)[获取密钥](https://app.relayswitch.io/console?lang=zh)