macOS安装更新CocoaPods时ffi扩展编译失败如何解决

编译失败的核心原因有两点：

• macOS系统自带的Ruby 2.6环境随系统/Xcode命令行工具更新后，开发头文件ruby/config.h路径匹配异常，导致ffi gem的原生扩展无法完成编译
• 直接使用sudo往系统Ruby目录安装全局gem，容易触发系统权限保护、路径不匹配问题，本身就不是推荐的用法

1. 修复Xcode命令行工具环境 #

先移除损坏的命令行工具残留：

sudo rm -rf /Library/Developer/CommandLineTools

触发命令行工具重装：

xcode-select --install

按照弹窗提示完成安装后，校正开发工具路径：

• 已安装完整版Xcode的设备执行：

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

• 仅安装命令行工具未装完整版Xcode的设备执行：

sudo xcode-select -s /Library/Developer/CommandLineTools

2. 替换系统自带Ruby环境 #

系统自带Ruby是给系统内部程序用的，版本老旧、权限限制多，长期使用建议替换为用户态维护的Ruby版本，通过Homebrew安装即可：

brew install ruby

安装完成后将新的Ruby路径加入shell环境变量，macOS默认使用zsh的话执行：

• Intel芯片设备：

echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

• Apple Silicon（M1/M2/M3系列）芯片设备：

echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

执行ruby -v确认输出的版本号不是2.6.x，即代表环境切换成功。

3. 重新安装CocoaPods #

环境切换完成后不需要加sudo，直接执行安装命令：

gem install cocoapods

如果仍提示ffi相关的旧报错，先执行修复命令再重新安装：

gem pristine ffi --version 1.15.4

安装完成后执行pod --version能正常输出版本号即修复完成。

如果暂时不想调整Ruby环境，可以手动补全系统Ruby缺失的头文件软链：

1. 进入系统Ruby头文件目录：

cd /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/include/ruby-2.6.0

2. 查看当前目录下universal-darwin开头的文件夹实际名称（不同系统版本后缀数字不同，比如21/22/23），执行对应软链命令，把文件夹名替换成你实际查到的名称：

sudo ln -sf universal-darwin21/ruby/config.h ruby/config.h

3. 软链创建完成后，重新执行sudo gem install cocoapods即可完成安装。

注意：该方案为临时修复，后续macOS系统或Xcode更新后大概率会再次出现同类问题，长期使用仍建议切换到独立维护的Ruby环境。

内容的提问来源于stack exchange，提问作者Russell Harrower