React Native 如何在 Mac 上开发 iOS App？从 Node.js、CocoaPods 到 Xcode 编译

React Native 官方环境指南目前要求 Node.js 22.11.0 或更高版本；但项目自身的版本声明优先。React Native 如何在 Mac 上开发 iOS App？可以按项目要求准备 Node.js 和 JavaScript 依赖，配置 Xcode，再按需安装 CocoaPods 依赖，最后运行模拟器或用 Xcode 编译。 (React Native 官方环境指南)

这篇文章适合刚开始搭建 React Native iOS 环境的开发者，也适合已经能写 JavaScript、但卡在 CocoaPods 或原生依赖上的前端工程师。
如果团队需要在本地或远程 Mac 上运行 iOS 模拟器、编译原生工程，也可以按后面的步骤逐项核验。

先核验 React Native 如何在 Mac 上开发 iOS App 的环境

开发环境可以分成 JavaScript 工具链和 Apple 原生工具链：前者负责安装项目依赖、启动 Metro；后者由 macOS、Xcode、iOS SDK 和模拟器组成，负责编译 iOS 原生部分。React Native 官方指南列出 Node.js、Xcode 与 CocoaPods 等准备项；对于含原生代码的 iOS 构建，Mac 环境是关键前提。

开工前先判断项目类型。若项目使用封装原生构建的框架，日常开发可能不必在本机配置完整的 Xcode 工具链；若要直接编译 iOS 原生工程、安装原生模块或运行本地模拟器，就需要核对 Mac 上的 Xcode 与项目配置。

常见的阻塞并不只是“少装了一个工具”：

• Node.js 或包管理器与项目预期不符，安装依赖可能报错，Xcode 的构建脚本也可能找不到 Node.js。
• JavaScript 依赖安装成功，不代表 iOS 原生依赖已就绪；如果项目含 Podfile，仍需按项目说明处理 CocoaPods。
• Xcode 已安装，也不代表对应 iOS 模拟器运行时和命令行工具已可用；macOS、Xcode 与目标 SDK 的组合会影响能否构建。
• 模拟器构建与真机运行并非同一件事。真机或发布构建还可能受签名证书、团队配置和描述文件影响。(Apple 的 Xcode 设备分发说明)

再按项目声明安装 Node.js 与 JavaScript 依赖

不要先凭经验挑一个 Node.js 版本。先检查仓库根目录的 package.json 中是否声明了 engines 或 devEngines，并查看 .nvmrc、.node-version 等版本提示；包管理器也要从 packageManager 字段和仓库里的锁文件判断。npm 文档说明，engines 可用于声明 Node.js 版本要求，但是否强制执行还取决于 npm 配置。(npm 关于 package.json 的文档)

确认项目要求后，再检查本机版本及包管理器：

node -v
npm -v

如果仓库使用 npm 且已有 package-lock.json，可按团队约定使用 npm ci 做锁文件安装；它要求锁文件与 package.json 匹配。不要因为习惯而把 npm 命令换成其他包管理器，否则锁文件可能不再对应原有依赖树。npm 对 npm install 与锁文件的关系也有说明：锁文件满足版本范围时，会用于还原已锁定的依赖。(npm 安装命令文档)

这一步的结果应当是：项目依赖安装完成，版本约束没有冲突，仓库锁文件没有被意外改写。若项目脚本或贡献说明指定了不同命令，以仓库说明为准，不要把通用命令当作所有项目的标准答案。

配置 Xcode、命令行工具与模拟器运行时

安装 Xcode 后，首次启动时按界面提示完成组件安装与许可确认，再到设置中的 Locations 页面检查 Command Line Tools 指向的版本。可在终端运行 xcode-select -p 核实当前活动开发者目录；若它指向独立的 Command Line Tools 目录，而项目需要 Xcode 自带的 xcodebuild 或 iOS 模拟器工具，则应在 Xcode 设置中选好对应的 Xcode。Apple 说明，xcode-select --print-path 可用于查看当前活动目录，而 xcodebuild、simctl 等工具与 Xcode 工具链相关。(Apple 的 Xcode 命令行工具说明)

接着确认已安装项目需要的 iOS Simulator 运行时。React Native 指南指出，从 Xcode 14.0 起，可在设置的 Platforms 页面添加 iOS 模拟器组件；不同版本界面名称可能变化，因此以本机 Xcode 设置中的可用组件为准。若团队项目限定了 SDK 或部署目标，应检查工程设置和团队构建说明，不要为了“更新”而直接升级工具链。

若终端编译找不到 Node.js，而交互式终端中 node -v 正常，问题可能出在 Xcode 构建脚本获得的环境变量不同。React Native 官方说明，模板可用 .xcode.env 配置 NODE_BINARY；该配置方式从 React Native 0.69 起可用。核对该文件与构建脚本，比盲目重装 Node.js 更直接。(React Native 环境配置说明)

根据 iOS 工程安装 CocoaPods 依赖

