【Bug已解决】Failed to fetch version ECONNREFUSED 解决方案

【Bug已解决】Failed to fetch version ECONNREFUSED 解决方案

1. 问题描述

在 Windows 或 macOS 上首次安装或更新 Claude Code时，终端输出以下报错信息：

Failed to fetch version from https://downloads.claude.ai/claude-code-releases/latest ECONNREFUSED

这个问题在以下场景中特别常见：

• 新安装或升级后首次运行
• 切换 Node.js 版本或操作系统升级后
• 企业内网或 CI/CD 环境中首次配置
• 多账号切换或配置文件被意外修改

报错通常突然出现——之前正常运行的环境突然无法使用，开发者往往反复重装也无法解决。在 GitHub Issues 和开发者社区中，这类报错的讨论量持续活跃，说明是一个高频且持续存在的问题。

# 典型复现过程$ claude# 或对应工具命令Failed to fetch version from https://downloads.claude.ai/claude-code-releases/latest ECONNREFUSED# 反复重装无效$npminstall-gxxx# 成功但问题依旧$ xxx--version# 仍然报错

2. 原因分析

核心原理拆解

正常执行流程 ↓ 环境/配置/依赖出现异常 ↓ 触发报错 ↓ 工具无法正常工作

原因分类表

深入说明

ECONNREFUSED 表示 TCP 连接被主动拒绝。Claude Code 的安装器需要访问 downloads.claude.ai 下载二进制文件，如果该域名无法解析或被防火墙拦截，就会报此错误。常见原因包括：DNS 解析失败、本地防火墙规则拦截、企业网络策略限制、或系统时间不同步导致 TLS 握手失败。注意：此报错是网络层面的连接问题，与 API Key 或账号无关。

3. 解决方案

方案1：检查 DNS 解析（最推荐）

首先确认域名能否正常解析。如果无法解析，说明 DNS 配置有问题，需要更换 DNS 服务器。

nslookupdownloads.claude.ai# 或digdownloads.claude.ai# 如果解析失败，尝试更换 DNS# macOS/Linuxsudonetworksetup-setdnsserversWi-Fi8.8.8.81.1.1.1# Windowsnetsh interfaceipsetdns"Wi-Fi"static8.8.8.8

方案2：使用 npm 镜像源安装

如果下载域名不可达，可以配置 npm 使用国内镜像源来安装 Claude Code 的 npm 包部分，二进制文件会从镜像拉取。

npmconfigsetregistry https://registry.npmmirror.comnpminstall-g@anthropic-ai/claude-code# 安装完成后恢复官方源npmconfigsetregistry https://registry.npmjs.org

方案3：手动下载二进制文件

如果自动下载始终失败，可以手动下载对应平台的二进制文件并放置到正确位置。

# 1. 在可访问网络的机器上下载# 2. 手动复制到安装目录# macOS (Apple Silicon)cpclaude-darwin-arm64 ~/.npm-global/lib/node_modules/@anthropic-ai/claude-code/bin/claudechmod+x ~/.npm-global/lib/node_modules/@anthropic-ai/claude-code/bin/claude# 3. 验证claude--version

方案4：检查系统时间同步

TLS 握手要求客户端和服务器时间差不超过 5 分钟。如果系统时间偏差过大，连接会被拒绝。

# macOSsudosntp-stime.apple.com# Linuxsudontpdate ntp.ubuntu.com# Windowsw32tm /resync

方案5：强制使用 IPv4

某些环境下 IPv6 路由不通但 DNS 优先返回 AAAA 记录，强制使用 IPv4 可以绕过此问题。

# macOSnetworksetup-setv6offWi-Fi# Linuxecho'precedence ::ffff:0:0/96 100'|sudotee-a/etc/gai.conf# curl 强制 IPv4curl-4https://downloads.claude.ai/

4. 各方案对比总结

5. 常见问题 FAQ

5.1 使用公司网络时总是报 ECONNREFUSED，但家里网络正常

企业网络通常有安全网关或代理服务器拦截了对 downloads.claude.ai 的访问。需要联系 IT 部门将该域名加入白名单，或配置 npm 的代理设置：npm config set proxy http://公司代理:端口。也可以在能访问的网络环境下安装好后，将整个 node_modules 目录复制到公司机器上。

5.2 DNS 能解析但 curl 仍然连接被拒绝

