引言
在使用 npx react-native init 命令创建新的 react native 项目时，开发者可能会遇到 gem::ext::builderror 错误，尤其是在安装 bundler 阶段。此错误通常与 ruby 的 ffi gem 有关，表明其原生扩展未能成功编译。ffi（foreign function interface）是一个用于允许 ruby 代码调用 c 库的 gem，而 cocoapods 等依赖项在 react native 项目初始化过程中会间接依赖它。当系统缺少 libffi 库的开发头文件或这些头文件不在标准搜索路径中时，就会出现构建失败。
问题分析
当执行 npx react-native init AwesomeProject 命令时，React Native CLI 会进行多项设置，其中包括为 iOS 项目安装 CocoaPods 依赖。CocoaPods 本身是一个 Ruby gem，它依赖于其他 gem，其中 ffi 是一个关键的底层依赖。ffi gem 在安装时需要编译一个原生扩展，这要求系统上存在 libffi 库及其开发头文件（如 ffi.h 和 ffitarget.h）。
错误日志中常见的提示包括：
- error Gem::Ext::BuildError: ERROR: Failed to build gem native extension.
- checking for ffi_prep_closure_loc() in -lffi... no
- make failed, exit code 2
- Error: Looks like your iOS environment is not properly set.
这些信息共同指向一个核心问题：Ruby 的 ffi gem 无法找到或链接到 libffi 库的必要组件，导致其原生扩展编译失败，进而阻碍了 CocoaPods 乃至整个 React Native 项目的初始化进程。路径中包含空格（例如 Dropbox/My Mac (Muhammad’s MacBook Pro)）也可能在某些 make 工具链中引发额外的解析问题，但根本原因仍是 libffi 依赖。
解决方案
解决此问题的核心在于确保系统上正确安装了 libffi 库，并且其开发头文件对 Ruby gem 的构建过程是可访问的。在 macOS 系统上，Homebrew 是管理这些库的推荐工具。
步骤一：安装或更新 libffi
首先，使用 Homebrew 安装 libffi 库。如果已经安装，Homebrew 会提示已安装或尝试更新。
brew install libffi
此命令会下载并安装 libffi 库及其头文件到 Homebrew 的默认路径（通常是 /opt/homebrew/Cellar/libffi/ 或 /usr/local/Cellar/libffi/）。
步骤二：创建头文件符号链接
ffi gem 在编译时可能期望 libffi 的头文件位于标准的系统路径，例如 /usr/local/include/。尽管 Homebrew 将文件安装在其“Cellar”中，但这些路径可能不会自动被 Ruby gem 的构建系统识别。因此，我们需要手动创建符号链接，将 Homebrew 安装的 libffi 头文件链接到 /usr/local/include/。
ln -s $(brew --cellar libffi)/*/include/ffi.h /usr/local/include/ffi.h ln -s $(brew --cellar libffi)/*/include/ffitarget.h /usr/local/include/ffitarget.h
- $(brew --cellar libffi) 命令会输出 libffi 的 Homebrew 安装路径，例如 /opt/homebrew/Cellar/libffi。
- /*/include/ffi.h 会匹配该路径下所有版本子目录中的 include/ffi.h 文件。
- ln -s 命令用于创建符号链接。
注意： 如果 /usr/local/include/ 目录不存在，您可能需要先创建它：sudo mkdir -p /usr/local/include。如果目标路径中已存在同名文件，创建链接会失败，此时可能需要先删除旧文件（请谨慎操作，确保不会删除重要文件）。
步骤三：重新初始化 React Native 项目
完成上述步骤后，系统环境已为 ffi gem 的成功编译做好了准备。现在，您可以重新尝试初始化 React Native 项目。
npx react-native init AwesomeProject
如果之前的项目初始化失败并创建了部分文件，建议在重新尝试之前删除该项目目录，以避免潜在的冲突：
rm -rf AwesomeProject npx react-native init AwesomeProject
验证与注意事项
- 验证 libffi 安装： 您可以通过 brew list libffi 确认 libffi 是否已通过 Homebrew 安装。
- 验证符号链接： 使用 ls -l /usr/local/include/ffi.h 和 ls -l /usr/local/include/ffitarget.h 命令可以检查符号链接是否正确创建并指向了 Homebrew 的 libffi 路径。
- 权限问题： 如果在创建符号链接时遇到权限错误，请尝试使用 sudo 命令，例如 sudo ln -s ...。
- Ruby 版本管理： 如果您使用 rvm 或 rbenv 等 Ruby 版本管理工具，请确保您正在使用的 Ruby 环境是干净且配置正确的。此解决方案主要针对 libffi 依赖问题，与 Ruby 版本本身的关系较小，但一个健康的 Ruby 环境是前提。
- 系统路径中的空格： 虽然上述解决方案解决了 libffi 依赖问题，但如果您的项目路径中包含空格（如 ~/Dropbox/My Mac (Muhammad’s MacBook Pro)/Desktop/AwesomeProject），这在某些构建工具中仍然可能导致问题。在开发过程中，通常建议避免在项目路径中使用空格或特殊字符。
总结
Gem::Ext::BuildError 在 React Native 项目初始化过程中是一个常见的挑战，尤其是在 macOS 系统上，它通常源于 ffi gem 无法找到或链接到 libffi 库的开发头文件。通过利用 Homebrew 安装 libffi 并手动创建头文件的符号链接到标准系统路径，可以有效解决这一问题。遵循本教程的步骤，您将能够顺利初始化 React Native 项目，并专注于应用程序的开发。
