---
title: "Mac 上的 npm error code ENOTFOUND · Kilobat 指南"
url: "https://kilobat.app/zh-hant/guides/npm-enotfound"
description: "Mac 上的 npm install 以 npm error code ENOTFOUND 停止。registry名稱無法解析。請檢查 DNS、registry設定、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-hant/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 伺服器。
- **registry錯誤。**npm registry設定指向不存在的主機，或需要 VPN 的主機。
- **VPN 有自己的 DNS。**公司的registry只有在 VPN 開啟時才能解析。
- **npm 沒有使用的代理伺服器。**在只能透過代理伺服器的網路上，npm 需要代理伺服器設定。

## 如何檢查

1. 顯示 npm 使用的registry。

   ```
   npm config get registry
   ```
2. 透過 macOS 解析主機名稱。

   ```
   dscacheutil -q host -a name registry.npmjs.org
   ```
3. 直接詢問 registry。

   ```
   npm ping
   ```
4. 顯示代理伺服器設定。

   ```
   npm config get https-proxy
   ```

## 如何修正

1. 如果 macOS 的查詢失敗，請修正 DNS。請參閱 [Mac 上的 DNS 無法解析](https://kilobat.app/zh-hant/guides/dns-server-not-found)。
2. 更正 registry。

   ```
   npm config set registry https://registry.npmjs.org/
   ```
3. 公司的 registry 需要連上 VPN。
4. 清除 DNS 快取。請參閱[清除 Mac 上的 DNS 快取](https://kilobat.app/zh-hant/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-hant/guides/recipes/why-cant-it-connect)。

## 常見問題

**ENOTFOUND 和 EAI_AGAIN 一樣嗎？**

不一樣。EAI_AGAIN 表示暫時的查詢失敗。請參閱 [Mac 上的 EAI_AGAIN](https://kilobat.app/zh-hant/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-hant/guides/npm-econnreset): ECONNRESET 表示連線遭強制重設。
- [Mac 上的「npm error code ETIMEDOUT」](https://kilobat.app/zh-hant/guides/npm-etimedout): ETIMEDOUT 表示對方沒有及時回應。
- [Mac 上的 EAI_AGAIN](https://kilobat.app/zh-hant/guides/eai-again): EAI_AGAIN 表示目前無法解析名稱。
- [Mac 上的「curl: (6) Could not resolve host」](https://kilobat.app/zh-hant/guides/curl-could-not-resolve-host): curl 結束代碼 6 表示 curl 無法取得主機名稱的位址。
