錯誤訊息

Mac 上的「npm error code ECONNRESET」

ECONNRESET 表示另一端強制關閉了連線。Node.js 說明文件稱之為「Connection reset by peer」。

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

症狀

  • npm install 停止並顯示 npm error code ECONNRESET。
  • npm 另外指出這是與網路連線有關的問題。
  • 在公司網路、VPN 上，或使用安全性 App 時發生。

可能原因

  • 會重設連線的代理伺服器或過濾器。公司的代理伺服器或安全性軟體可能會關閉它不允許的連線。
  • TLS 檢查。檢查加密流量的代理伺服器可能會中斷連線。請參閱「公司代理伺服器憑證導致 Mac 上的終端機工具無法使用」。
  • 會重新連線的 VPN。VPN 重新連線時，經過它的連線都會關閉。
  • 不穩定的連線。Node.js 說明文件指出，遠端逾時或重新開機都可能造成此錯誤。

如何檢查

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

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

  2. 確認 registry 有回應。

    npm ping

  3. 使用 curl 測試 registry，並查看憑證簽發者。

    curl -v -o /dev/null https://registry.npmjs.org/ 2>&1 | grep -i issuer

  4. 在其他網路（例如手機熱點）上嘗試安裝。

如何修正

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

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

  2. 如果公司代理伺服器會檢查 TLS，請為 Node.js 加入其根憑證。請參閱「公司代理伺服器憑證導致 Mac 上的終端機工具無法使用」。

  3. 增加 npm 的重試次數。

    npm config set fetch-retries 5

  4. 如果開啟了 VPN、代理伺服器或安全 App，請暫時關閉進行測試，測試後再重新開啟。

使用 Kilobat

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

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

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

常見問題

ECONNRESET 是我專案的錯誤嗎？

通常不是。這代表連到 registry 的連線被關閉了。在其他網路上執行相同的安裝來比較。

資料來源

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