React Native初始化项目时Ruby Gems安装失败求助

问题背景 #

执行npx react-native init Project创建React Native新项目时，Ruby Gems安装失败，具体为构建json 2.6.3原生扩展时找不到'ruby/config.h'文件；此前尝试sudo gem install cocoapods时，ffi-1.16.1原生扩展构建失败，提示需先安装开发工具。

错误日志 #

项目初始化时的错误 #

✔ Downloading template
✔ Copying template
✔ Processing template
✖ Installing Ruby Gems
error Fetching gem metadata from https://rubygems.org/........
Resolving dependencies...
Fetching rexml 3.2.6
Installing rexml 3.2.6
Fetching CFPropertyList 3.0.6
Installing CFPropertyList 3.0.6
Fetching concurrent-ruby 1.2.2
Installing concurrent-ruby 1.2.2
Fetching i18n 1.14.1
Installing i18n 1.14.1
Fetching minitest 5.20.0
Installing minitest 5.20.0
Fetching tzinfo 2.0.6
Installing tzinfo 2.0.6
Fetching zeitwerk 2.6.11
Installing zeitwerk 2.6.11
Fetching activesupport 6.1.7.6
Installing activesupport 6.1.7.6
Fetching public_suffix 4.0.7
Installing public_suffix 4.0.7
Fetching addressable 2.8.5
Installing addressable 2.8.5
Fetching httpclient 2.8.3
Installing httpclient 2.8.3
Fetching json 2.6.3
Installing json 2.6.3 with native extensions
Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

current directory:
/Users/qrivnel/Desktop/Project/vendor/bundle/ruby/2.6.0/gems/json-2.6.3/ext/json/ext/generator
/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/ruby -I
/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0 -r
./siteconf20230924-69529-n3hcgy.rb extconf.rb
creating Makefile

current directory:
/Users/qrivnel/Desktop/Project/vendor/bundle/ruby/2.6.0/gems/json-2.6.3/ext/json/ext/generator
make "DESTDIR=" clean

current directory:
/Users/qrivnel/Desktop/Project/vendor/bundle/ruby/2.6.0/gems/json-2.6.3/ext/json/ext/generator
make "DESTDIR="
compiling generator.c
In file included from generator.c:1:
In file included from ./../fbuffer/fbuffer.h:5:
In file included from
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX14.0.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/include/ruby-2.6.0/ruby.h:33:
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX14.0.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/include/ruby-2.6.0/ruby/ruby.h:24:10:
fatal error: 'ruby/config.h' file not found
#include "ruby/config.h"
         ^~~~~~~~~~~~~~~
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX14.0.sdk/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/include/ruby-2.6.0/ruby/ruby.h:24:10:
note: did not find header 'config.h' in framework 'ruby' (loaded from
'/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks')
1 error generated.
make: *** [generator.o] Error 1

make failed, exit code 2

Gem files will remain installed in
/Users/qrivnel/Desktop/Project/vendor/bundle/ruby/2.6.0/gems/json-2.6.3 for
inspection.
Results logged to
/Users/qrivnel/Desktop/Project/vendor/bundle/ruby/2.6.0/extensions/universal-darwin-22/2.6.0/json-2.6.3/gem_make.out

An error occurred while installing json (2.6.3), and Bundler cannot continue.
Make sure that `gem install json -v '2.6.3' --source 'https://rubygems.org/'`
succeeds before bundling.

In Gemfile:
  cocoapods was resolved to 1.13.0, which depends on
    cocoapods-core was resolved to 1.13.0, which depends on
      algoliasearch was resolved to 1.27.5, which depends on
        json
✖ Installing Ruby Gems
error Looks like your iOS environment is not properly set. Please go to https://reactnative.dev/docs/environment-setup?os=macos&platform=android and follow the React Native CLI QuickStart guide for macOS and iOS.
info Run CLI with --verbose flag for more details.

手动安装CocoaPods时的错误 #

Password:
Building native extensions. This could take a while...
ERROR:  Error installing cocoapods:
ERROR: Failed to build gem native extension.

current directory: /Library/Ruby/Gems/2.6.0/gems/ffi-1.16.1/ext/ffi_c

/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/ruby -I /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0 -r ./siteconf20230924-70457-cgucg.rb extconf.rb
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of necessary
libraries and/or headers.  Check the mkmf.log file for more details.  You may
need configuration options.

Provided configuration options:
--with-opt-dir
--without-opt-dir
--with-opt-include
--without-opt-include=${opt-dir}/include
--with-opt-lib
--without-opt-lib=${opt-dir}/lib
--with-make-prog
--without-make-prog
--srcdir=.
--curdir
--ruby=/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/$(RUBY_BASE_NAME)
--with-ffi_c-dir
--without-ffi_c-dir
--with-ffi_c-include
--without-ffi_c-include=${ffi_c-dir}/include
--with-ffi_c-lib
--without-ffi_c-lib=${ffi_c-dir}/lib
--enable-debug
--disable-debug
--enable-system-libffi
--disable-system-libffi
--with-libffi-config
--without-libffi-config
--with-pkg-config
--without-pkg-config
/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/mkmf.rb:467:in `try_do': The compiler failed to generate an executable file. (RuntimeError) You have to install development tools first. from /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/mkmf.rb:546:in `block in try_link0'
from /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/tmpdir.rb:93:in `mktmpdir' from /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/mkmf.rb:543:in `try_link0'
from /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/mkmf.rb:570:in `try_link' from /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/mkmf.rb:672:in `try_ldflags'
from /System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/lib/ruby/2.6.0/mkmf.rb:1832:in `pkg_config' from extconf.rb:9:in `system_libffi_usable?'
from extconf.rb:46:in `'

To see why this extension failed to compile, please check the mkmf.log which can be found here:

/Library/Ruby/Gems/2.6.0/extensions/universal-darwin-22/2.6.0/ffi-1.16.1/mkmf.log

extconf failed, exit code 1

Gem files will remain installed in /Library/Ruby/Gems/2.6.0/gems/ffi-1.16.1 for inspection.
Results logged to /Library/Ruby/Gems/2.6.0/extensions/universal-darwin-22/2.6.0/ffi-1.16.1/gem_make.out

解决方案 #

1. 安装Xcode命令行工具 #

错误提示明确要求先安装开发工具，执行以下命令：

xcode-select --install

安装完成后重启终端，再尝试后续操作。

2. 修复Ruby头文件缺失问题 #

macOS自带Ruby可能缺少必要头文件，通过指定SDK路径解决：

export SDKROOT=$(xcrun --show-sdk-path)

执行后重新安装json gem：

gem install json -v '2.6.3'

3. 使用RVM管理Ruby版本（推荐） #

系统自带Ruby版本兼容性有限，用RVM安装独立Ruby版本：

• 安装RVM：

curl -sSL https://get.rvm.io | bash -s stable

• 加载RVM环境：

source ~/.rvm/scripts/rvm

• 安装适配CocoaPods 1.13.0的Ruby版本（如2.7.x）：

rvm install 2.7

• 设置默认Ruby版本：

rvm use 2.7 --default

• 重新安装CocoaPods：

gem install cocoapods -v 1.13.0

4. 利用已安装的Brew版CocoaPods跳过自动Gem安装 #

既然已通过brew安装CocoaPods 1.13.0，可修改初始化命令跳过自动Gem安装：

npx react-native init Project --skip-install

进入项目目录后手动安装依赖：

cd Project
npm install
# 手动配置iOS依赖
cd ios
pod install
cd ..

内容的提问来源于stack exchange，提问作者Erhan Karataş