React Native项目初始化失败：Bundler安装触发Gem::Ext::BuildError

核心诱因 #

ffi gem需要本地编译环境支持，iOS开发依赖的Xcode命令行工具不完整、系统编译组件缺失，或是Ruby版本不兼容，是引发该错误的主要原因。

分步解决方案 #

1. 补全Xcode命令行工具并接受许可 #

执行命令安装/更新Xcode命令行工具：

xcode-select --install

安装完成后，强制接受Xcode许可协议：

sudo xcodebuild -license accept

2. 安装系统编译依赖（macOS） #

• Intel芯片Mac：

brew install libffi

• Apple Silicon芯片Mac：
  先安装依赖，再配置环境变量：

brew install libffi
export LDFLAGS="-L/opt/homebrew/opt/libffi/lib"
export CPPFLAGS="-I/opt/homebrew/opt/libffi/include"
export PKG_CONFIG_PATH="/opt/homebrew/opt/libffi/lib/pkgconfig"

可将上述三个环境变量添加到~/.zshrc或~/.bash_profile，避免每次重启终端重复配置。

3. 调整Ruby版本并重新安装ffi #

ffi 1.15.5对Ruby版本有兼容要求，建议用rbenv管理版本：

# 安装rbenv（未安装时执行）
brew install rbenv
rbenv init
# 重启终端后安装Ruby 2.7.6
rbenv install 2.7.6
# 设置当前项目使用该版本
rbenv local 2.7.6

然后带编译参数重新安装ffi：

gem install ffi -v 1.15.5 -- --with-cflags="-Wno-error=implicit-function-declaration"

添加--with-cflags参数可规避macOS新版本的编译警告触发错误。

4. 重新配置项目Bundler #

进入项目目录，执行：

bundle install

若仍报错，删除锁文件后重试：

rm Gemfile.lock
bundle install

5. 验证iOS环境完整性 #

运行React Native官方环境检查工具，补全缺失依赖：

npx @react-native-community/cli doctor

内容的提问来源于stack exchange，提问作者Ismail Masood Orakzai