详解最新版 React Native搭建IOS环境过程

为什么要写这个文档，给新开发IOS APP的开发人员提供一个引导，并且能在搭建过程中遇到的问题提供解决方案和思路，以至于能快速搭建好开发环境。在搭建过程中，笔者遇到了很多坑，初次搭建IOS环境，并不顺利。

说明：我电脑使用的是 MacBook Pro 2018 款，系统版本是 macOS Monterey。本文是参考 React Native 0.71 版本的官方文档，搭建 iOS开发环境。在按照官方文档搭建的过程中，我遇到了较多的网络问题，搭建环境之前，需要科学上网。

安装Xcode

首先需要安装Xcode，可以通过App Store下载，也可以在苹果官网下载最新版本的Xcode，安装完成后，找到左上角的 Xcode 标识，点击 Preferences，找到 Locations 标签中的 Command Line Tools 一栏，选择对应的 Xcode。

选择完成后，会出现类似 /Applications/Xcode.app 之类的地址，你可以点进去，确定 Xcode 的目录地址是否正确。

安装Homebrew

如果你已经安装了Homebrew，请跳过此步骤。如果没有安装，打开终端并粘贴下面的命令进行安装：

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
复制代码

如果执行这个命令后，报错的内容是 unable to access github，提示访问不到 GitHub 地址。在后面还有非常多的类似网络报错，在这里，我就不再一一列举了。解决方案都是类似的，需科学上网，保证自己的网络畅通。

安装完成后，重启当前 Terminal，你可以运行如下命令，检查它是否安装成功。

$ brew --version
Homebrew 4.0.6
Homebrew/homebrew-core (git revision fbc2e62; last commit 2023-03-13)
复制代码

安装Node.js和NPM

Node 是 JavaScript 相关服务的运行环境，比如构建服务就是通过 Node 环境提供的。安装的 Node，会自带 NPM 包管理器，它将帮助我们管理相关依赖。

已安装可跳过该步骤，React Native需要Node.js环境，可以在官网下载最新版本的Node.js，也可以使用Homebrew进行安装：

brew install node
复制代码

安装完成后，你可以通过如下命令检查 Node 和 NPM 是否安装成功。

$ node --version
v16.19.1
$ npm --version
8.19.3
复制代码

安装Watchman

Watchman是由Facebook开发的文件监视器，在React Native中用于监听文件变化并自动执行相应的操作。可以使用Homebrew进行安装：

$ brew install watchman
复制代码

安装完成后，通过如下命令检查是否安装成功。

$ watchman --version
2023.03.13.00
复制代码

安装Ruby环境

Ruby 是一种面向对象的脚本语言，简单易用，功能强大，能跨平台和可移植性好等等，在 iOS 应用的依赖管理中会使用到它。Mac 电脑上默认集成了 Ruby，但却和 React Native 所依赖的 Ruby 版本有些不一致。因此，你需要通过 rbenv 对 Ruby 进行版本管理，就像使用n工具用于管理 Node 的版本一样。

系统自带的 Ruby 是 2.6.10 版本，而 React Native 0.71 所依赖的 Ruby 版本是 2.7.6。因此，我们需要使用 rbenv 将 Ruby 版本切换到 2.7.6。

首先，你可以运行如下命令查看当前的 Ruby 版本。

$ ruby --version
ruby 2.6.10p219 (2022-04-12 revision c9c2245c0a) [x86_64-darwin21]
复制代码

接着，你可以使用 Homebrew 安装 rbenv，安装命令如下：

$ brew install rbenv ruby-build 
复制代码

安装完成后，运行 init 命令。运行完成后，它会提示你需要在 .zshrc 文件中执行 rbenv init 命令，因此你需要根据提示，使用 echo 将 init 命令添加到 Terminal 启动前。以保障 Terminal 启动时，rbenv 会生效。相关命令如下：

$ rbenv init

# 每人的提示信息不一定相同，根据提示信息进行相关操作
$ echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
复制代码

命令执行完成后，重启 Terminal，安装并切换到 React Native 所依赖的 Ruby 版本。

$ rbenv install 2.7.6
$ rbenv global 2.7.6
复制代码

切换完成 Ruby 版本后，再次重启 Terminal，再次运行 ruby --version 命令，确定 Ruby 版本是否切换成功。

$ ruby --version
ruby 2.7.6p219 (2022-04-12 revision c9c2245c0a) [x86_64-darwin21]
复制代码

Gem 和 Bundler

Ruby 有两种常用包管理工具：Gem 和 Bundler。Ruby 的软件源使用的是亚马逊的云服务，国内网络环境下载时可能会出现各种不稳定和超时，所以如果您用自带的需要科学上网，这两种包管理工具都会用到，你可以将官方 ruby 源替换成国内清华源 （mirrors.tuna.tsinghua.edu.cn/rubygems/）。

# 添加镜像源并移除默认源
$ gem sources --add https://mirrors.tuna.tsinghua.edu.cn/rubygems/ --remove https://rubygems.org/
# 列出已有源
$ gem sources -l
# 镜像源只有一个
*** CURRENT SOURCES ***

https://mirrors.tuna.tsinghua.edu.cn/rubygems/
复制代码

