React Native 环境搭建 & 启动教程（macOS）
前置条件
- macOS 系统
- 已安装 Homebrew
- 已安装 Node.js
- 已安装 Xcode（iOS 开发必须）
- 已安装 Android Studio（Android 开发必须）
一、修复 Ruby 版本（iOS 必须）
macOS 自带的 Ruby 版本过低（2.6.x），CocoaPods 需要 Ruby >= 3.2.0，使用 rbenv 升级。
1. 安装 rbenv
brew install rbenv ruby-build
2. 将 rbenv 写入 shell 配置
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc
3. 安装 Ruby 3.3.0
rbenv install 3.3.0
rbenv global 3.3.0
编译过程约需 5~10 分钟，耐心等待。
4. 验证版本
ruby --version
# 应输出: ruby 3.3.0 ...
二、安装 CocoaPods（iOS 必须）
gem install cocoapods
验证安装：
pod --version
三、创建 React Native 项目
项目名称只能使用字母和数字（不能含连字符
-），推荐驼峰命名。
npx @react-native-community/cli init MyAppRn
cd MyAppRn
四、启动 iOS
每次打开新终端时，先确认 Ruby 环境
source ~/.zshrc
ruby --version # 确认是 3.3.0，不是系统的 2.6.x
运行项目
cd MyAppRn
npx react-native run-ios
⚠️ 注意目录：必须在
MyAppRn/目录内运行，不能在父目录my-app/下运行。 运行前用pwd确认路径末尾是MyAppRn，否则会报Unable to resolve module ./index错误。
首次运行会自动执行
pod install下载依赖，耗时较长，请耐心等待。
手动执行 pod install（依赖更新后需要）
cd ios
pod install
cd ..
npx react-native run-ios
五、配置 Android 开发环境（首次必须）
1. 安装 JDK 17
React Native 推荐使用 JDK 17（Eclipse Temurin）：
brew install --cask temurin@17
下载约 200MB，耐心等待。
2. 配置环境变量
将以下内容追加到 ~/.zshrc：
cat >> ~/.zshrc << 'EOF'
# Java
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
# Android SDK
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$PATH"
EOF
source ~/.zshrc
3. 验证配置
java -version
# 应输出: openjdk version "17.x.x" ...
adb --version
# 应输出: Android Debug Bridge version 1.x.x
六、启动 Android 模拟器
方式一：使用已有模拟器
- 打开 Android Studio
- 点击右上角 Device Manager 图标
- 找到已有模拟器，点击 ▶ 按钮 启动
- 等待模拟器完全启动（出现锁屏界面即可）
方式二：新建模拟器
- 打开 Android Studio → Device Manager
- 点击 "+" → Create Virtual Device
- 选择机型（推荐 Pixel 8）→ 点击 Next
- 选择系统镜像（推荐 API 35 或以上）→ 点击 Next → Finish
- 点击 ▶ 按钮 启动新建的模拟器
验证模拟器已连接：
adb devices # 应看到: emulator-5554 device
七、启动 Android 应用
运行前确认
# 新开终端时先执行（确保环境变量生效）
source ~/.zshrc
# 确认模拟器在线
adb devices
运行项目
cd MyAppRn
npx react-native run-android
⚠️ 注意目录：同 iOS，必须在
MyAppRn/目录内运行。
首次构建耗时较长（2~5 分钟），后续增量构建会很快。
八、常见问题
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
"xxx" is not a valid name | 项目名含连字符或特殊字符 | 改用驼峰命名，如 MyAppRn |
You don't have write permissions for /Library/Ruby/Gems/2.6.0 | 使用了系统 Ruby | 按第一节安装 rbenv 并切换到 3.3.0 |
connection_pool requires ruby >= 3.2.0 | Ruby 版本过低 | 同上，升级 Ruby |
pod install 失败或超时 | 网络问题或 Ruby 版本错误 | 检查网络；确认 ruby --version 为 3.3.0 |
| Android 找不到设备 | 模拟器未启动或 USB 调试未开启 | 先在 Android Studio 启动模拟器 |
Unable to resolve module ./index | 在错误目录下运行了命令 | cd MyAppRn 后再运行，用 pwd 确认当前路径 |
Unable to locate a Java Runtime | 未安装 JDK 或 JAVA_HOME 未配置 | 按第五节安装 JDK 17 并配置环境变量 |
adb: command not found | Android SDK platform-tools 未加入 PATH | 按第五节配置环境变量，然后 source ~/.zshrc |
spawnSync adb ENOENT | 当前终端未加载新 PATH | 执行 source ~/.zshrc 后重新运行 |
Failed to install SDK components: build-tools;35.0.0 | 缺少 Build-Tools 组件 | Android Studio → Settings → Android SDK → SDK Tools，安装对应版本 |
