---
title: "Mac 上 brew install 或 npm install 因网络错误失败 · Kilobat 指南"
url: "https://kilobat.app/zh-hans/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-hans/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-hans/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. 这些命令免费。参阅“[智能体下载大文件前先检查网络](https://kilobat.app/zh-hans/guides/recipes/check-network-before-download.html)”。

## 常见问题

**Homebrew 会使用“系统设置”中的代理吗？**

Homebrew 的文档列出了 curl、Git 和 Subversion 的代理环境变量。在 shell 中设置 `https_proxy`。

**npm 会等待多久？**

根据 npm 文档，`fetch-timeout` 默认为 300000 ms，即 5 分钟；`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-hans/guides/corporate-proxy-certificates.html): 一些公司网络会检查 HTTPS 流量。
- [Mac 上代理设置导致 App 无法连接](https://kilobat.app/zh-hans/guides/proxy-settings-breaking-apps.html): 代理设置会让流量经由另一台服务器转发。
- [智能体下载大文件前先检查网络](https://kilobat.app/zh-hans/guides/recipes/check-network-before-download.html): 智能体可以询问 Kilobat 现在是否适合进行大量传输。
- [Mac 上 SSH 和 Git 超时](https://kilobat.app/zh-hans/guides/ssh-git-timeouts.html): SSH 和 Git 需要与服务器之间有可用的 TCP 连接。
- [Mac 上出现“npm error code ETIMEDOUT”](https://kilobat.app/zh-hans/guides/npm-etimedout.html): ETIMEDOUT 表示对方没有及时应答。