从零开始：Mac上手React Native环境搭建全记录
最近带几个前端同事转型移动开发，第一关就是在Mac上配通React Native的开发环境。别看只是“装几个工具”，实际过程中各种报错、卡顿、白屏轮番上演——尤其是M1芯片新机 + 最新版Xcode的组合，稍有不慎就掉进坑里。
今天我就以一个实战开发者的视角，把这套流程掰开揉碎讲清楚。不堆术语，不抄文档，只讲你真正需要知道的那些事，以及官方指南里不会明说的“潜规则”。
为什么是Mac？因为iOS绕不过去
React Native号称“一次编写，多端运行”，但如果你打算真刀真枪做产品，Mac几乎是必选项，原因很简单：
要打包和调试iOS应用，必须用Xcode，而Xcode只能跑在macOS上。
哪怕你主攻Android，Mac也能让你同时预览双端效果，省去频繁切设备的麻烦。再加上Homebrew这类神器的存在，整个工具链的管理比Windows友好太多。
所以，想认真搞RN开发？先搞定你的Mac环境。
第一步：先把地基建牢 —— Xcode与命令行工具
别跳过这一步：Xcode不只是个IDE
很多人以为Xcode只是写iOS代码用的，其实它是一整套原生构建系统的核心。你在终端执行npx react-native run-ios的时候，背后其实是Xcode在干活：
- 解析项目结构
- 编译原生模块（Objective-C/Swift）
- 启动模拟器
- 安装并运行
.app
所以，第一步不是装Node，而是去Mac App Store 搜 Xcode，下载安装（至少14.0以上版本）。
⚠️ 注意：Xcode体积很大（通常8GB+），建议连着Wi-Fi慢慢下。别用第三方渠道下载，容易签名失败。
安装完一定要打开一次！
这是新手最容易忽略的一点：安装完Xcode后必须手动启动一次。
打开后会提示你安装额外组件（比如Command Line Tools、模拟器镜像等）。这个过程可能持续几分钟，耐心等它走完。完成后，在菜单栏进入：
Xcode → Preferences → Locations确保“Command Line Tools”选中了当前Xcode版本。否则你会遇到经典错误：
xcrun: error: unable to find utility这就是因为CLI工具没关联上。
模拟器也得提前准备
RN默认启动iPhone模拟器。你可以先手动打开Xcode里的Simulator应用，检查是否已下载合适的系统镜像（推荐iOS 16或17，对应iPhone 14/15）。
如果没下载，点击：
File → New Simulator → 选择设备类型和OS版本之后可以用命令指定启动哪款设备：
npx react-native run-ios --simulator="iPhone 15"第二步：让安装变得简单 —— Homebrew登场
Mac上最不该手动装的，就是开发工具。Node、Watchman、CocoaPods……一个个去官网找DMG文件太原始了。
我们要用现代方式：Homebrew，一句话搞定所有依赖管理。
一句话安装Homebrew
打开终端，粘贴这行命令（来自官网）：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"安装完成后，brew会告诉你路径信息。如果是M1/M2芯片，路径通常是/opt/homebrew/bin；Intel则是/usr/local/bin。
你可以测试一下：
brew --version输出类似Homebrew 4.1.0就说明成功了。
用brew装Node.js（别自己去官网下）
接下来我们通过brew安装Node.js：
brew install node等待完成后再验证：
node --version # 应该看到 v18.x 或 v20.x npm --version # 至少 9.x✅ 推荐使用Node 18 LTS版本，稳定且兼容性最好。如果你想切换不同版本，可以用
nvm管理，但对新手来说直接brew装一个够用了。
顺便提一句：Watchman也可以用brew装，它是RN监听文件变化的守护进程：
brew install watchman虽然RN CLI现在自带了轻量级监听器，但大型项目还是建议装上Watchman，避免热更新失效。
第三步：处理iOS的“本地户口”—— CocoaPods不能少
React Native项目里有很多功能是靠原生实现的，比如相机、地图、推送通知。这些模块怎么集成进iOS工程？答案是：CocoaPods。
你可以把它理解为iOS世界的npm。
安装CocoaPods
Mac系统自带Ruby，所以我们可以直接用gem来安装：
sudo gem install cocoapods💡 如果你是M1芯片，可能会遇到架构冲突。可以用下面这条命令强制以x86_64模式运行：
bash arch -x86_64 sudo gem install cocoapods
安装完成后运行：
pod --version正常应输出1.15.x左右。
初始化Pod依赖
创建完RN项目后，进入ios目录，执行：
cd ios pod install --repo-update cd ..这一步会生成YourApp.xcworkspace文件，以后要用这个文件打开Xcode工程（而不是.xcodeproj）。
📌 牢记一条铁律：每次添加新的原生库后，都必须重新执行
pod install，否则Xcode看不到新模块。
常见问题如“找不到模块”、“编译报错RCTBridge头文件缺失”，八成是因为忘了这一步。
第四步：创建你的第一个React Native项目
现在轮到主角出场了：React Native CLI。
虽然现在也有Expo这种更简单的方案，但如果你想深入掌握原理、对接原生代码，CLI依然是首选。
初始化项目
运行这条命令：
npx @react-native-community/cli init MyFirstApp💡 想用TypeScript？加上模板参数：
bash npx @react-native-community/cli init MyFirstApp --template typescript
等待几分钟，项目就建好了。目录结构长这样：
MyFirstApp/ ├── App.js // 主界面组件 ├── index.js // 入口文件 ├── android/ // Android原生工程 ├── ios/ // iOS原生工程（含Podfile） ├── metro.config.js // JS打包配置 └── package.json // 依赖声明启动开发服务器
先进入项目根目录：
cd MyFirstApp然后启动Metro Bundler（负责打包JS代码并实时推送更新）：
npx react-native start浏览器会自动打开http://localhost:8081/debugger-ui，这是调试页面（按Cmd+D可在模拟器唤出菜单）。
第五步：跑起来！iOS模拟器初体验
回到另一个终端窗口，运行：
npx react-native run-ios第一次执行会比较慢，因为它要：
- 调用Xcode编译原生代码
- 构建bundle
- 安装到模拟器
如果一切顺利，你会看到一个蓝色背景的应用启动，写着“Welcome to React Native”。
恭喜！你的环境已经通了。
常见坑点与应对策略
❌ 白屏？多半是Metro没连上
现象：模拟器启动了，但屏幕全白，控制台无输出。
排查步骤：
- 确认
npx react-native start是否正在运行 - 检查模拟器能否访问本机网络（通常没问题）
- 在模拟器中摇一摇 → 选“Reload”试试
- 清除缓存重启：
bash npx react-native start --reset-cache
❌ pod install 失败？试试这几招
- 清理缓存：
bash pod cache clean --all - 删除旧文件重来：
bash rm -rf Pods/ Podfile.lock && pod install - M1芯片加前缀：
bash arch -x86_64 pod install
❌ 找不到模拟器？
运行：
xcrun simctl list devices available查看可用设备列表。如果为空，说明系统镜像没装好，回Xcode补下载。
开发体验优化建议
编辑器推荐：VS Code + 插件包
- React Native Tools：官方插件，支持命令面板快速运行
- ESLint / Prettier：统一代码风格
- Bracket Pair Colorizer：提升可读性
快速调试技巧
- 修改JS代码 → 自动刷新（Fast Refresh）
- 摇一摇模拟器 → 调出Dev Menu → 开启“Live Reload”或“Debug”
- 使用Chrome DevTools调试逻辑层（注意：不能调试原生UI）
总结：环境搭建的本质是什么？
很多人觉得“搭环境”是在走流程，其实不然。
真正重要的，是理解每个工具的角色：
| 工具 | 角色 |
|---|---|
| Xcode | iOS的编译引擎，没有它iOS跑不起来 |
| Homebrew | 工具管家，帮你避开手动配置的深渊 |
| Node.js + npm | JS世界的操作系统，RN跑在这上面 |
| CocoaPods | 原生模块的“包办婚姻中介”，把第三方库塞进iOS工程 |
| React Native CLI | 你的指挥官，一声令下，全平台响应 |
当你把这些拼图连起来，就会发现：所谓“环境搭建”，其实是构建一个跨语言、跨平台的协作系统。
只要地基稳了，后面无论是接入摄像头、调用蓝牙，还是集成支付SDK，都不会再被环境问题绊住脚步。
如果你按照这篇指南操作，绝大多数人在2小时内就能跑通第一个App。下一步可以尝试：
- 改动
App.js，加个按钮看看热更新 - 学习使用
react-navigation做页面跳转 - 接入
@react-native-camera/camera试试拍照功能
技术这条路，永远是动手比观望更重要。
有问题欢迎留言交流，我们一起踩坑、填坑、不再踩坑。
