CocoaPods 在 Apple Silicon (M1) 上的运行指南

问题描述

在 Apple Silicon (M1/M2) Mac 设备上运行 CocoaPods 时，开发者经常会遇到 Ruby 的 ffi 扩展兼容性问题。错误信息通常表现为：

LoadError - dlsym(0x7f8926035eb0, Init_ffi_c): symbol not found

这个问题的根源在于 Apple Silicon 芯片采用了 ARM64 架构，而系统自带的 Ruby 环境及其 gem 扩展是为 x86_64 架构编译的，导致兼容性问题。

解决方案概览

针对 Apple Silicon 芯片，有以下几种解决方案，推荐程度从高到低排列：

1. 使用 Homebrew 安装 CocoaPods（推荐 ✅）
2. 安装 ARM64 原生 Ruby 环境
3. 使用 Rosetta 兼容模式（临时方案）

解决方案详情

方案一：使用 Homebrew 安装 CocoaPods（推荐）

这是最简单且最稳定的解决方案，无需处理 Ruby 环境兼容性问题。

# 卸载已存在的 CocoaPods gem
sudo gem uninstall cocoapods

# 使用 Homebrew 安装 CocoaPods
brew install cocoapods

# 验证安装
pod --version

TIP

确保你的 Homebrew 已正确安装并配置为 Apple Silicon 原生版本（安装在 /opt/homebrew 目录下）。

方案二：安装 ARM64 原生 Ruby 环境

如果你需要保持 gem 安装方式，可以安装专为 ARM64 架构编译的 Ruby。

Homebrew

# 安装 Ruby
brew install ruby

# 将 Ruby 添加到 PATH
echo 'export PATH="/opt/homebrew/opt/ruby/bin:/opt/homebrew/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 安装 CocoaPods
sudo gem install cocoapods

rbenv

# 安装 rbenv
brew install rbenv

# 初始化 rbenv
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

# 安装 Ruby
rbenv install 3.1.4
rbenv global 3.1.4

# 安装 CocoaPods
gem install cocoapods

方案三：使用 Rosetta 兼容模式（临时方案）

如果需要临时解决问题或处理特定依赖兼容性，可以使用 Rosetta 模式。

# 安装 ffi gem（x86_64 架构）
sudo arch -x86_64 gem install ffi

# 运行 pod 命令（x86_64 架构）
arch -x86_64 pod install

WARNING

这不是长久之计，可能会影响性能和未来兼容性。建议尽快迁移到原生解决方案。

配置终端使用 Rosetta

如果需要使用 Rosetta 模式，可按以下步骤配置：

1. 在「应用程序」中找到「终端」
2. 右键点击选择「显示简介」
3. 勾选「使用 Rosetta 打开」选项
4. 重新启动终端

验证安装

无论选择哪种方案，安装后都应验证环境是否正确配置：

# 检查 Ruby 架构
which ruby
ruby -v

# 检查 CocoaPods 架构
which pod
pod --version

# 检查 ffi gem 版本
gem info ethon

常见问题排查

1. Homebrew 未正确安装

确保 Homebrew 已正确安装到 Apple Silicon 原生位置：

# 检查 Homebrew 安装路径
which brew
# 应该返回: /opt/homebrew/bin/brew

# 如果不是，重新安装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 架构不匹配错误

如果遇到架构不匹配的错误，可尝试创建通用二进制：

# 创建通用二进制安装
sudo env ARCHFLAGS='-arch arm64 -arch arm64e -arch x86_64' gem install cocoapods

3. Xcode 路径问题

确保 Xcode 命令行工具已正确配置：

# 设置活跃的开发者目录
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

# 接受 Xcode 许可协议
sudo xcodebuild -license

最佳实践建议

1. 优先使用 Homebrew：这是最稳定且易于维护的解决方案
2. 保持环境更新：定期更新 Homebrew 和 CocoaPods
3. 避免混合使用安装方法：不要同时使用 gem 和 Homebrew 安装 CocoaPods
4. 项目级别配置：对于团队项目，考虑使用 .ruby-version 文件确保环境一致性

INFO

从 macOS 未来版本开始，系统可能不再预装 Ruby，建议尽早建立独立的环境管理方案。

总结

Apple Silicon Mac 上的 CocoaPods 兼容性问题主要源于架构差异。通过使用 Homebrew 安装 CocoaPods 或配置正确的 Ruby 环境，可以彻底解决这些问题。Rosetta 模式可作为临时解决方案，但不建议长期使用。

选择最适合你工作流程的方案，确保开发环境的稳定性和性能。