---
title: "Mac 上 brew install 或 npm install 因網路錯誤而失敗 · Kilobat 指南"
url: "https://kilobat.app/zh-hant/guides/homebrew-npm-download-fails.html"
description: "找出 brew install 或 npm install 為什麼因逾時、代理伺服器或憑證錯誤而停止，並設定網路需要的代理伺服器、鏡像站或憑證。"
---

開發者

# Mac 上的 Homebrew 或 npm 下載失敗

Homebrew 用 curl 和 Git 下載，npm 則從它的 registry 下載。每個工具各自讀取自己的代理伺服器和憑證設定。

適用於：目前的 Homebrew 和 npm，所有目前的 macOS 版本。 · 檢查日期：2026年10月29日

## 症狀

- `brew install` 停止，顯示「curl: (28) … timed out」或「Failed to download resource」。
- `npm install` 停止，顯示 ETIMEDOUT、ECONNRESET 或憑證錯誤。
- 只有在公司網路或 VPN 上下載才會失敗。
- 在慢速連線上，下載開始後又停止。

## 可能原因

- **工具不知道代理伺服器。**Homebrew 使用 `http_proxy`、`https_proxy` 和 `all_proxy`。npm 使用自己的 `proxy` 和 `https-proxy` 設定，或同樣的環境變數。
- **TLS 檢查。**公司的代理伺服器會用自己的憑證簽署流量。請參閱「[公司代理伺服器憑證讓 Mac 上的終端機工具出錯](https://kilobat.app/zh-hant/guides/corporate-proxy-certificates.html)」。
- **npm registry 設定錯誤。**舊的 `registry` 設定可能指向你連不到的伺服器。
- **連線緩慢或為計量網路。**在微弱的 Wi-Fi 或熱點上，大型下載可能逾時。

## 如何檢查

1. 讓 Homebrew 檢查你的系統。

   ```
   brew doctor
   ```
2. 顯示 Homebrew 與系統的組態。

   ```
   brew config
   ```
3. 顯示 npm 的 registry 和代理伺服器設定。

   ```
   npm config get registry
   npm config get proxy
   npm config get https-proxy
   ```
4. 向 npm registry 要求回應。

   ```
   npm ping
   ```
5. 直接用 curl 測試下載主機。

   ```
   curl -v -o /dev/null https://formulae.brew.sh/api/formula.json
   ```

## 如何修正

1. Homebrew 在代理伺服器後方時，在同一個 shell 中設定代理伺服器環境變數。

   ```
   export https_proxy=http://proxy.example.com:8080
   ```
2. npm 在代理伺服器後方時，設定 npm 的代理伺服器。

   ```
   npm config set https-proxy http://proxy.example.com:8080
   ```
3. 移除舊的 npm registry 設定，讓 npm 使用預設值。

   ```
   npm config delete registry
   ```
4. 讓 Homebrew 對失敗的下載多試幾次。

   ```
   export HOMEBREW_CURL_RETRIES=5
   ```
5. 如果公司使用鏡像站，就設定它。Homebrew 用 `HOMEBREW_BOTTLE_DOMAIN` 和 `HOMEBREW_API_DOMAIN` 設定鏡像站。
6. 如果是憑證錯誤，加入公司的根憑證。請參閱「[公司代理伺服器憑證讓 Mac 上的終端機工具出錯](https://kilobat.app/zh-hant/guides/corporate-proxy-certificates.html)」。

## 使用 Kilobat

1. 大型安裝前，先檢查網路是否為計量網路、是否在 VPN 上，或是否很慢。

   ```
   kilobat conditions
   ```
2. 找出是哪一層擋住了下載主機。加上 `--app` 以使用該程序的代理伺服器環境變數。

   ```
   kilobat why https://ghcr.io/v2/homebrew/core --app process:curl
   ```
3. 安裝期間讓 Mac 保持喚醒。

   ```
   kilobat awake -- brew upgrade
   ```
4. 這些指令免費。請參閱「[在 AI 代理程式執行大型下載前檢查網路](https://kilobat.app/zh-hant/guides/recipes/check-network-before-download.html)」。

## 常見問題

**Homebrew 會使用「系統設定」中的代理伺服器嗎？**

Homebrew 的文件列出了 curl、Git 和 Subversion 的代理伺服器環境變數。請在 shell 中設定 `https_proxy`。

**npm 會等多久？**

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

## 資料來源

- [Homebrew 文件：Manpage，環境變數](https://docs.brew.sh/Manpage)
- [npm 文件：config](https://docs.npmjs.com/cli/v11/using-npm/config)
- curl(1)，macOS 27.2 內建的 man 頁面

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

## 相關指南

- [公司代理伺服器憑證導致 Mac 上的終端機工具失效](https://kilobat.app/zh-hant/guides/corporate-proxy-certificates.html): 有些公司網路會檢查 HTTPS 流量。
- [代理伺服器設定讓 Mac 上的 App 無法連線](https://kilobat.app/zh-hant/guides/proxy-settings-breaking-apps.html): 代理伺服器設定會讓流量經由另一台伺服器傳送。
- [在 AI 代理程式執行大型下載前檢查網路](https://kilobat.app/zh-hant/guides/recipes/check-network-before-download.html): AI 代理程式可以詢問 Kilobat，現在是否適合進行大型傳輸。
- [Mac 上的 SSH 和 Git 逾時](https://kilobat.app/zh-hant/guides/ssh-git-timeouts.html): SSH 和 Git 需要與伺服器之間有正常的 TCP 連線。
- [Mac 上的「npm error code ETIMEDOUT」](https://kilobat.app/zh-hant/guides/npm-etimedout.html): ETIMEDOUT 表示對方沒有及時回應。