Mac 上的“npm error code ENOTFOUND”

ENOTFOUND 表示 DNS 查询失败。Node.js 文档称之为“DNS lookup failed”,即 EAI_NODATA 或 EAI_NONAME 的失败。

让你的智能体来解决拷贝一条提示词,适用于 Claude Code、Codex 或任何能使用终端的智能体。

我的 Mac 出现了这个问题:Mac 上的“npm error code ENOTFOUND”。请阅读 https://kilobat.app/zh-hans/guides/npm-enotfound.md,并和我一起逐步处理。如果缺少 Kilobat CLI,请安装:brew install seifip/kilobat/kilobat。请你自己运行指南中的终端和 kilobat 检查,并告诉我发现了什么。列出只有我才能完成的步骤。更改任何设置之前先问我。

适用于:npm 10 及更高版本打印“npm error”,更早的版本打印“npm ERR!”。所有当前 macOS 版本上的 Node.js。核查日期:2026年10月29日

症状

  • npm install 中止并显示 npm error code ENOTFOUND。
  • 下一行会给出一个主机,例如 registry.npmjs.org。
  • 浏览器可能正常。

可能的原因

  • 没有连接或 DNS。Mac 无法连接到 DNS 服务器。
  • 软件源不对。npm 的软件源设置指向了不存在的主机,或需要 VPN 才能访问的主机。
  • 自带 DNS 的 VPN。公司的软件源只有在 VPN 开启时才能解析。
  • npm 没有使用的代理。在只能通过代理上网的网络中,npm 需要设置代理。

如何检查

  1. 显示 npm 使用的软件源。

    npm config get registry
  2. 通过 macOS 解析主机名。

    dscacheutil -q host -a name registry.npmjs.org
  3. 直接询问软件源。

    npm ping
  4. 显示代理设置。

    npm config get https-proxy

如何修复

  1. 如果 macOS 的查询失败,请修复 DNS。参见Mac 上 DNS 无法解析。

  2. 更正软件源。

    npm config set registry https://registry.npmjs.org/
  3. 访问公司软件源时,请连接 VPN。

  4. 刷新 DNS 缓存。请参阅在 Mac 上刷新 DNS 缓存。

使用 Kilobat

  1. Kilobat 的连接诊断会逐层测试这个地址:网络、代理、DNS、规则、IPv4、IPv6、TLS 和服务器,并指出失败的那一层。

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

常见问题

ENOTFOUND 和 EAI_AGAIN 一样吗?

不一样。EAI_AGAIN 表示临时性的查询失败。参见Mac 上的 EAI_AGAIN。

是我的包名写错了吗?

很少是这样。ENOTFOUND 涉及的是主机名,而不是包名。

参考资料

核查日期:2026 年 10 月 29 日。