这说明 DNS 正常但 TCP 连接被拒绝。可能是防火墙规则或安全软件（如 Windows Defender、360 安全卫士）拦截了出站连接。检查防火墙规则：sudo pfctl -sr（macOS）或检查 Windows Defender 防火墙出站规则。临时关闭安全软件测试可以快速定位问题。

5.3 安装时报 ECONNREFUSED 但 claude 命令已经存在

这说明二进制文件已经下载成功，但安装器在检查更新时连接失败。这种情况不影响使用，可以直接运行claude --version验证。如果需要更新，可以稍后网络恢复时再执行npm update -g @anthropic-ai/claude-code。

5.4 Docker 容器内安装报 ECONNREFUSED

Docker 容器的网络可能与宿主机不同。需要检查容器的 DNS 配置：docker run --dns 8.8.8.8 ...。或者使用 host 网络模式：docker run --network host ...。另外确保容器内的 /etc/resolv.conf 包含有效的 DNS 服务器。

5.5 更换 DNS 后仍然报错

可能是 DNS 缓存未刷新。清除 DNS 缓存：macOSsudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder，Windowsipconfig /flushdns，Linuxsudo systemd-resolve --flush-caches。

5.6 在 WSL2 中安装报 ECONNREFUSED

WSL2 的网络可能与 Windows 宿主机的 DNS 配置不同步。在 WSL2 中执行echo 'nameserver 8.8.8.8' | sudo tee /etc/resolv.conf修复 DNS。或者在 ~/.wslconfig 中配置 networkingMode=mirrored 使用镜像网络模式。

5.7 CI/CD 环境中安装 Claude Code 报 ECONNREFUSED

CI/CD 环境通常有严格的网络限制。建议使用预先构建好的 Docker 镜像，或在自托管 Runner 上预装 Claude Code。如果必须在 CI 中安装，确保 Runner 有访问外网的权限，或配置 npm 私有镜像。

5.8 使用代理后仍然报 ECONNREFUSED

npm 的代理配置可能与系统代理不同步。显式配置 npm 代理：npm config set proxy http://127.0.0.1:端口和npm config set https-proxy http://127.0.0.1:端口。同时确保代理软件允许 downloads.claude.ai 的流量通过。

5.9 报错信息中 IP 地址是 127.0.0.1 而非外网 IP

这说明 DNS 被本地 hosts 文件或 DNS 劫持重定向了。检查 /etc/hosts（macOS/Linux）或 C:\Windows\System32\drivers\etc\hosts（Windows）中是否有 downloads.claude.ai 的条目，如果有则删除。

5.10 安装成功后首次运行 claude 也报 ECONNREFUSED

Claude Code 运行时也需要连接 Anthropic API 服务器。检查 ANTHROPIC_API_KEY 环境变量是否正确配置：echo $ANTHROPIC_API_KEY。如果使用第三方 API 路由，确保 ANTHROPIC_BASE_URL 设置正确。

5.11 排查清单速查表

□ 1. 运行 nslookup downloads.claude.ai 确认 DNS 解析正常 □ 2. 运行 curl -I https://downloads.claude.ai 确认 HTTP 连接可达 □ 3. 检查系统时间是否同步: date 命令对比标准时间 □ 4. 检查防火墙/安全软件是否拦截了出站连接 □ 5. 尝试更换 DNS 服务器为 8.8.8.8 或 1.1.1.1 □ 6. 清除 DNS 缓存后重试 □ 7. 企业网络联系 IT 将 downloads.claude.ai 加入白名单 □ 8. 尝试使用 npm 国内镜像源安装 □ 9. 检查 /etc/hosts 中是否有域名劫持条目 □ 10. WSL2 用户检查 /etc/resolv.conf DNS 配置

6. 总结

1. ECONNREFUSED 的本质是网络层面的 TCP 连接被拒绝，最常见原因是 DNS 解析失败或防火墙拦截
2. 首选方案是检查 DNS 解析，更换为公共 DNS 服务器（如 8.8.8.8）可解决大部分问题
3. 企业网络用户需要联系 IT 部门将 downloads.claude.ai 加入白名单
4. 如果网络问题无法解决，可以使用 npm 镜像源或手动下载二进制文件作为备选方案
5. 最佳实践建议：在新环境中先运行curl -I https://downloads.claude.ai验证网络可达性，再执行安装命令

故障排查流程图