很多使用 Apple Silicon（M1/M2/M3 等）芯片的 Mac 用户，在执行 Homebrew 命令时，会遇到经典 CPU 架构不匹配报错，本文将深度解析问题原因，并提供临时应急和永久根治两套方案，脚本采用清华镜像官方推荐方式，国内稳定可用。
一、完整报错信息
/usr/local/Homebrew/Library/Homebrew/brew.sh: line 1188: /usr/local/Homebrew/Library/Homebrew/vendor/portable-ruby/current/bin/ruby: Bad CPU type in executable
/usr/local/Homebrew/Library/Homebrew/brew.sh: line 1188: /usr/local/Homebrew/Library/Homebrew/vendor/portable-ruby/current/bin/ruby: Undefined error: 0
二、问题核心根源
该报错的本质是 CPU 架构不匹配，也是 M 系列 Mac 最常见的 Brew 环境问题：
- 你的设备：Apple Silicon M 系列芯片，原生架构为 arm64
- 当前 Brew 版本：安装在
/usr/local/Homebrew的 Intel x86_64 旧版本 - 冲突点：旧版 Intel 架构的 Brew 自带的 Ruby 二进制程序，无法在 ARM 原生环境运行，直接触发 CPU 类型错误
关键路径区分（必记） ✅ M 芯片 ARM 原生版 Brew（正确）：/opt/homebrew ❌ Intel 旧版 Brew（报错源头）：/usr/local/Homebrew
绝大多数出现该问题的用户，都是通过 Mac 迁移助手同步了旧 Intel 电脑的环境，导致系统残留了旧架构的 Homebrew。
三、解决方案一：Rosetta 模拟运行（临时应急，不推荐长期）
如果只是临时需要使用 brew 命令，不想重装环境，可以通过 Rosetta2 模拟 Intel 架构运行旧版 Brew，快速临时修复。
1. 安装 Rosetta2 兼容层
softwareupdate --install-rosetta --agree-to-license
2. 以 Intel 架构执行 Brew 命令
arch -x86_64 brew --version
方案优缺点
✅ 优点：无需重装，即时生效 ❌ 缺点：性能损耗大，后续更新、安装软件极易出现兼容报错，环境不稳定，仅适合临时救急。
四、解决方案二：彻底重装原生 ARM Brew（推荐，永久根治｜清华镜像官方方式）
清华的
install.git仓库不支持 curl 直接拉取脚本，必须先用 git clone 下载仓库，再本地执行uninstall.sh/install.sh。
步骤 1：卸载旧版 Intel Homebrew（清华镜像 git 方式）
# 克隆清华镜像的 homebrew/install 仓库
git clone --depth=1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git brew-install
# 执行卸载脚本，指定旧brew路径 /usr/local
/bin/bash brew-install/uninstall.sh --path /usr/local
# 清理临时目录（可选）
rm -rf brew-install
执行过程中按提示确认卸载，脚本自动清理 /usr/local 下 Homebrew、Cellar 等目录。
步骤 2：清理环境变量配置
打开终端配置文件（M 芯片默认 zsh）
open ~/.zshrc
删除文件中所有包含 /usr/local/bin/brew 的旧配置，典型无效配置如下：
eval "$(/usr/local/bin/brew shellenv)"
保存文件后，刷新终端环境：
source ~/.zshrc
步骤 3：安装 M 芯片原生 ARM 版 Homebrew（清华镜像 git 方式）
# 再次克隆install仓库
git clone --depth=1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git brew-install
# 安装，同时设置brew核心仓库为清华镜像
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
/bin/bash brew-install/install.sh
# 删除临时仓库目录
rm -rf brew-install
步骤 4：配置原生环境变量
安装完成后，终端会提示环境变量配置命令，复制执行（通用命令如下）：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc
步骤 5：永久配置 Homebrew 清华镜像【强烈建议】
# 替换 brew.git 远程地址
git -C "$(brew --repo)" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git
# 替换 homebrew-core
git -C "$(brew --repo)/Library/Taps/homebrew/homebrew-core" remote set-url origin https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git
# 设置bottles二进制包镜像，写入zsh配置
echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles' >> ~/.zshrc
echo 'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zshrc
source ~/.zshrc
五、环境验证（确认修复成功）
执行以下命令，验证当前 Brew 环境为原生 ARM 版本：
1. 查看 Brew 安装路径
brew --prefix
✅ 正常输出：/opt/homebrew
2. 查看终端架构
arch
✅ 正常输出：arm64
3. 检测环境完整性
brew doctor
无报错、提示系统正常即代表修复完成。
六、进阶：双版本 Brew 共存（极少场景使用）
部分开发场景需要同时兼容新旧软件，可保留 Intel + ARM 双版本 Brew，普通用户不建议使用，极易出现 PATH 冲突。
- ARM 原生版（默认）：直接执行
brew - Intel 兼容版：必须加前缀执行
arch -x86_64 brew
Intel 版本 brew 同样可以配置清华镜像。
七、恢复官方源备用命令（放在文末）
如果后续需要切回官方源：
git -C "$(brew --repo)" remote set-url origin https://github.com/Homebrew/brew.git
git -C "$(brew --repo)/Library/Taps/homebrew/homebrew-core" remote set-url origin https://github.com/Homebrew/homebrew-core.git
# 删除镜像环境变量
sed -i '' '/HOMEBREW_BOTTLE_DOMAIN/d' ~/.zshrc
sed -i '' '/HOMEBREW_API_DOMAIN/d' ~/.zshrc
source ~/.zshrc
八、问题总结与避坑指南
- 报错核心：M 芯片 Mac 使用了 Intel x86_64 架构的旧版 Homebrew，架构不兼容
- 清华镜像注意点：
mirrors.tuna.tsinghua.edu.cn/git/homebrew/下是 git 仓库，不能直接 curl 拉取 sh 脚本，必须 git clone - 最优方案：卸载旧版，安装
/opt/homebrew原生 ARM 版本，并配置清华镜像加速 - 禁忌操作：不要强行保留双环境、不要忽略环境变量残留，会持续引发各类 brew 报错
- 迁移避坑：新机迁移建议不要同步旧电脑的开发环境配置，避免残留兼容问题
