错误信息

Mac 上 Homebrew 失败并提示“curl: (28)”

Homebrew 用 curl 下载。curl 退出码 28 表示超时。curl 文档的说法是：“The specified time-out period was reached.”（已达到指定的超时时间）

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

症状

  • brew install 因 curl: (28) 中止，随后提示时间已用完。
  • Homebrew 提示下载资源失败。
  • 在慢速网络、VPN 或公司网络上下载失败。

可能的原因

  • 连接慢或丢包。在信号弱的 Wi-Fi 或热点上，较大的 bottle 会超时。
  • curl 没有使用代理。Homebrew 使用 http_proxy、https_proxy 和 all_proxy。
  • 防火墙丢弃流量。如果网络丢弃到下载主机的连接，就会超时。
  • IPv6 路径不通。下载主机有 IPv6 地址，而 IPv6 无法使用。

如何检查

  1. 让 Homebrew 检查系统。

    brew doctor

  2. 用 curl 测试下载主机，仅使用 IPv4。

    curl -4 -I https://ghcr.io/v2/

  3. 显示代理环境变量。

    env | grep -i proxy

  4. 测量连接质量。

    networkQuality

如何修复

  1. 让 Homebrew 多重试几次。默认重试 3 次。

    export HOMEBREW_CURL_RETRIES=5

  2. 如果网络需要代理，在同一个 shell 中设置。

    export https_proxy=http://proxy.example.com:8080

  3. 如果公司有镜像，设置 HOMEBREW_BOTTLE_DOMAIN 和 HOMEBREW_API_DOMAIN。

  4. 如果可以，换到更快的网络上再运行一次命令。

使用 Kilobat

  1. 检查网络是否按流量计费、是否在 VPN 上，或者速度慢。

    kilobat conditions

  2. Kilobat 的连接诊断逐层测试主机：网络、代理、DNS、规则、IPv4、IPv6、TLS 和服务器，并指出失败的那一层。

    kilobat why https://ghcr.io/v2/

  3. 安装过程中保持 Mac 唤醒。

    kilobat awake -- brew upgrade

  4. Kilobat 的这些检查都是免费的。AI 智能体可以通过 MCP 用 diagnose_connection 和 diagnose_network 运行它们。请参阅找出某个网站或 API 连不上的原因。

常见问题

curl 错误 28 是什么？

它是 CURLE_OPERATION_TIMEDOUT。curl 的 man 手册页将退出码 28 列为操作超时。

参考资料

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