先进入项目的 iOS 工程目录，确认是否存在 Podfile、Podfile.lock，以及项目说明是否要求 CocoaPods。Podfile 描述 Xcode 工程目标所需的 Pods 依赖；它不是每个 React Native 项目都必须采用的唯一依赖方式。若仓库没有该文件，先查项目文档，不要自行创建一个通用文件套用。(CocoaPods 关于 Podfile 的指南)

项目确认使用 CocoaPods 后，按仓库说明执行安装；常见操作是在含有 Podfile 的目录运行：

pod install

完成后查看命令输出是否有解析失败、下载错误或版本冲突，并检查 Podfile.lock 是否按预期更新。pod install 会依据锁文件保留已锁定的 Pod 版本；pod update 则用于主动更新指定依赖，或在不指定名称时尝试更新全部 Pods。两者用途不同，遇到问题时不要把 pod update 当成“安装失败后的万能修复”。(CocoaPods 关于 pod install 与 pod update 的说明)

若 CocoaPods 生成了 .xcworkspace，通常应打开这个工作区来构建，而不是只打开原始 .xcodeproj；工作区负责把应用工程与 Pods 工程关联起来。是否存在该文件及项目采用的集成方式，仍以仓库实际产物为准。

启动模拟器并验证 App，再进行 Xcode 编译

JavaScript 依赖、Xcode 与原生依赖都准备好后，先查看 package.json 的 scripts，确认项目定义了什么 iOS 启动脚本。React Native 模板常见入口是 npm run ios，但应使用仓库实际配置的包管理器与脚本；如果模拟器设备名称不匹配，可用 xcrun simctl list devices 检查 Xcode 当前识别的设备，再选择已安装的运行时。(React Native 在 iOS 模拟器中运行的说明)

要区分 Metro 与原生编译：Metro 提供 JavaScript 开发服务，Xcode 构建则需要编译 iOS 原生目标。某些启动脚本会串联多个环节，但看到 Metro 已启动，不能据此判定原生构建成功。查看终端输出中最早出现的错误，并确认模拟器实际安装、启动了 App。

需要在 Xcode 中操作时，打开 CocoaPods 安装后生成的工作区，选中应用对应的 Scheme 与可用模拟器，再执行 Build 或 Run。若目标是连接真机或进行分发，则另行检查 Signing & Capabilities、Team、证书与描述文件；自动签名可由 Xcode 管理相关配置，手动签名则需要匹配的签名资产。

按错误出现的位置排查编译失败

与其先清缓存，不如从构建日志中定位第一个明确错误，并按失败环节检查：

• 依赖安装阶段失败：检查 Node.js 版本声明、包管理器与锁文件是否匹配；若提示包版本或脚本错误，先回看 package.json 与安装日志。
• Xcode 脚本找不到 Node.js：在终端核对 which node，再检查 .xcode.env 中的 NODE_BINARY 及构建脚本环境；终端能找到 Node.js，不保证 Xcode 脚本也能找到。
• Pods 解析或集成失败：检查 Podfile、Podfile.lock、CocoaPods 命令输出及项目要求的 Ruby 环境。只有在依赖定义或锁文件需要变化时才考虑更新 Pods。
• SDK 或模拟器目标不可用：核对当前活动 Xcode、已安装运行时、目标设备与工程部署目标；模拟器组件可在 Xcode 设置中管理。(Apple 的 Xcode 附加组件安装说明)
• 签名错误：若模拟器构建通过、真机或归档失败，检查 Bundle Identifier、Team、签名证书和描述文件；不要把签名故障误判为 CocoaPods 问题。

可逐项完成这份自检清单，再决定是否进入下一步：

• [ ] Node.js 版本符合项目声明，使用的包管理器与仓库锁文件一致。
• [ ] JavaScript 依赖安装完成，package.json 中的 iOS 脚本可核对。
• [ ] Xcode 已启动并完成必要组件设置，xcode-select -p 指向预期工具链。
• [ ] 目标 iOS 模拟器运行时已安装，Xcode 能列出目标设备。
• [ ] 项目确实使用 CocoaPods 时，pod install 已按项目说明完成，且工作区文件符合预期。
• [ ] 模拟器构建与运行通过；如需真机或发布，再单独确认签名配置。

如果本地没有可运行 Xcode 的 Mac，Windows 或 Linux 环境虽然可用于部分 JavaScript 开发，却不能代替 Mac 上的 Apple 原生工具链来完成此类本地 iOS 编译；自购 Mac 更适合长期、稳定且有实体设备调试需求的工作。只为阶段性验证、团队协作或临时构建时，远程 Mac 可作为另一种方案，但仍需核对项目依赖、模拟器使用和签名权限是否适合远程操作。可以查看 Zutcloud 目前公开的 Mac 环境与租用信息，并通过帮助中心的远程连接说明确认实际操作条件；若要比较公开套餐，可再查看配置与计费页面。