问题描述
我的 macOS 系统上的 Homebrew 一直处于不可用状态，无法正常更新和安装软件包。每次尝试使用 Homebrew 时都会遇到各种错误，严重影响了开发工作效率。
问题诊断
第一步：检查 Homebrew 版本
首先，我运行了版本检查命令：
brew --version
实际输出：
Homebrew 5.1.1
✅ Homebrew 本身已安装，版本是 5.1.1。这说明问题不是 Homebrew 没装好，而是其他原因。
第二步：运行诊断命令
接着，我运行了 Homebrew 的诊断命令：
brew doctor
实际输出：
Please note that these warnings are just used to help the Homebrew maintainers
with debugging if you file an issue. If everything you use Homebrew for is
working fine: please don't worry or file an issue; just ignore this. Thanks!
Warning: Suspicious https://github.com/Homebrew/brew git origin remote found.
The current git origin is:
https://mirrors.ustc.edu.cn/brew.git
With a non-standard origin, Homebrew won't update properly.
You can solve this by setting the origin remote:
git -C "/usr/local/Homebrew" remote set-url origin https://github.com/Homebrew/brew
Warning: A newer Command Line Tools release is available.
Update them from Software Update in System Settings.
Warning: Some installed kegs have no formulae!
This means they were either deleted or installed manually.
You should find replacements for the following formulae:
openssl@1.1
Warning: Unbrewed dylibs were found in /usr/local/lib.
If you didn't put them there on purpose they could cause problems when
building Homebrew formulae and may need to be deleted.
Unexpected dylibs:
/usr/local/lib/libltdl.7.dylib
Warning: Unbrewed header files were found in /usr/local/include.
If you didn't put them there on purpose they could cause problems when
building Homebrew formulae and may need to be deleted.
Unexpected header files:
/usr/local/include/libltdl/*
/usr/local/include/ltdl.h
第三步：分析诊断输出
从 brew doctor 的输出中，我逐条分析发现了 5 个问题：
问题 1：Git 源配置异常
输出内容：
Warning: Suspicious https://github.com/Homebrew/brew git origin remote found.
The current git origin is:
https://mirrors.ustc.edu.cn/brew.git
分析过程：
- Homebrew 的 Git 源应该是官方源
https://github.com/Homebrew/brew.git - 但我的系统配置的是国内镜像源
https://mirrors.ustc.edu.cn/brew.git - 这说明之前为了加速，我或某个工具修改过镜像源配置
- 问题影响：虽然镜像源可以下载，但 Homebrew 官方认为这是"可疑"配置，可能会影响更新
问题 2：Command Line Tools 过期
输出内容：
Warning: A newer Command Line Tools release is available.
Update them from Software Update in System Settings.
分析过程：
- Command Line Tools 是 macOS 编译工具链的核心组件
- 过期版本可能导致某些软件包编译失败
- 这不是导致 Homebrew "不可用"的主要原因，但需要关注
问题 3：孤立的软件包
输出内容：
Warning: Some installed kegs have no formulae!
This means they were either deleted or installed manually.
You should find replacements for the following formulae:
openssl@1.1
分析过程：
keg是 Homebrew 对已安装软件包的称呼formulae是 Homebrew 的软件包定义文件openssl@1.1已安装，但 Homebrew 找不到它的定义文件了- 这通常是因为该版本已被 Homebrew 官方移除
- 问题影响：不影响使用，但会产生警告信息
问题 4：未管理的动态库文件
输出内容：
Warning: Unbrewed dylibs were found in /usr/local/lib.
Unexpected dylibs:
/usr/local/lib/libltdl.7.dylib
Warning: Unbrewed header files were found in /usr/local/include.
Unexpected header files:
/usr/local/include/libltdl/*
/usr/local/include/ltdl.h
分析过程：
dylibs是 macOS 的动态链接库文件（类似 Windows 的 .dll）- 这些文件在
/usr/local/lib和/usr/local/include中 - 但它们不是通过 Homebrew 安装的，所以被称为 "Unbrewed"
- 我进一步检查了这些文件：
ls -la /usr/local/lib/libltdl*
输出：
-rwxr-xr-x 1 root wheel 57024 Jan 19 2020 /usr/local/lib/libltdl.7.dylib
-rw-r--r-- 1 root wheel 157360 Jan 19 2020 /usr/local/lib/libltdl.a
lrwxr-xr-x 1 root wheel 15 Jan 19 2020 /usr/local/lib/libltdl.dylib -> libltdl.7.dylib
-rwxr-xr-x 1 root wheel 913 Jan 19 2020 /usr/local/lib/libltdl.la
发现：
- 这些文件创建于 2020 年 1 月 19 日
- 属于
libtool工具的旧版本 - 可能是以前手动安装或通过其他方式遗留的
- 问题影响：可能与其他软件包产生冲突
问题 5：未链接的软件包
在后续检查中，我还发现了另一个问题：
brew link autoconf
输出：
Error: Could not symlink bin/autoconf
Target /usr/local/bin/autoconf
already exists.
分析过程：
autoconf已安装但未正确链接到系统路径/usr/local/bin/autoconf已存在，可能是旧文件- 问题影响：可能导致使用了错误版本的 autoconf
第四步：尝试修复 Git 源，发现根本问题
根据 brew doctor 的建议，我尝试将 Git 源改回官方源：
git -C "/usr/local/Homebrew" remote set-url origin https://github.com/Homebrew/brew
然后尝试更新：
brew update
实际输出：
fatal: unable to access 'https://github.com/Homebrew/brew/':
Failed to connect to github.com port 443 after 75003 ms:
Couldn't connect to server
Error: Fetching /usr/local/Homebrew...
关键发现：
- 等待了 75 秒（75003 ms）后连接失败
- 错误信息明确：
Couldn't connect to server - 这说明根本问题不是 Homebrew 配置，而是网络无法访问 GitHub！
第五步：网络连接诊断
为了确认网络问题，我进行了多项测试：
测试 1：Ping 外网 IP
ping -c 3 8.8.8.8
输出：
Request timeout for icmp_seq 0
Request timeout for icmp_seq 1
--- 8.8.8.8 ping statistics ---
3 packets transmitted, 0 packets received, 100.0% packet loss
分析：
- 8.8.8.8 是 Google 的公共 DNS 服务器
- 100% 丢包说明完全无法连接外网
- 这不是 DNS 问题，而是网络连接本身的问题
测试 2：尝试访问 GitHub
curl -I https://github.com
输出：
curl: (28) Failed to connect to github.com port 443 after 75000 ms:
Couldn't connect to server
分析：
- HTTPS 连接超时（443 端口）
- 无法访问任何 GitHub 服务
测试 3：测试国内镜像
curl -I https://mirrors.aliyun.com
输出：
HTTP/2 301
server: Tengine
分析：
- 阿里云镜像可以正常访问
- 说明国内网络是通的，只是无法访问国外服务器
诊断结论
通过以上步骤，我确定了问题的根本原因：
| 问题层级 | 问题内容 | 影响程度 |
|---|---|---|
| 根本原因 | 网络无法访问 GitHub（外网不通） | 🔴 严重 |
| 次要问题 1 | Git 源配置为国内镜像 | 🟡 中等 |
| 次要问题 2 | Command Line Tools 过期 | 🟡 中等 |
| 次要问题 3 | 孤立包 openssl@1.1 | 🟢 轻微 |
| 次要问题 4 | 未管理的 libltdl 文件 | 🟢 轻微 |
| 次要问题 5 | autoconf 未链接 | 🟢 轻微 |
解决思路：
- 由于外网无法访问，改回官方源没有意义
- 正确的做法是：保持使用国内镜像源，让 Homebrew 继续工作
网络连接诊断
我进行了详细的网络诊断：
# 测试外网连接
ping -c 3 8.8.8.8
# 测试 GitHub 连接
curl -I https://github.com
# 测试国内镜像连接
curl -I https://mirrors.aliyun.com
诊断结果：
| 测试项 | 结果 | 说明 |
|---|---|---|
| 外网连接（8.8.8.8） | ❌ 100% 丢包 | 完全无法连接外网 |
| GitHub 连接 | ❌ 超时 | 无法访问国外服务器 |
| 国内镜像 | ✅ 可访问 | 阿里云镜像可以连接 |
网络配置分析
# 查看网络接口
ifconfig | grep -A 5 "en0:"
# 查看 Wi-Fi 配置
networksetup -getinfo Wi-Fi
# 查看路由表
route -n get default
# 查看 DNS 配置
cat /etc/resolv.conf
网络配置信息：
- IP 地址：10.10.26.199（内网 IP）
- 子网掩码：255.255.252.0
- 网关：存在两个网关
- 10.10.24.1（Wi-Fi 网关）
- 10.10.11.1（默认路由网关）
- DNS 服务器：
- 202.96.128.86
- 223.6.6.6（阿里云）
- 223.5.5.5（阿里云）
- 114.114.114.114（114DNS）
问题分析：
- 使用的是内网 IP（10.10.x.x），说明在公司网络或受限网络环境中
- 存在多个网关配置，可能导致路由混乱
- 无法访问外网，可能原因：
- 网络接口冲突（en0 和 en7 同时活跃）
- VPN 已断开连接
- 防火墙阻止外网访问
- 网关故障
修复方案
方案一：配置国内镜像源（推荐）
由于网络无法访问 GitHub，我采用了配置国内镜像源的方案，使 Homebrew 能够继续工作。
步骤 1：修改 Homebrew Git 源
git -C "/usr/local/Homebrew" remote set-url origin https://mirrors.aliyun.com/homebrew/brew.git
步骤 2：配置环境变量
为了使镜像源配置永久生效，我将环境变量添加到 shell 配置文件：
cat >> ~/.zshrc << 'EOF'
# Homebrew 国内镜像配置
export HOMEBREW_BREW_GIT_REMOTE=https://mirrors.aliyun.com/homebrew/brew.git
export HOMEBREW_CORE_GIT_REMOTE=https://mirrors.aliyun.com/homebrew/homebrew-core.git
export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.aliyun.com/homebrew/homebrew-bottles
EOF
配置说明：
HOMEBREW_BREW_GIT_REMOTE：Homebrew 核心仓库源HOMEBREW_CORE_GIT_REMOTE：Homebrew Core 仓库源HOMEBREW_BOTTLE_DOMAIN：预编译二进制包源
步骤 3：更新 Homebrew
export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.aliyun.com/homebrew/homebrew-bottles
brew update
结果：
==> Updating Homebrew...
Already up-to-date.
方案二：清理系统文件（可选）
虽然需要 sudo 权限，但我记录了清理步骤供参考：
# 删除旧的 libtool 文件
sudo rm -rf /usr/local/lib/libltdl* /usr/local/include/libltdl* /usr/local/include/lt_*.h
# 清理 Homebrew 缓存
brew cleanup
方案三：修复 autoconf 链接（可选）
# 强制覆盖链接
brew link --overwrite autoconf
注意： 如果遇到权限问题，需要修改目录权限：
sudo chown -R $(whoami) /usr/local/share/autoconf
brew link --overwrite autoconf
测试结果
验证 Homebrew 功能
测试 1：检查 Homebrew 版本
brew --version
输出：
Homebrew 5.1.1
✅ 通过
测试 2：搜索软件包
brew search curl
输出：
awscurl
curl
curlcpp
curlie
curlpp
flickcurl
grpcurl
carl
cursr
font-iosevka-curly
font-iosevka-curly-slab
✅ 通过 - 能够正常搜索软件包
测试 3：列出已安装的软件包
brew list
输出（部分）：
autoconf
m4
maven
nginx
openjdk
openssl@1.1
pcre
scala-cli
✅ 通过 - 能够正常列出已安装的软件包
测试 4：安装新软件包
作为最终测试，我尝试安装 ffmpeg：
brew install ffmpeg
安装过程：
-
下载依赖包（10 个）：
- dav1d
- lame
- libvpx
- ca-certificates
- openssl@3
- opus
- sdl2
- svt-av1
- x264
- x265
-
安装 ffmpeg 主程序
安装结果：
🍺 /usr/local/Cellar/ffmpeg/8.1: 287 files, 56.7MB
测试 5：验证安装
ffmpeg -version
输出：
ffmpeg version 8.1 Copyright (c) 2000-2026 the FFmpeg developers
built with Apple clang version 16.0.0 (clang-1600.0.26.6)
configuration: --prefix=/usr/local/Cellar/ffmpeg/8.1 --enable-shared --enable-pthreads --enable-version3 --cc=clang --host-cflags= --host-ldflags= --enable-ffplay --enable-gpl --enable-libsvtav1 --enable-libopus --enable-libx264 --enable-libmp3lame --enable-libdav1d --enable-libvpx --enable-libx265 --enable-openssl --videotoolbox --enable-audiotoolbox
libavutil 60. 26.100 / 60. 26.100
libavcodec 62. 28.100 / 62. 28.100
✅ 通过 - ffmpeg 安装成功并可正常使用
最终状态
| 项目 | 状态 | 说明 |
|---|---|---|
| Homebrew 版本检查 | ✅ 正常 | 版本 5.1.1 |
| 软件包搜索 | ✅ 正常 | 能够搜索软件包 |
| 软件包列表 | ✅ 正常 | 能够列出已安装软件 |
| 软件包安装 | ✅ 正常 | 成功安装 ffmpeg 及其依赖 |
| 外网连接 | ❌ 无法连接 | 但不影响 Homebrew 使用 |
关键要点总结
-
问题根源：网络无法访问 GitHub，导致 Homebrew 无法从官方源更新
-
解决方案：配置国内镜像源（阿里云），使 Homebrew 能够继续工作
-
环境变量配置：通过在
~/.zshrc中添加环境变量，使镜像源配置永久生效 -
验证方法：通过搜索、列表、安装等多个测试验证 Homebrew 功能
-
后续建议：
- 如果需要访问 GitHub，需要解决网络连接问题
- 可以尝试连接 VPN 或联系网络管理员
- 定期运行
brew cleanup清理缓存和旧版本
参考资源
文档生成时间：2026-03-25 11:45 GMT+8
系统环境：macOS Sonoma (Darwin 24.6.0)
Homebrew 版本：5.1.1
