macOS Monterey安装Homebrew失败报Not a valid ref错误如何修复

报错信息 #

==> Downloading and installing Homebrew...
HEAD is now at 32a3e1fe2 Merge pull request #12488 from carlocab/service-on_os
error: Not a valid ref: refs/remotes/origin/master
fatal: ambiguous argument 'refs/remotes/origin/master': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git [...] -- [...]'

报错原因 #

该错误核心诱因有两个：

• Homebrew 官方仓库已将默认主分支从master重命名为main，旧安装脚本仍在引用已不存在的master分支
• 此前安装失败残留的不完整仓库文件与新安装流程发生冲突

可行修复方案 #

方案1：清理残留后重装 #

• 第一步删除不完整的Homebrew安装目录：
  Intel芯片Mac执行：sudo rm -rf /usr/local/Homebrew
  M系列芯片Mac执行：sudo rm -rf /opt/homebrew
• 第二步清理可能冲突的git全局配置：git config --global --unset core.autocrlf
• 第三步重新执行官方安装命令：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

方案2：手动克隆仓库安装 #

如果方案1仍报错，可跳过安装脚本的分支校验步骤，手动拉取仓库：

• 创建安装目录并授权：
  Intel芯片Mac执行：sudo mkdir -p /usr/local/Homebrew && sudo chown -R $(whoami) /usr/local/Homebrew
  M系列芯片Mac执行：sudo mkdir -p /opt/homebrew && sudo chown -R $(whoami) /opt/homebrew
• 手动克隆最新的官方仓库：
  Intel芯片Mac执行：git clone https://github.com/Homebrew/brew /usr/local/Homebrew
  M系列芯片Mac执行：git clone https://github.com/Homebrew/brew /opt/homebrew
• 将brew命令加入系统环境变量：
  Intel芯片Mac执行：echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
  M系列芯片Mac执行：echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
• 重载配置生效：source ~/.zshrc，执行brew -v输出版本号即安装成功

方案3：网络异常排查 #

如果拉取仓库时出现超时、连接失败的情况，可临时切换手机热点网络重试，避免局域网DNS拦截导致的资源拉取异常。

内容的提问来源于stack exchange，提问作者praveen