iOS 环境搭建教程

本文档将详细介绍如何在 macOS 上搭建 iOS 开发环境，以便进行 React Native 开发。（为了保证环境一致全部在网络通畅的情况下运行）

1. 安装 Homebrew

Homebrew 是 macOS 的包管理工具，我们将通过它来安装开发所需的工具。

安装 Homebrew

打开终端并输入以下命令来安装 Homebrew：

bash 复制代码

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

验证安装

安装完成后，可以运行以下命令来检查 Homebrew 是否安装成功：

bash 复制代码

brew --version

输出示例：

复制代码

Homebrew 4.4.11

2. 安装 Node 和 NPM

Node.js 是 React Native 开发的基础，NPM 是 Node.js 的包管理工具。

使用 Homebrew 安装 Node.js

运行以下命令来安装 Node.js：

bash 复制代码

brew install node

验证安装

安装完成后，使用以下命令检查 Node 和 NPM 是否成功安装：

bash 复制代码

node --version

输出示例：

复制代码

v23.4.0

bash 复制代码

npm --version

输出示例：

复制代码

10.9.2

3. 安装 Watchman 工具

Watchman 是一个监控文件系统的工具，可以加速 React Native 项目的构建过程。

安装 Watchman

使用 Homebrew 安装 Watchman：

bash 复制代码

brew install watchman

验证安装

安装完成后，运行以下命令检查是否成功安装：

bash 复制代码

watchman --version

输出示例：

复制代码

2024.12.02.00

4. 安装 Xcode

Xcode 是苹果官方的开发环境，包含了构建 iOS 应用所需的工具链。最简单的安装方式是通过 Mac App Store。

安装步骤

打开 Mac App Store。
搜索 Xcode 并点击安装。
安装完成后，Xcode 会自动安装 iOS 模拟器以及其他开发工具。

5. 安装 Ruby 和 rbenv

React Native 需要使用 Ruby 环境来管理 CocoaPods，CocoaPods 是一个用于管理 iOS 项目依赖的工具。

安装 rbenv 和 Ruby

使用 Homebrew 安装 rbenv 和 ruby-build：

bash 复制代码

brew install rbenv ruby-build

安装完成后，运行以下命令进行初始化：

bash 复制代码

rbenv init

根据终端提示，执行以下命令将 rbenv init 添加到 .zshrc 文件中：

bash 复制代码

echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc

安装指定版本的 Ruby

使用以下命令安装 Ruby 版本 3.36：

bash 复制代码

rbenv install 3.36
rbenv global 3.36

6. 安装 CocoaPods

CocoaPods 用于管理 React Native 项目的 iOS 依赖库。

安装 CocoaPods

使用 Gem 安装 CocoaPods：

bash 复制代码

sudo gem install cocoapods

验证安装

安装完成后，使用以下命令验证是否成功安装：

bash 复制代码

pod --version

输出示例：

复制代码

1.16.2

7. 新建一个 React Native 项目

步骤 1：创建新项目

如果您之前全局安装了 react-native-cli，请先卸载它，以避免潜在的问题：

bash 复制代码

npm uninstall -g react-native-cli @react-native-community/cli

接着使用 React Native Community CLI 创建一个新的 React Native 项目：

bash 复制代码

npx @react-native-community/cli@latest init AwesomeProject

步骤 2：启动 iOS 模拟器

在项目目录下，运行以下命令启动 iOS 模拟器：

bash 复制代码

npm run ios

如果遇到问题，请按照终端的提示进行修复。

其他可能遇到的问题

在使用 iOS 模拟器时，可能会遇到以下问题：

模拟器启动失败：error Unable to open base configuration reference file '/Users/caredamon/project/github/workspaces-react/AwesomeProject/ios/Pods/Target Support Files/Pods-AwesomeProject/Pods-AwesomeProject.debug.xcconfig'. error Unable to load contents of file list: '/Target Support Files/Pods-AwesomeProject/Pods-AwesomeProject-resources-Debug-input-files.xcfilelist' error Failed to build ios project. "xcodebuild" exited with error code '65'.

错误分析

Unable to open base configuration reference file

这是因为 CocoaPods 没有生成或正确配置 .xcconfig 文件。
Unable to load contents of file list

这是因为 Pods 相关的文件列表（如 input-files.xcfilelist 和 output-files.xcfilelist）不存在或路径不正确。
xcodebuild exited with error code '65'

这是 iOS 项目配置或依赖问题的通用错误，特别是在缺少 Pods 安装的情况下。

解决方案

按照以下步骤逐一检查和解决问题：

1. 检查 CocoaPods 是否已正确安装

如果你的 macOS 没有安装 CocoaPods 或版本过旧，可能会导致依赖无法解析。

检查版本 ：
bash 复制代码
```
pod --version
```
如果没有安装或版本低于 1.11.3，请重新安装或更新 ：
bash 复制代码
```
sudo gem install cocoapods
```

2. 重新安装 Pods 依赖

进入项目的 ios 目录，删除旧的 Pods 目录和锁文件，重新安装 Pods 依赖：

进入 ios 目录 ：
bash 复制代码
```
cd ios
```
删除旧的 Pods 目录和锁文件 ：
bash 复制代码
```
rm -rf Pods Podfile.lock
```
重新安装 Pods 依赖 ：
bash 复制代码
```
pod install
```

确保 Podfile.lock 和 Pods 文件夹被成功生成。

运行项目 ：
bash 复制代码
```
npx react-native run-ios
```

在使用 iOS 模拟器时，可能会遇到以下问题

node:events:491 throw er; // Unhandled 'error' event ^ Error: EMFILE: too many open files, watch at FSWatcher._handle.onchange (node:internal/fs/watchers:207:21) Emitted 'error' event on NodeWatcher instance at: at FSWatcher._checkedEmitError (/Users/caredamon/project/github/workspaces-react/baseProjectRN/node_modules/metro-file-map/src/watchers/NodeWatcher.js:82:12) at FSWatcher.emit (node:events:513:28) at FSWatcher._handle.onchange (node:internal/fs/watchers:213:12) { errno: -24, syscall: 'watch', code: 'EMFILE', filename: null } Node.js v23.4.0

解决方案

bash 复制代码

Delete node_modules folder and run npm install solved the issue