錯誤訊息

Mac 上的「npm error code ETIMEDOUT」

ETIMEDOUT 表示另一端沒有及時回應。Node.js 說明文件寫道：「the connected party did not properly respond after a period of time.」（連線的另一方在一段時間後仍未正確回應。）

適用於：npm 10 及以上版本會顯示「npm error」，較舊的版本則顯示「npm ERR!」。適用於所有目前的 macOS 版本。檢查日期：2026年10月29日

症狀

  • npm install 停止並顯示 npm error code ETIMEDOUT。
  • npm 另外指出這是與網路連線有關的問題。
  • 在特定網路（例如公司網路或熱點）上失敗。

可能原因

  • npm 不知道的代理伺服器。在需要代理伺服器的網路上，npm 需要設定 proxy 和 https-proxy。
  • 無法連到的 registry。舊的 registry 設定可能指向私人伺服器。
  • 緩慢或會遺失封包的連線。在訊號弱的 Wi-Fi 或熱點上，大型套件會逾時。
  • IPv6 路徑故障。registry 有 IPv6 位址，但你的網路上 IPv6 無法運作。

如何檢查

  1. 顯示 npm 的 registry 和代理伺服器設定。

    npm config get registry
npm config get proxy
npm config get https-proxy

  2. 確認 registry 有回應。

    npm ping

  3. 使用 curl 測試 registry，只用 IPv4。

    curl -4 -I https://registry.npmjs.org/

  4. 測量連線。

    networkQuality

如何修正

  1. 如果網路需要代理伺服器，請為 npm 設定。

    npm config set https-proxy http://proxy.example.com:8080

  2. 移除舊的 registry 設定，讓 npm 使用預設值。

    npm config delete registry

  3. 在連線緩慢時增加 npm 的重試次數。

    npm config set fetch-retries 5

  4. 可以的話，在較快的網路上再次執行安裝。

使用 Kilobat

  1. Kilobat 的連線診斷會逐層測試 registry：網路、代理伺服器、DNS、規則、IPv4、IPv6、TLS 和伺服器，並指出是哪一層失敗。

    kilobat why https://registry.npmjs.org/

  2. 進行大型安裝前，先檢查網路是否為計量網路、是否經過 VPN，或速度是否很慢。

    kilobat conditions

  3. 這些 Kilobat 檢查都是免費的。AI 代理程式可透過 MCP 以 diagnose_connection 和 diagnose_network 執行。請參閱找出某個網站或 API 連不上的原因。

常見問題

npm 會等多久？

npm 的文件指出，fetch-timeout 預設為 300000 ms（五分鐘），fetch-retries 預設為 2。

資料來源

資料來源檢查日期：2026年10月29日。man 頁面為 macOS 內建版本；在終端機中用 man <name> 開啟。