错误信息

Mac 上出现“npm error code ECONNRESET”

ECONNRESET 表示对方强行关闭了连接。Node.js 文档称之为“Connection reset by peer”（连接被对方重置）。

适用于：npm 10 及更高版本输出“npm error”，更早的版本输出“npm ERR!”。适用于所有当前 macOS 版本。核查日期：2026年10月29日

症状

  • npm install 中止并显示 npm error code ECONNRESET。
  • npm 还会提示这是与网络连接有关的问题。
  • 在公司网络、VPN 下或装有安全软件时出现。

可能的原因

  • 代理或过滤器重置了连接。公司代理或安全软件可能会关闭它不允许的连接。
  • TLS 检查。检查加密流量的代理可能会破坏连接。参阅公司代理证书导致 Mac 上的终端工具出错。
  • VPN 重新连接。VPN 重新连接时，经由它的连接会关闭。
  • 连接不稳定。Node.js 文档指出，远端超时或重启都可能导致此错误。

如何检查

  1. 显示 npm 的 registry 和代理设置。

    npm config get registry
npm config get proxy
npm config get https-proxy

  2. 测试 registry 是否响应。

    npm ping

  3. 用 curl 测试 registry，查看证书颁发者。

    curl -v -o /dev/null https://registry.npmjs.org/ 2>&1 | grep -i issuer

  4. 在其他网络（例如手机热点）上尝试安装。

如何修复

  1. 如果网络需要代理，为 npm 设置代理。

    npm config set https-proxy http://proxy.example.com:8080

  2. 如果公司代理会检查 TLS，为 Node.js 添加其根证书。参阅公司代理证书导致 Mac 上的终端工具出错。

  3. 增加 npm 的重试次数。

    npm config set fetch-retries 5

  4. 如果打开了 VPN、代理或安全 App，请暂时关闭它进行测试，测试后再重新打开。

使用 Kilobat

  1. Kilobat 的连接诊断会逐层测试 registry：网络、代理、DNS、规则、IPv4、IPv6、TLS 和服务器，并指出失败的是哪一层。

    kilobat why https://registry.npmjs.org/

  2. Kilobat 的这些检查都是免费的。AI 智能体可以通过 MCP 用 diagnose_connection 和 diagnose_network 运行它们。请参阅找出某个网站或 API 连不上的原因。

常见问题

ECONNRESET 是我项目里的 bug 吗？

通常不是。是与 registry 的连接被关闭了。在另一个网络上运行同样的安装进行对比。

参考资料

参考资料核查于 2026年10月29日。man 手册页为 macOS 自带版本；在“终端”中用 man <name> 打开。