错误信息

Mac 上出现“npm error code ETIMEDOUT”

ETIMEDOUT 表示对方没有及时响应。Node.js 文档的说法是：“the connected party did not properly respond after a period of time.”（连接方在一段时间后未正确响应。）

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

症状

  • npm install 中止并显示 npm error code ETIMEDOUT。
  • npm 还会提示这是与网络连接有关的问题。
  • 只在某个网络上失败，例如公司网络或热点。

可能的原因

  • npm 不知道的代理。在需要代理的网络上，npm 需要设置 proxy 和 https-proxy。
  • 无法访问的 registry。旧的 registry 设置可能指向一台私有服务器。
  • 连接缓慢或丢包。在信号弱的 Wi-Fi 或热点上，大型包会超时。
  • IPv6 路径不通。registry 有 IPv6 地址，而你的网络上 IPv6 无法使用。

如何检查

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

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

  2. 测试 registry 是否响应。

    npm ping

  3. 用 curl 测试 registry，仅使用 IPv4。

    curl -4 -I https://registry.npmjs.org/

  4. 测量连接质量。

    networkQuality

如何修复

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

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

  2. 删除旧的 registry 设置，让 npm 使用默认值。

    npm config delete registry

  3. 在慢速连接上增加 npm 的重试次数。

    npm config set fetch-retries 5

  4. 如果可以，换到更快的网络上再次安装。

使用 Kilobat

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

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

  2. 大型安装前，先检查网络是否按流量计费、是否在 VPN 上或速度较慢。

    kilobat conditions

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

常见问题

npm 会等待多久？

根据 npm 文档，fetch-timeout 默认为 300000 ms，即 5 分钟；fetch-retries 默认为 2。

参考资料

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