---
title: "Mac 上的 npm error code ETIMEDOUT：修正 npm 網路逾時 · Kilobat 指南"
url: "https://kilobat.app/zh-hant/guides/npm-etimedout.html"
description: "在 Mac 上執行 npm install 時出現 npm error code ETIMEDOUT 並停止。檢查 registry、代理伺服器和連線，然後更改 npm 的設定。"
---

錯誤訊息

# 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 連不上的原因](https://kilobat.app/zh-hant/guides/recipes/why-cant-it-connect.html)。

## 常見問題

**npm 會等多久？**

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

## 資料來源

- [Node.js 說明文件：Common system errors](https://nodejs.org/api/errors.html#common-system-errors)
- [npm 文件：config](https://docs.npmjs.com/cli/v11/using-npm/config)
- curl(1) 和 networkQuality(8)，macOS 27.2 內建的 man 頁面

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

## 相關指南

- [Mac 上的「npm error code ECONNRESET」](https://kilobat.app/zh-hant/guides/npm-econnreset.html): ECONNRESET 表示對方強制關閉了連線。
- [Mac 上的 Homebrew 或 npm 下載失敗](https://kilobat.app/zh-hant/guides/homebrew-npm-download-fails.html): Homebrew 使用 curl 和 Git 下載。
- [代理伺服器設定讓 Mac 上的 App 無法連線](https://kilobat.app/zh-hant/guides/proxy-settings-breaking-apps.html): 代理伺服器設定會讓流量經由另一台伺服器傳送。
- [公司代理伺服器憑證導致 Mac 上的終端機工具失效](https://kilobat.app/zh-hant/guides/corporate-proxy-certificates.html): 有些公司網路會檢查 HTTPS 流量。
- [在 AI 代理程式執行大型下載前檢查網路](https://kilobat.app/zh-hant/guides/recipes/check-network-before-download.html): AI 代理程式可以詢問 Kilobat，現在是否適合進行大型傳輸。