8.1 排查清单

原文链接: https://docs.brew.sh/Troubleshooting

第一步：更新并诊断

在向任何人提问之前，先按顺序执行：

1

brew update

再执行一次 brew update——第一次更新可能让失败命令仍停留在旧的 Homebrew 版本上。

1

brew doctor

读完每一条警告，修复与失败命令相关的警告，然后重试原始命令并保存完整输出。

重要：不要直接套用旧 issue 报告里的破坏性 Git、属主或权限命令。先弄清楚它们会影响哪些文件；恢复性指引见 8.2 常见问题。

第二步：搜索已有报告

按故障组件搜索对应的问题跟踪器：

• formula 问题：Homebrew/homebrew-core issues；
• cask 问题：Homebrew/homebrew-cask issues；
• brew 命令本身：Homebrew/brew issues；
• 第三方 tap 中的 formula/cask/命令：该 tap 自己的跟踪器。

还可以搜索 Homebrew Discussions。注意：旧 Discourse 论坛已下线，引用它的内容属于历史资料，可能含有过时指令。

第三步：收集诊断信息

formula 安装或构建失败时，上传日志：

1

brew gist-logs FORMULA

其他失败收集：

1
2

brew config
brew doctor

发布任何终端输出前，先移除凭据、私有仓库 URL 和其他机密。不要因为某条警告“看起来无关”就省略它。

第四步：创建 issue

如果问题既未解决也未被报告，使用对应仓库的 issue 模板，并在正文中提供：

• 完整的失败命令与错误输出；
• 相关 brew config 与 brew doctor 输出；
• 可用时的 brew gist-logs URL；
• 能标识包名、失败类型与操作系统的描述性标题。

完整的上报预期参见官方 Creating a Homebrew Issue。