Homebrew升级报错多因环境与操作不匹配，需按报错类型精准处理：网络问题换镜像或关代理，权限问题修复目录属主，链接冲突用link--overwrite，自身损坏则更新brew或运行官方修复脚本。

homebrew 升级报错，多数不是真的“坏了”，而是环境状态和升级动作不匹配导致的。关键不在重装，而在看清报错类型、定位根因、针对性处理。

先快速判断报错属于哪一类

• 如果 brew update 卡住不动或提示 fatal: unable to access...：大概率是网络或 Git 仓库同步问题
• 如果 brew upgrade 运行中报 Permission denied 或 Could not symlink：通常是目录权限或文件冲突
• 如果执行后提示 Error: Command failed 并带 Ruby 错误堆栈：可能涉及 Homebrew 自身损坏或 Ruby 环境异常
• 如果 brew doctor 输出一堆 warning，再升级就失败：说明系统状态已不健康，需先修复基础环境

常见报错场景与对应操作

• Git 同步失败（update 卡住 / fetch 超时）

  • 检查是否配置了代理：git config --global http.proxy 和 https.proxy，临时关闭可试 git config --global --unset http.proxy
  • 切换国内镜像源（尤其对大陆用户）：

    git -C $(brew --repo) remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git
    git -C $(brew --repo)/Library/Taps/homebrew/homebrew-core remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git

  • 手动拉取：cd $(brew --repo) && git fetch origin master

• 权限错误（如 /usr/local 或 /opt/homebrew 下 Permission denied）

  • 不要用 sudo brew！正确做法是修复目录所有权：
    • Intel Mac：sudo chown -R $(whoami) /usr/local
    • Apple Silicon：sudo chown -R $(whoami) /opt/homebrew
  • 再运行 brew doctor 确认无 Invalid permissions 类警告

• 链接冲突（Error: The brew link step did not complete successfully）

  • 常见于重复安装、手动拷贝二进制、或旧版本残留
  • 先看冲突文件：brew link --overwrite <formula> --dry-run
  • 确认无误后覆盖：brew link --overwrite <formula>
  • 若批量出问题，可先 brew unlink <formula> 再 brew link <formula>

• 升级中途中断或 Homebrew 自身损坏

  • 先尝试自我修复：brew update && brew upgrade brew（单独升级 brew 本身）
  • 若仍失败，用官方修复脚本：

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    （该脚本会检测已有安装，仅更新不覆盖）

升级前建议养成两个习惯

• 每次升级前跑一次 brew doctor，把 warning 当 checklist 处理完再升
• 避免在升级过程中手动中断（比如 ⌘+C），容易留下半状态；若已中断，先 brew update 再 brew upgrade

不复杂但容易忽略