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 install中止并显示npm error code ENOTFOUND。- 下一行会给出一个主机,例如
registry.npmjs.org。 - 浏览器可能正常。
可能的原因
- 没有连接或 DNS。Mac 无法连接到 DNS 服务器。
- 软件源不对。npm 的软件源设置指向了不存在的主机,或需要 VPN 才能访问的主机。
- 自带 DNS 的 VPN。公司的软件源只有在 VPN 开启时才能解析。
- npm 没有使用的代理。在只能通过代理上网的网络中,npm 需要设置代理。
如何检查
显示 npm 使用的软件源。
npm config get registry通过 macOS 解析主机名。
dscacheutil -q host -a name registry.npmjs.org直接询问软件源。
npm ping显示代理设置。
npm config get https-proxy
如何修复
如果 macOS 的查询失败,请修复 DNS。参见Mac 上 DNS 无法解析。
更正软件源。
npm config set registry https://registry.npmjs.org/访问公司软件源时,请连接 VPN。
刷新 DNS 缓存。请参阅在 Mac 上刷新 DNS 缓存。
使用 Kilobat
Kilobat 的连接诊断会逐层测试这个地址:网络、代理、DNS、规则、IPv4、IPv6、TLS 和服务器,并指出失败的那一层。
kilobat why https://registry.npmjs.org/Kilobat 的这些检查都是免费的。AI 智能体可以通过 MCP 用
diagnose_connection和diagnose_network运行它们。请参阅找出某个网站或 API 连不上的原因。
常见问题
ENOTFOUND 和 EAI_AGAIN 一样吗?
不一样。EAI_AGAIN 表示临时性的查询失败。参见Mac 上的 EAI_AGAIN。
是我的包名写错了吗?
很少是这样。ENOTFOUND 涉及的是主机名,而不是包名。
参考资料
核查日期:2026 年 10 月 29 日。