MacBook 苹果芯片切换导致 Docker 安装失败的踩坑记录

问题背景

最近从 Intel 芯片的 MacBook 切换到了 M2 Pro 芯片的 MacBook，在使用 Homebrew 安装 Docker 时遇到了一系列报错，经过一番折腾才发现是 Homebrew 架构不匹配导致的问题。

错误现象

使用 brew install --cask docker 安装 Docker 时，出现以下错误：

Error: It seems there is already a Binary at '/usr/local/cli-plugins/docker-compose'.

以及后续的：

Error: It seems there is already a Binary at '/usr/local/bin/hub-tool'.

错误分析过程

初步排查思路

一开始以为是简单的文件冲突问题，尝试了以下常规解决方案：

1. 删除冲突文件

   sudo rm -f /usr/local/cli-plugins/docker-compose
   sudo rm -f /usr/local/bin/hub-tool
   

2. 完全清理 Docker 相关文件

   brew uninstall --cask docker --force
   sudo rm -rf /Applications/Docker.app
   sudo rm -rf ~/.docker
   # ... 其他清理命令
   

但这些方法都治标不治本，问题依然存在。

根本原因发现

问题的根本原因是：不同芯片架构的 Mac 上 Homebrew 的安装位置不同

• Intel Mac: Homebrew 安装在 /usr/local/
• Apple Silicon (M1/M2/M3): Homebrew 安装在 /opt/homebrew/

从 Intel Mac 迁移到 Apple Silicon Mac 时，如果直接迁移了用户数据，旧的 Intel 版本 Homebrew 和新的 Apple Silicon 版本 Homebrew 会产生冲突。

正确的解决方案

1. 卸载旧版本 Homebrew

如果系统中存在 Intel 版本的 Homebrew，需要先卸载：

# 卸载 Intel 版本的 Homebrew（如果存在）
/usr/local/bin/brew uninstall --ignore-dependencies --force $(brew list --formula)
sudo rm -rf /usr/local/Homebrew
sudo rm -rf /usr/local/Caskroom
sudo rm -rf /usr/local/Cellar

2. 重新安装 Apple Silicon 版本的 Homebrew

# 安装适用于 Apple Silicon 的 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. 更新环境变量

确保 PATH 中包含正确的 Homebrew 路径：

# 添加到 ~/.zshrc 或 ~/.bash_profile
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

4. 验证安装

# 检查 Homebrew 版本和位置
brew --version
which brew  # 应该显示 /opt/homebrew/bin/brew

5. 重新安装 Docker

# 现在可以正常安装 Docker 了
brew install --cask docker

# 如果使用 Colima，也重新安装
brew install colima

验证结果

安装完成后验证：

docker --version
colima --version

# 启动 Colima（轻量级容器运行时）
colima start

# 测试 Docker
docker run hello-world

经验总结

关键点

1. 芯片架构切换时要重装 Homebrew：不同架构的 Mac 使用不同路径的 Homebrew
2. 不要简单地删除冲突文件：治标不治本，根本问题是架构不匹配
3. 检查环境变量：确保 PATH 指向正确的 Homebrew 位置

预防措施

• 在芯片切换后，第一时间检查并重装 Homebrew
• 建立新机器时，不要盲目迁移所有配置文件
• 定期检查 which brew 确保使用正确版本

相关资源

• Colima Issue #702 - rfay 的回复提供了关键解决思路
• Homebrew 官方安装指南

总结

这次踩坑让我深刻理解了 Mac 不同芯片架构对开发环境的影响。看似简单的 Docker 安装失败，实际上反映的是更深层的系统架构问题。遇到类似问题时，要从根本原因入手分析，而不是仅仅解决表面现象。

希望这篇记录能帮助到遇到同样问题的开发者们！