Unity集成Firebase打包iOS遇CocoaPods版本不符安装失败问题

核心问题定位 #

• 新版Firebase Analytics对CocoaPods最低版本要求为1.10.0，系统自带Ruby环境安装的旧版1.8.4不满足要求
• ffi原生扩展编译失败是Xcode命令行工具未正确关联、Big Sur下编译参数默认拦截隐式声明、架构参数不匹配三个原因共同导致，重装Xcode、直接重装CocoaPods没有命中问题点
• Homebrew源当前对Big Sur版本的CocoaPods包适配存在依赖冲突，是此前尝试方案无效的核心原因

逐步骤操作 #

1. 清理所有残留旧版本依赖
   打开终端依次执行以下命令，遇到多版本提示时直接选择「卸载全部版本」即可：

sudo gem uninstall cocoapods
sudo gem uninstall cocoapods-core
sudo gem uninstall cocoapods-downloader
sudo gem uninstall ffi

2. 修复Xcode编译环境

• 打开Xcode，进入Settings > Locations，在Command Line Tools下拉菜单中选中当前安装的正式版Xcode，不要留空、不要选Beta版本
• 回到终端执行以下命令，关联命令行工具路径、完成Xcode首次启动初始化（会自动安装缺失的系统头文件、同意许可协议）：

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

3. 编译安装ffi依赖（解决原生扩展编译失败问题）
   2014款MBP为x86_64架构，执行命令时需要指定架构和编译参数，跳过Big Sur下的默认编译拦截：

sudo arch -x86_64 gem install ffi -- --with-cflags="-Wno-error=implicit-function-declaration"

4. 安装兼容版本的CocoaPods
   不要安装过高版本的CocoaPods，1.11.3是Big Sur环境下兼容性最好、同时满足Firebase版本要求的稳定版，执行命令安装：

sudo arch -x86_64 gem install cocoapods -v 1.11.3

安装完成后执行pod --version验证，终端输出1.11.3即为安装成功。

5. 清理Unity工程残留缓存重新构建

• 找到Unity导出的iOS工程目录，删除目录下的Pods文件夹、Podfile文件、Podfile.lock文件
• 回到Unity重新执行Build操作，Unity会自动触发新的CocoaPods依赖安装流程，不会再出现版本不满足、framework添加失败的报错。

避坑说明 #

• 不要在该系统版本下通过Homebrew安装CocoaPods，当前Homebrew默认的CocoaPods包依赖更高版本的macOS系统组件，会出现新的依赖冲突
• 执行sudo命令时终端不会显示输入的密码字符，属于正常机制，正常输入密码后回车即可
• 不要尝试安装1.12.0及以上版本的CocoaPods，高版本对Big Sur的Ruby环境存在兼容问题，会出现新的运行报错

内容的提问来源于stack exchange，提问作者Adrián Varga