Claude Code 镜像与加速接入：先分清三类问题再动手

先分清你遇到的是哪一类

「Claude Code 镜像」这个搜索词底下混着四种完全不同的故障。它们的症状看起来都像「连不上」，但出问题的层不一样，换错东西不会有任何效果。

第一类和后三类没有任何关系。很多人把 npm 装不上归咎于「要用镜像站」，其实只需要换一个 npm 源，跟用不用网关是两件事。

下面四节按这四类分别给诊断命令。每一节都有一个明确的通过标准，过了就往下走，不过就停在那一层解决。

第一类：安装阶段的问题

Claude Code 通过 npm 分发，安装慢或失败通常是 registry 的问题，与 API 无关。

先确认是不是 registry 的问题：

npm config get registry
npm ping

npm ping 超时就是 registry 不通。换一个国内可用的 registry 即可，这是公开的标准做法，和任何中转服务无关。

装完验证：

claude --version

能打印版本号，说明安装这一层已经通了。之后再出问题，就不是安装的锅，不要回头再折腾 registry。

第二类：API 端点连不通

这是「镜像」这个词真正指向的场景。Claude Code 默认请求 Anthropic 官方端点，网络不通时会超时。

标准解法是指向一个 Anthropic Messages 协议兼容的网关，用官方支持的环境变量：

export ANTHROPIC_BASE_URL="https://你的网关/v1"
export ANTHROPIC_AUTH_TOKEN="你的密钥"

这里有两个几乎人人踩过的坑。

第一，鉴权头要和网关匹配。 ANTHROPIC_AUTH_TOKEN 发送的是 Authorization: Bearer，ANTHROPIC_API_KEY 发送的是 x-api-key。两者不通用，用错会报 401，而报错信息通常只说鉴权失败，不会告诉你是头用错了。网关只认其中一种时，换一个环境变量就好了。

第二，Base URL 不要带 /v1/messages。 只写到 /v1，后面的路径由客户端自己拼。带全了会变成 /v1/messages/v1/messages，返回 404。

配完先用 curl 验证端点本身通不通，再启动 Claude Code：

curl -s -o /dev/null -w "%{http_code} %{time_total}s\n" \
  -X POST "$ANTHROPIC_BASE_URL/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"你的模型ID","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

返回 200 且耗时正常，端点这层就没问题了。这一步的价值在于把「网关的问题」和「客户端配置的问题」分开——curl 能通而 Claude Code 不通，那一定是客户端这边的配置。

至于怎么判断一个网关值不值得用，协议兼容性、工具调用稳定性这些要逐项验证，我们在Claude Code 中转站怎么选里写了九条可自测的标准。具体的环境变量与配置文件优先级，见Claude Code 中转站配置。

第三类：能用但慢

端点通了还是慢，不要直接换网关——先定位慢在哪一段。curl 的 time_* 变量能把一次请求拆成五个阶段：

curl -s -o /dev/null \
  -w "DNS %{time_namelookup}  连接 %{time_connect}  TLS %{time_appconnect}  首字节 %{time_starttransfer}  总计 %{time_total}\n" \
  "$ANTHROPIC_BASE_URL/models" -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

这几个值是累计的，后一个减前一个才是该阶段真正的耗时。

首字节时间（TTFT）是最值得单独看的指标。 它反映的是网关到上游的链路加上模型排队时间，同一个模型在不同网关上的 TTFT 可能差好几倍。而 DNS 和 TLS 只在第一次请求时明显，连接复用后基本归零。

对话式使用时，TTFT 比总耗时更影响体感——等两秒才开始吐字，和立刻开始吐字但总共花五秒，后者感觉快得多。

第四类：用一会儿就断

Claude Code 的流式响应依赖长连接。中途断开通常是三个原因之一，靠断开的规律就能区分：

测长流式是否稳定，直接发一个要求长输出的请求，看它能不能走完：

curl -N -X POST "$ANTHROPIC_BASE_URL/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"你的模型ID","max_tokens":2000,"stream":true,
       "messages":[{"role":"user","content":"写一篇 1500 字的技术说明"}]}' \
  | tail -5

正常应当以 message_stop 事件结束。中途无声中断说明连接被掐了，此时看断开的时间点是否固定，就能分辨是代理超时还是网关的问题。

返回 429 属于另一类问题，各种错误码的含义和对应处理见API 中转站错误码对照；流式事件本身的完整性判断见流式响应与工具调用兼容性。

「Claude Code 镜像站」到底指什么

严格讲，Claude Code 没有官方镜像。「镜像站」这个说法在中文语境里被用来指三种不同的东西，选错方向会浪费很多时间。

要在终端里用 Claude Code 做编码工作，你需要的是第一种。判断一个站属于哪一种，看它给你的是什么：

• 给 Base URL 加密钥 → 第一种，按本文第三节配置
• 给 一个网页登录入口 → 第二种，不能用于 CLI，它读不到你本地的文件，也执行不了命令
• 给 一行 npm config 命令 → 第三种，只解决安装，不解决连接

一个常见的混淆是：某些站同时提供网页版和 API，但两者的额度和计费是分开的。买了网页版的套餐不等于有 API 额度。

不想靠宣传页判断的话，直接打一条命令：

curl -s -o /dev/null -w "%{http_code}\n" \
  "https://候选站点/v1/models" -H "Authorization: Bearer 你的密钥"

返回 200 且能列出模型，是协议兼容网关；返回 404 或者一段 HTML，多半是网页套壳站。这一条命令就能省掉一次下错单。

一个完整的排查顺序

遇到问题时按这个顺序走，每一步都有明确的通过标准，不要跳步：

在第几步断，问题就在那一层。前五步全是 curl，不依赖 Claude Code 本身，所以能干净地把客户端排除在外。

跳过前面几步直接改 Claude Code 的配置，是最常见的浪费时间的方式。 配置文件改来改去，而问题其实在 DNS 上。

常见问题

继续阅读