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 無法解析。

  2. 更正 registry。

    npm config set registry https://registry.npmjs.org/
  3. 公司的 registry 需要連上 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 日。