如何在本地搭建 React Native iOS 开发环境

在本地搭建 React Native iOS 项目听起来很简单，但实际操作中常会遇到问题：Ruby 版本不兼容、CocoaPods 安装失败、Xcode 配置不当，甚至神秘的构建错误。下面是一个真实可行的完整环境搭建流程。

🍎 步骤 0 — 准备 Xcode（关键但容易忽略）

即便你已经从 App Store 安装了 Xcode，系统可能还没有完全配置好命令行工具。我在遇到问题后，完成了以下步骤才顺利运行：

1. 选择正确的 Xcode 路径

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcode-select -p

预期输出：

/Applications/Xcode.app/Contents/Developer

2. 同意 Xcode 许可协议

sudo xcodebuild -license

然后：

• 按 space 滚动查看协议
• 在末尾输入 agree 同意

如果没有完成这步，构建可能会无提示失败或报错。

3. 安装命令行工具（如果尚未安装）

xcode-select --install

React Native iOS 构建依赖 Xcode 工具链和 iOS SDK。正确配置可以避免 pod install 或构建失败。

🧰 步骤 1 — 检查 Ruby 环境

检查当前使用的 Ruby：

which ruby
ruby -v

如果显示类似：

~/.rbenv/shims/ruby
ruby 2.7.6

说明 rbenv 正在管理你的 Ruby，而不是系统或 Homebrew Ruby。

🚀 步骤 2 — 使用 rbenv 安装新版 Ruby

rbenv install 3.3.0
rbenv global 3.3.0
rbenv rehash
ruby -v

📦 步骤 3 — 安装 CocoaPods

gem install cocoapods
pod --version

📁 步骤 4 — 安装 iOS 依赖

cd ios
pod install

🔄 步骤 5 — 更新 Pod 仓库（如有需要）

pod repo update
# 或者结合安装
pod install --repo-update

⚠️ 常见问题及解决方法

• pod install 失败：运行 pod repo update
• CocoaPods 未找到：运行 gem install cocoapods 并 rbenv rehash
• Ruby 版本未生效：确保 rbenv 已启用：eval "$(rbenv init -)"
• gem 权限错误：避免使用 sudo，使用 rbenv 管理的 Ruby

🧼 可选清理

如果你通过 Homebrew 安装了 Ruby 但不使用它：

brew uninstall ruby

这样可以避免混淆，因为 rbenv 已在管理 Ruby 版本。

✅ 最终流程总结

# 安装 Ruby
rbenv install 3.3.0
rbenv global 3.3.0

# 安装 CocoaPods
gem install cocoapods

# 安装 iOS 依赖
cd ios
pod install --repo-update

💡 关键要点

• CocoaPods 依赖 Ruby → 保持 Ruby 更新
• rbenv 会覆盖系统和 Homebrew Ruby
• brew upgrade ruby 不会影响 rbenv
• 始终在 ios 文件夹内运行 pod install
• 依赖失败时，使用 pod repo update

🎯 总结

最大的困惑来自于同时存在多个 Ruby 环境：系统 Ruby、Homebrew Ruby 和 rbenv Ruby。一旦确认 rbenv 在控制版本，所有操作都变得可预测。如果你在做 React Native iOS 开发，一个干净的 Ruby + CocoaPods 环境可以节省数小时的调试时间。

❤️ Support This Blog

---

If this post helped you, you can support my writing with a small donation. Thank you for reading.

---

Coffee ☕ Thanks 🙏 Extra Support ❤️