安装Homebrew报错not a valid ref: refs/remotes/origin/master如何解决

• Homebrew 旗下homebrew-core、homebrew-cask等核心代码仓库早已将默认分支名从早期的master修改为main，如果本地存在之前安装失败残留的仓库文件、或者旧版本安装脚本未同步分支配置，就会尝试拉取不存在的origin/master分支引用，直接触发Not a valid ref、invalid upstream类报错。
• 跨洋网络拉取代码仓库时经常出现丢包、元数据拉取不全的问题，会进一步提升该错误的出现概率。
• 安装中途中断留下的损坏本地仓库缓存，会让后续的安装流程直接读取错误配置，无法自动修正分支指向。

注：Apple Silicon芯片Mac的Homebrew默认安装路径为/opt/homebrew，Intel芯片Mac的默认安装路径为/usr/local，执行后续操作时请根据自己的设备芯片替换对应路径。

按顺序在终端执行以下操作即可完成正常安装：

1. 彻底清理历史残留的损坏文件，避免旧配置干扰新安装流程

   sudo rm -rf /opt/homebrew
   sudo rm -rf ~/.cache/Homebrew
   

2. 调整Git全局网络参数，降低大仓库拉取时的超时失败概率

   git config --global core.compression 0
   git config --global http.lowSpeedLimit 0
   git config --global http.lowSpeedTime 999999
   

3. 手动创建Homebrew安装目录并给当前用户授予读写权限

   sudo mkdir -p /opt/homebrew
   sudo chown -R $(whoami) /opt/homebrew
   

4. 克隆Homebrew主程序到安装目录，强制指定拉取main分支，跳过自动分支检测逻辑

   git clone --depth=1 Homebrew主仓库地址 /opt/homebrew
   

   若直接拉取官方仓库速度过慢，可自行替换为可正常访问的镜像源地址，不影响后续功能使用。

5. 创建第三方Tap目录，手动拉取核心仓库文件，同样强制指定main分支

   mkdir -p /opt/homebrew/Library/Taps/homebrew
   git clone --depth=1 homebrew-core仓库地址 /opt/homebrew/Library/Taps/homebrew/homebrew-core
   git clone --depth=1 homebrew-cask仓库地址 /opt/homebrew/Library/Taps/homebrew/homebrew-cask
   

6. 将Homebrew执行路径写入终端配置文件，macOS Monterey默认使用zsh，执行以下命令即可：

   echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   

   如果使用bash作为默认shell，把上述命令里的.zshrc替换为.bash_profile即可。

7. 执行更新命令验证安装状态

   brew update
   

所有步骤执行完成后，输入brew -v，如果能正常输出版本号信息，就代表安装完成，可以正常使用。

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