iOS 环境搭建教程

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

---

1. 安装 Homebrew

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

安装 Homebrew

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

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

验证安装

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

brew --version

输出示例：

Homebrew 4.4.11

---

2. 安装 Node 和 NPM

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

使用 Homebrew 安装 Node.js

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

brew install node

验证安装

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

node --version

输出示例：

v23.4.0

npm --version

输出示例：

10.9.2

---

3. 安装 Watchman 工具

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

安装 Watchman

使用 Homebrew 安装 Watchman：

brew install watchman

验证安装

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

watchman --version

输出示例：

2024.12.02.00

---

4. 安装 Xcode

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

安装步骤

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

---

5. 安装 Ruby 和 rbenv

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

安装 rbenv 和 Ruby

使用 Homebrew 安装 rbenv 和 ruby-build：

brew install rbenv ruby-build

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

rbenv init

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

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

安装指定版本的 Ruby

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

rbenv install 3.36
rbenv global 3.36

---

6. 安装 CocoaPods

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

安装 CocoaPods

使用 Gem 安装 CocoaPods：

sudo gem install cocoapods

验证安装

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

pod --version

输出示例：

1.16.2

---

7. 新建一个 React Native 项目

步骤 1：创建新项目

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

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

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

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

步骤 2：启动 iOS 模拟器

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

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’.

---

错误分析

1. Unable to open base configuration reference file
   这是因为 CocoaPods 没有生成或正确配置 .xcconfig 文件。

2. Unable to load contents of file list
   这是因为 Pods 相关的文件列表（如 input-files.xcfilelist 和 output-files.xcfilelist）不存在或路径不正确。

3. xcodebuild exited with error code '65'
   这是 iOS 项目配置或依赖问题的通用错误，特别是在缺少 Pods 安装的情况下。

---

解决方案

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

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

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

• 检查版本：

  pod --version
  

• 如果没有安装或版本低于 1.11.3，请重新安装或更新：

  sudo gem install cocoapods
  

2. 重新安装 Pods 依赖

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

• 进入 ios 目录：

  cd ios
  

• 删除旧的 Pods 目录和锁文件：

  rm -rf Pods Podfile.lock
  

• 重新安装 Pods 依赖：

  pod install
  

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

• 运行项目：

  
  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

解决方案

Delete node_modules folder and run npm install solved the issue