开发者

Mac 上 Homebrew 或 npm 下载失败

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

根据 npm 文档，fetch-timeout 默认为 300000 ms，即 5 分钟；fetch-retries 默认为 2。

Homebrew 用 curl 和 Git 下载，npm 从它的 registry 下载。每个工具都读取自己的代理和证书设置。

适用于：当前版本的 Homebrew 和 npm，所有当前 macOS 版本。核查日期：2026年10月29日

症状

工具不知道代理。Homebrew 使用 http_proxy、https_proxy 和 all_proxy。npm 使用自己的 proxy 和 https-proxy 设置，或同样的环境变量。
TLS 检查。公司代理会用自己的证书为流量签名。参阅“公司代理证书导致 Mac 上的终端工具出错”。
npm registry 设置错误。旧的 registry 设置可能指向无法访问的服务器。
连接慢或按流量计费。在信号弱的 Wi-Fi 或热点上，大文件下载可能超时。

显示 npm 的 registry 和代理设置。

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

直接用 curl 测试下载主机。

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

在代理后面使用 Homebrew 时，在同一个 shell 中设置代理环境变量。
```
export https_proxy=http://proxy.example.com:8080
```

在代理后面使用 npm 时，设置 npm 代理。

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

删除旧的 npm registry 设置，让 npm 使用默认值。
```
npm config delete registry
```
让 Homebrew 对失败的下载多重试几次。
```
export HOMEBREW_CURL_RETRIES=5
```
如果公司使用镜像，进行相应设置。Homebrew 用 HOMEBREW_BOTTLE_DOMAIN 和 HOMEBREW_API_DOMAIN 指定镜像。
遇到证书错误时，添加公司的根证书。参阅“公司代理证书导致 Mac 上的终端工具出错”。

进行大型安装前，检查网络是否按流量计费、是否在 VPN 上，或者速度慢。
```
kilobat conditions
```
找出阻断下载主机的那一层。加上 --app 可使用该进程的代理环境变量。
```
kilobat why https://ghcr.io/v2/homebrew/core --app process:curl
```
安装过程中保持 Mac 唤醒。
```
kilobat awake -- brew upgrade
```
这些命令免费。参阅“智能体下载大文件前先检查网络”。

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

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

npm 会等待多久？

根据 npm 文档，fetch-timeout 默认为 300000 ms，即 5 分钟；fetch-retries 默认为 2。

参考资料核查于 2026年10月29日。man 手册页为 macOS 自带版本；在“终端”中用 man <name> 打开。