HR's Blog

Swimming 🏊 in the sea🌊of code!

0%

Mac M1安装brew问题汇总

Posted on Edited on In Disqus:
Mac M1/M2/M3/M4 (Apple Silicon) 安装与使用 Homebrew 完整踩坑指南：全面解决 command not found、国内 443 超时、Formula 找不到、更新报错及 CocoaPods ffi Bus Error，附国内极速镜像一键脚本与原生 arm64 架构最佳实践。

Mac M1/M2/M3/M4 (Apple Silicon) 安装与使用 Homebrew 常见踩坑与报错解决方案全汇总

在搭载 Apple Silicon（M1、M2、M3、M4 及 Pro/Max/Ultra 芯片）的 Mac 电脑上，由于底层 CPU 架构从传统的 x86_64 全面切换至 arm64，Homebrew 的安装路径、编译逻辑以及依赖生态发生了根本性变化。

很多同学在换上新 Mac 搭建开发环境时，常常会遇到 “官网脚本连不上”、“安装后找不到 brew 命令”、“软件源找不到常见包”、“CocoaPods 运行报 Ruby Bus Error” 等一系列棘手问题。

本文将这些高频报错与踩坑点进行系统性归纳，不仅提供 开箱即用的一键修复命令，还会从底层架构原理上剖析为什么会报错，帮助大家彻底扫清 Apple Silicon 终端开发障碍。

📌 30 秒快速排错索引 (TL;DR)

遇到问题不用通读全文，根据你的报错现象直接跳转对应方案：

序号 常见报错现象 / 需求 根因分类 快速跳转
01 curl: (7) Failed to connect to raw.githubusercontent.com 国内 GitHub DNS 污染 / 连接超时 👉 方案一：官方脚本与国内镜像一键安装
02 zsh: command not found: brew M 芯片默认路径改变，环境变量未加载 👉 方案二：环境变量正确配置姿势
03 Error: No similarly named formulae found / fatal: Could not resolve HEAD Git 浅克隆损坏 / 默认源同步中断 👉 方案三：重置与配置国内镜像加速
04 ffi/library.rb: [BUG] Bus Error / CocoaPods 崩溃 旧版 Ruby ffi 架构不兼容与 Rosetta 混淆 👉 方案四：CocoaPods 原生 arm64 最佳实践
05 环境混乱，想要重头再来 残留缓存冲突与多架构混乱 👉 方案五：彻底卸载与干净重装指南

🍎 底层原理：Apple Silicon 与 Intel 架构差异

在开始解决具体问题前，必须了解 Homebrew 在 Apple Silicon 上的核心设计差异：

  • **Intel 架构 Mac (x86_64)**：默认安装路径为 /usr/local。该路径默认就在系统的 $PATH 搜索列表中，因此装完即可直接识别 brew 命令。
  • **Apple Silicon Mac (arm64)**：默认安装路径被官方改为 /opt/homebrew。
    • 为什么改路径？ 为了与 macOS 的 Rosetta 2 转译环境共存！如果继续装在 /usr/local，原生 arm64 编译的二进制文件与 x86_64 转译文件会发生严重冲突。
    • 产生的影响：/opt/homebrew/bin 默认不在 macOS 的原始 $PATH 中，因此首次安装完成后必须显式将环境变量注入 Shell 配置，否则终端必然报错 command not found: brew。
1
2
Intel Mac:        /usr/local/bin/brew       (已在默认 PATH)
Apple Silicon:    /opt/homebrew/bin/brew    (需手动添加到 PATH)

1. Homebrew 安装与国内极速镜像

官方安装地址

官方给出的标准安装命令如下：

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

🔗 Homebrew 官方网站

踩坑一：国内网络 443 超时与连接失败

在没有系统级国际代理的环境下，执行上述脚本通常会遇到如下报错：

1
curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused

💡 极速解决方案：国内一键全自动安装脚本

推荐使用国内开发者广泛维护、内置清华/中科大/阿里云镜像的自动化脚本，不仅免去 GitHub 网络困扰，还会自动提示配置好环境变量：

1
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

运行过程：

  1. 终端会弹出提示选择源：推荐输入 1 选择 中科大源 或 2 选择 清华大学源；
  2. 脚本会自动检测系统是否安装了 Xcode Command Line Tools，若未安装会自动触发安装；
  3. 全程自动跑完并提示配置环境变量，省时省力。

2. 安装后无法找到 brew 命令 (command not found)

踩坑二：安装成功但提示找不到命令

1
zsh: command not found: brew

💡 解决方案：将 /opt/homebrew 注入环境变量

正如前文所述，Apple Silicon 的默认路径是 /opt/homebrew。

请直接在终端中复制并执行以下两条命令（自动写入当前用户的 .zprofile 并立即生效）：

