---
title: "Mac 上的“npm error code ENOTFOUND”· Kilobat 指南"
url: "https://kilobat.app/zh-hans/guides/npm-enotfound"
description: "Mac 上的 npm install 以 npm error code ENOTFOUND 停止。软件源的名称没有解析。检查 DNS、软件源设置、VPN 和代理。"
---

# 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 无法解析](https://kilobat.app/zh-hans/guides/dns-server-not-found)。
2. 更正软件源。

   ```
   npm config set registry https://registry.npmjs.org/
   ```
3. 访问公司软件源时，请连接 VPN。
4. 刷新 DNS 缓存。请参阅[在 Mac 上刷新 DNS 缓存](https://kilobat.app/zh-hans/guides/flush-dns-cache-mac)。

## 使用 Kilobat

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

   ```
   kilobat why https://registry.npmjs.org/
   ```
2. Kilobat 的这些检查都是免费的。AI 智能体可以通过 MCP 用 `diagnose_connection` 和 `diagnose_network` 运行它们。请参阅[找出某个网站或 API 连不上的原因](https://kilobat.app/zh-hans/guides/recipes/why-cant-it-connect)。

## 常见问题

**ENOTFOUND 和 EAI_AGAIN 一样吗？**

不一样。EAI_AGAIN 表示临时性的查询失败。参见[Mac 上的 EAI_AGAIN](https://kilobat.app/zh-hans/guides/eai-again)。

**是我的包名写错了吗？**

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

## 参考资料

- [Node.js 文档：Common system errors](https://nodejs.org/api/errors.html#common-system-errors)
- [npm 文档：常见错误](https://docs.npmjs.com/common-errors)

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

## 相关指南

- [Mac 上出现“npm error code ECONNRESET”](https://kilobat.app/zh-hans/guides/npm-econnreset): ECONNRESET 表示连接被强制重置。
- [Mac 上出现“npm error code ETIMEDOUT”](https://kilobat.app/zh-hans/guides/npm-etimedout): ETIMEDOUT 表示对方没有及时应答。
- [Mac 上的 EAI_AGAIN](https://kilobat.app/zh-hans/guides/eai-again): EAI_AGAIN 表示当前无法解析名称。
- [Mac 上的“curl: (6) Could not resolve host”](https://kilobat.app/zh-hans/guides/curl-could-not-resolve-host): curl 退出码 6 表示 curl 无法获取主机名对应的地址。
