8.2 常见问题：运行、下载与系统升级
3 分钟阅读
本页覆盖反复出现的 Homebrew 问题及当前推荐的非破坏性诊断步骤。先从 8.1 排查清单 开始，完整阅读错误信息，再修改文件或权限。
缺少 Command Line Tools
在 macOS 上从源码构建 formula 需要 Xcode Command Line Tools。反直觉的是：只安装完整 Xcode 并不够，CLT 是独立安装包：
| |
cask 与 bottle 没有开发者工具也能安装，但此时 brew doctor 仍会报告“不支持该配置”。
bad interpreter: /usr/bin/ruby^M
此错误通常表示 Homebrew 检出目录里的文件带有 Windows 行尾，多由 Git 配置引起。请先对照 GitHub 的 配置 Git 行尾 指南，然后按下文方式 brew update-reset 恢复 Homebrew 仓库。
本地修改导致 brew update 失败
先检查 brew update 报出的仓库状态：
| |
把第二条中的 USER/REPOSITORY 换成错误信息里提到的每个 tap。除非你是 Homebrew 或 tap 维护者，本地修改几乎可以肯定是无意的，重置是正确的修复。请先保留任何在 Homebrew 或 tap 中有意做的工作；不要执行从旧 issue 里随便复制的 git clean 或 git reset --hard。
然后只重置受影响的仓库：
| |
只运行适用的命令。brew update-reset 会把指定仓库取回并重置到上游默认分支，会销毁这些仓库中未提交与已提交的本地修改，因此先看它的帮助并保存好工作。不带仓库参数运行会重置 Homebrew 与所有 tap。
Git 检出或网络失败
类似 early EOF、index-pack failed、连接 GitHub 失败的错误，通常意味着网络、代理、镜像或过滤问题：
- 在同一个 shell 中确认能访问 GitHub 和下载主机；
- 检查代理环境变量、VPN、防火墙与网络监控工具；
- 运行
brew config查看已配置的 Git 或 bottle 镜像； - 在稳定网络下重试，再决定是否上报。
只有用 Homebrew 才能稳定复现时，才走 8.1 排查清单 并附上确切命令与输出。
curl 配置问题
用户级 curl 配置会改变代理、证书、协议或输出行为。检查 ~/.curlrc 与 CURL_* 环境变量，不要盲目删除配置。可临时关闭自定义设置测试，再修正导致失败的具体项。curl 的 退出码参考 与 libcurl 错误参考 能解释常见传输错误。
macOS 系统升级之后
macOS 升级可能替换或失效已装 formula 依赖的 CLT 与库。官方建议：
- 安装全部可用的 macOS 更新；
- 当
brew doctor报告 CLT 问题时，重新安装或更新 Xcode Command Line Tools； - 执行
brew update； - 执行
brew upgrade重建或重装过期的 formula。
不要为缺失的版本化库创建符号链接：那会掩盖未完成的升级，并让不兼容的软件加载错误的库。
同时存在两套 Homebrew 安装
迁移助理（Migration Assistant）或在 Apple Silicon 上使用 x86_64 终端，都可能导致 /usr/local 与 /opt/homebrew 两套安装同时存在。先检查当前进程架构与可执行文件路径：
| |
Apple Silicon 的 shell 通常应报告 arm64 并使用 /opt/homebrew。删除旧的 Intel 安装前，先用它自己的可执行文件记录已装软件：
| |
检查生成的 ~/intel-Brewfile，在正确前缀下重装确认无误后，再按照官方卸载指引删除旧安装。
恢复整个安装环境
若 brew doctor 与前面的检查仍无法定位问题，先创建并检查软件清单再重装：
| |
把生成的 Brewfile 保存在 Homebrew 前缀之外，按官方卸载/安装文档操作，再用以下命令恢复：
| |
详细说明见 6.2 用 brew bundle 管理机器状态。