切换 Bundler 镜像源的方法是通过设置 config 进行切换，命令如下：

$ bundle config mirror.https://rubygems.org https://mirrors.tuna.tsinghua.edu.cn/rubygems
复制代码

具体来说，它会在 Bundler 的全局配置中添加一个 mirror.rubygems.org 的参数，将其值设置为 mirrors.tuna.tsinghua.edu.cn/rubygems, 表示在下载和安装包时使用清华大学的镜像源地址。

安装CocoaPods

在前面提到过，Ruby 有两种常用包管理工具，Gem 和 Bundler。CocoaPods 是另一种包管理工具，它虽然是用 Ruby 编写的，但不是 Ruby 的包管理工具，而是 iOS 的包管理工具。

这里我们借助 Gem 来安装 CocoaPods：

$ sudo gem install cocoapods
复制代码

安装完成后，运行如下命令确定 CocoaPods 是否已经安装成功。

$ pod --version
1.12.0
复制代码

新建项目

这里我们借助 React Native 内置的命令行工具，来创建一个名为 “AwesomeProject” 的新项目。

$ npx react-native init AwesomeProject
复制代码

但是，在 Installing CocoaPods dependencies 这一步会出现错误，错误截图如下所示：

这是由于没有切换 CocoaPods 的镜像源导致的。解决方案是，切换到清华大学开源软件镜像站的镜像，切换方式如下：

$ cd ~/.cocoapods/repos 
$ pod repo remove master
$ git clone https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git master
复制代码

执行完上述命令后，进入 AwesomeProject/ios 目录，找到 Podfile 文件，在文件第一行添加：

source 'https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git'
复制代码

这时，再在 AwesomeProject/ios 目录下，运行 CocoaPods 安装命令即可。

$ bundle exec pod install --verbose
复制代码

但是，此时仍可能会遇到报错，报错内容如下：

报错信息curl: (92) HTTP/2 stream 0 was not closed cleanly: PROTOCOL_ERROR (err 1)，报错的内容是，访问地址 repo1.maven.org/maven2/com/…, 这个库下载极慢，解决方案：

$ git config --global http.version HTTP/1.1
复制代码

启动项目

检查开发环境

好了，经过上面的工作，这时候终于可以跑项目了。进入项目根目录，执行 npx react-native doctor 指令检查IOS开发环境是否都已满足：

Common
 ✓ Node.js
 ✓ npm
 ✓ Watchman - Used for watching changes in the filesystem when in development mode

Android
 ✓ JDK
 ✓ Android Studio - Required for building and installing your app on Android
 ✓ Android SDK - Required for building and installing your app on Android
 ✓ ANDROID_HOME

iOS
 ✓ Xcode - Required for building and installing your app on iOS
 ✓ CocoaPods - Required for installing iOS dependencies
 ● ios-deploy - Required for installing your app on a physical device with the CLI
 ✓ .xcode.env - File to customize Xcode environment
复制代码

如果不满足，可以根据上面的提示手动处理修复开发环境。

如果已满足，运行 npx react-native info 输出开发环境信息，再次确认

info Fetching system and libraries information...
System:
    OS: macOS 12.6.3
    CPU: (4) x64 Intel(R) Core(TM) i5-6267U CPU @ 2.90GHz
    Memory: 47.88 MB / 8.00 GB
    Shell: 3.2.57 - /bin/bash
  Binaries:
    Node: 16.19.1 - /usr/local/bin/node
    Yarn: 1.22.19 - /usr/local/bin/yarn
    npm: 8.19.3 - /usr/local/bin/npm
    Watchman: 2023.03.13.00 - /usr/local/bin/watchman
  Managers:
    CocoaPods: 1.12.0 - /Users/zhouqiyuan/.rvm/rubies/ruby-2.7.6/bin/pod
  SDKs:
    iOS SDK:
      Platforms: DriverKit 22.2, iOS 16.2, macOS 13.1, tvOS 16.1, watchOS 9.1
    Android SDK: Not Found
  IDEs:
    Android Studio: 3.4 AI-183.6156.11.34.5522156
    Xcode: 14.2/14C18 - /usr/bin/xcodebuild
  Languages:
    Java: 12.0.1 - /usr/bin/javac
  npmPackages:
    @react-native-community/cli: Not Found
    react: 18.2.0 => 18.2.0
    react-native: 0.71.3 => 0.71.3
    react-native-macos: Not Found
  npmGlobalPackages:
    *react-native*: Not Found
复制代码

启动项目

项目根目录，运行如下命令来启动 iOS 项目：

$ npx react-native run-ios
复制代码

至此，我们已经成功搭建了 React Native 的开发环境，并成功运行了一个 React Native 项目。

总结

搭建开发环境是做新项目前期的痛点，过程会比较折腾，这一步劝退了很多想开发React Native的同学。在本文中，它主要包括八个步骤，涉及了 Xcode、Homebrew、Node、Watchman、Ruby、Gem、Bundler、CocoaPods 的安装、镜像配置、网络问题解决方案，以及如何新建项目和启动项目。

你在搭建 React Native 环境的过程中，遇到过哪些问题呢，能把你的解决方案和大家分享吗？