1
2
3
4
5
# 1. 将环境变量写入登录 shell 配置文件
(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zprofile

# 2. 让当前终端窗口立即生效
eval "$(/opt/homebrew/bin/brew shellenv)"

执行后验证是否生效：

1
2
3
4
5
which brew
# 正确输出应为：/opt/homebrew/bin/brew

brew --version
# 输出当前已安装的 Homebrew 版本号

小贴士：如果你使用的是 Bash 终端而非 macOS 默认的 Zsh，请将上面命令中的 ~/.zprofile 替换为 ~/.bash_profile。

3. brew 安装源损坏与软件包找不到 (Formula not found)

踩坑三：常见常用包都无法搜索或安装

在使用 brew install wget、ca-certificates 等基础工具时，抛出如下错误：

1
2
3
4
5
6
7
8
9
10
Warning: No available formula with the name "ca-certificates".
==> Searching for similarly named formulae...
Error: No similarly named formulae found.
==> Searching taps on GitHub...
Running `brew update --preinstall`...
Error: No formulae found in taps.
fatal: Could not resolve HEAD to a revision
Warning: No available formula with the name "wget".
==> Searching for similarly named formulae...
Error: No similarly named formulae found.

产生根因

  1. 安装过程中 git clone 中途断连，导致本地 tap 仓库处于残缺或 fatal: Could not resolve HEAD 状态；
  2. Homebrew 4.x 默认采用了 API 检索模式（HOMEBREW_INSTALL_FROM_API=1），国内网络访问 GitHub 静态 API 出现阻断。

💡 解决方案：重置并切换国内 API 镜像源

步骤 1：重置仓库并强制恢复

1
2
# 重置 Homebrew 核心仓库至最新状态
brew update-reset

步骤 2：配置国内 API 与 Bottle 镜像加速

将以下配置写入 ~/.zprofile，实现全量走国内中科大 / 清华源镜像加速：

1
2
3
4
5
6
7
8
9
10
11
cat << 'EOF' >> ~/.zprofile

# Homebrew 国内镜像加速 (中科大源)
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
EOF

# 立即刷新当前终端
source ~/.zprofile

步骤 3：再次尝试安装

1
2
brew update
brew install wget

此时即可飞速下载并完成安装。

4. pod install 报错 Ruby ffi Bus Error 与架构冲突

踩坑四：iOS 开发者使用 CocoaPods 发生崩溃

在 M1/M2/M3 电脑上执行 pod install 或 gem install 时，经常抛出 Ruby 底层内存总线错误：

1
2
3
4
5
6
Update all pods
Updating local specs repositories
/Library/Ruby/Gems/2.6.0/gems/ffi-1.15.5/lib/ffi/library.rb:275: [BUG] Bus Error at 0x0000000105158000
ruby 2.6.8p205 (2021-07-07 revision 67951) [universal.arm64e-darwin21]
...
Abort trap: 6

产生根因

这是早期 macOS 系统自带的老旧 Ruby 2.6（以及系统预装的 ffi 动态链接库）在 arm64 指令集下的兼容性缺陷。

💡 终极推荐解法：通过 Homebrew 原生安装 CocoaPods（无痛推荐）

不要再折腾系统废弃的 System Ruby！现代 macOS 最稳妥、最高效的做法是直接通过 Homebrew 安装独立且原生支持 arm64 的 CocoaPods：

1
2
# 通过 Homebrew 直接安装包含完整 arm64 独立环境的 CocoaPods
brew install cocoapods

为什么推荐这个方案？

  • 独立沙箱，完全不需要 sudo；
  • 100% 运行在 Apple Silicon 原生 arm64 模式下，速度比转译快 3 倍以上；
  • 彻底告别系统的 Ruby 版本冲突与权限地狱。

备用传统方案：Rosetta 2 x86_64 转译兼容模式

如果你因为团队老项目特殊插件必须依赖系统的 gem，可以使用 Rosetta 强制以 x86 模式运行：

1
2
3
4
5
6
7
8
# 1. 安装 Rosetta 2（若尚未安装）
softwareupdate --install-rosetta --agree-to-license

# 2. 强制使用 x86_64 架构重新编译安装 ffi
sudo arch -x86_64 gem install ffi

# 3. 在工程目录下以 x86_64 架构执行 pod install
arch -x86_64 pod install

⚠️ 注意：使用 arch -x86_64 pod install 会导致某些带二进制 framework 的 pod 库只下载 x86_64 切片，后续在 Xcode 的 Apple Silicon 模拟器（arm64）上运行时可能会引发架构不匹配报错，因此**强烈建议优先使用原生 brew install cocoapods**。

5. 彻底卸载与重置 Homebrew

如果你的本地环境已经被各种不同版本的软链接、权限报错或 Rosetta 混乱搞崩，最彻底的解决办法是“一键干净卸载并重新安装”。

官方完整卸载脚本

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

国内快速卸载脚本（无需科学上网）

1
/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/HomebrewUninstall.sh)"

卸载完成后，手动检查清理残留目录：

1
sudo rm -rf /opt/homebrew

清理干净后，重新参照本文 第 1 节与第 2 节 进行安装配置，5 分钟即可拥有一套清爽高效的原生 Homebrew 开发环境！

6. 常用体检与诊断命令

日常遇到任何异常，可以使用 Homebrew 自带的体检命令进行诊断：

1
2
3
4
5
6
7
8
# 自动诊断当前环境中的潜在冲突与问题，并给出修复建议
brew doctor

# 查看 brew 配置详情（安装路径、源地址、系统版本）
brew config

# 清理过期的历史缓存与旧版本安装包，释放磁盘空间
brew cleanup -s

总结

Apple Silicon 带来的极致能效比给日常开发体验带来了巨大提升，但在环境迁移初期难免会遇到架构切换的“阵痛”。只要理清了 /opt/homebrew 路径隔离与 arm64 原生运行的机制，配合国内优质镜像源，无论是日常工具安装还是 iOS / Android / 后端开发环境搭建，都能如丝般顺滑。

如果你在安装过程中遇到了其他冷门报错，欢迎在文末留言交流！