React Native 环境搭建实战指南：Expo 与原生 CLI 如何选？怎么配？
你有没有经历过这样的场景：兴致勃勃想用 React Native 写个 App，结果刚打开文档就被“安装 Xcode、配置 Android SDK、设置环境变量”一套组合拳打懵？
明明是写 JavaScript 的前端开发者，怎么突然要跟 Gradle 和 CocoaPods 打交道了？
别急——这正是每一个 RN 新手都会踩的坑。“react native 搭建环境”这件事本身，几乎可以决定你对这个框架的第一印象是爱还是恨。
今天我们就来彻底拆解这个问题。不讲空话，不堆术语，只聚焦一个目标：让你在最短时间内，选择最适合自己的路径，并真正把项目跑起来。
从零开始前，先搞清楚一件事：React Native 到底怎么工作？
在动手之前，得明白你在配置什么。
React Native 不是“把网页打包成 App”，它做的事情更聪明：
- 你写的 JSX 和 JavaScript 代码运行在一个独立的 JS 引擎里（通常是 Hermes 或 JSC）
- 原生端（iOS/Android）通过一个叫Bridge的机制和 JS 层通信
- 当你要渲染按钮、发起网络请求、调用相机时，JS 层会发消息给原生层，由真正的原生组件去执行
所以你的开发环境必须同时支持：
1. JS 代码的打包服务（Metro bundler）
2. iOS 原生编译与模拟器（Xcode）
3. Android 构建工具链（Android Studio + SDK + Gradle）
听起来复杂？没错，这就是为什么很多人转向Expo—— 它试图帮你屏蔽这些底层细节。
路径一：极简启动 —— 使用 Expo 快速上手
什么时候该用 Expo？
如果你符合以下任意一条：
- 第一次接触 React Native
- 想快速验证产品原型
- 主要做 UI 层开发，不需要接入指纹识别、蓝牙设备等深度原生功能
- 团队小，希望减少环境差异带来的协作成本
那 Expo 就是你最好的起点。
Expo 到底做了什么？
简单说，Expo 给你准备了一个“通用容器”：
- 它已经预装了常见的原生能力（如相机、定位、通知），你只需
import { Camera } from 'expo-camera'就能用 - 开发阶段，你可以用手机上的Expo Go App扫码实时预览，完全不用连电脑或开模拟器
- 发布时，可以用
eas build让 Expo 在云端帮你编译出 IPA/APK，省去本地配置 Xcode 和 Android Studio 的麻烦
💡 类比理解：Expo 就像“小程序开发框架”。你不用关心微信是怎么实现 WebView 的，只要按规则写页面就行。
怎么搭一个 Expo 环境？三步走
第一步：装 Node.js（基础依赖）
确保你已安装 Node.js ≥16.x（推荐 18.x LTS）。可以用 nvm 管理多个版本：
# macOS/Linux 用户可选 nvm install 18 nvm use 18第二步：创建项目
# 创建项目（会自动询问是否使用 TypeScript、启用严格模式等） npx create-react-native-app MyExpoApp --template cd MyExpoApp⚠️ 注意：不要用
react-native init！那是给原生 CLI 准备的命令。
第三步：启动开发服务器
npx expo start执行后会出现一个二维码和本地地址（通常是http://localhost:8081）。打开手机上的Expo Go（App Store / Google Play 都能搜到），扫码即可看到你的 App 实时运行！
📌 提示：如果真机无法连接，请确认手机和电脑在同一 Wi-Fi 下；也可以试试
npx expo start --tunnel使用远程隧道。
关键配置文件：app.json
这是 Expo 项目的“身份证”，定义了应用的基本信息：
{ "expo": { "name": "MyApp", "slug": "my-app", "version": "1.0.0", "orientation": "portrait", "icon": "./assets/icon.png", "userInterfaceStyle": "light", "splash": { "resizeMode": "contain", "backgroundColor": "#ffffff" }, "ios": { "supportsTablet": true }, "android": { "adaptiveIcon": { "foregroundImage": "./assets/adaptive-icon.png", "backgroundColor": "#FFFFFF" } } } }改动后无需重启 Metro，保存即生效。图标、启动图替换也只需要改路径即可。
路径二：全栈掌控 —— 原生 CLI 手动配置
什么时候非要用原生 CLI？
当你遇到这些问题时，Expo 可能就不够用了：
- 需要集成某个只有原生库的第三方 SDK（比如银行级加密模块）
- 要自定义启动页动画、修改状态栏行为
- 项目需要接入企业级 CI/CD 流水线
- 团队有原生开发人员，愿意为性能优化投入精力
这时候就得上React Native CLI。
原生 CLI 的核心思想
它不做封装，直接暴露两个原生工程目录：
MyApp/ ├── android/ ← Android Studio 工程 ├── ios/ ← Xcode 工程 ├── src/ ← 你的 JS 代码 └── package.json你可以像维护原生项目一样打开.xcworkspace或build.gradle文件进行定制。
但代价也很明显：你需要自己搞定所有环境依赖。
原生环境依赖一览表
| 组件 | 作用 | 推荐版本 |
|---|---|---|
| Node.js | 运行 JS 工具链 | 16.x 或 18.x LTS |
| npm / yarn | 包管理 | yarn 更稳定 |
| Watchman | 监听文件变化（macOS） | 可选但建议安装 |
| Xcode | iOS 编译 & 模拟器 | ≥13.0，需安装 Command Line Tools |
| Android Studio | Android 构建环境 | 2020.3.1+，需配置 SDK、JDK、Gradle |
✅ 数据来源： React Native 官方文档
初始化原生项目全流程
# 1. 安装 CLI 工具（全局） npm install -g @react-native-community/cli # 2. 创建项目（注意：不是 create-react-native-app） npx react-native init MyApp --skip-install # 3. 进入项目并安装依赖 cd MyApp npm install # 4. 启动 Metro 打包服务 npx react-native start --reset-cache此时浏览器会打开http://localhost:8081，说明 Metro 已就绪。
分平台运行 App
启动 iOS 应用
# 自动打开模拟器并安装 npx react-native run-ios # 指定特定设备 npx react-native run-ios --simulator "iPhone 14 Pro Max"常见问题：“No devices available”？
可能原因：
- Xcode 命令行工具未设置
- 模拟器未正确安装
- CocoaPods 依赖未拉取
解决办法：
# 设置 Xcode 路径 sudo xcode-select -s /Applications/Xcode.app/Contents/Developer # 安装命令行工具 xcode-select --install # 进入 ios 目录重新安装 Pods cd ios && pod deintegrate && pod install && cd ..启动 Android 应用
前提：已打开 Android 模拟器 或 连接真机（开启 USB 调试）
npx react-native run-android如果构建失败提示 “Could not resolve all artifacts”，大概率是网络问题导致 Gradle 下不了依赖。
解决方案：更换国内镜像源。
编辑android/build.gradle：
allprojects { repositories { maven { url 'https://maven.aliyun.com/repository/jcenter' } maven { url 'https://maven.aliyun.com/repository/google' } mavenCentral() } }保存后重新运行run-android即可。
Expo vs 原生 CLI：到底怎么选？
别纠结“哪个更好”，关键是“哪个更适合你现在”。
我们来看一张实战对比表：
| 维度 | Expo | 原生 CLI |
|---|---|---|
| 上手难度 | ⭐⭐⭐⭐⭐（半小时内跑起来） | ⭐⭐（半天起步） |
| 原生访问能力 | ⭐⭐（受限，除非 eject） | ⭐⭐⭐⭐⭐（完全自由） |
| 构建发布灵活性 | ⭐⭐⭐（依赖 EAS 云构建） | ⭐⭐⭐⭐⭐（本地签名、分渠道打包自如） |
| 学习曲线 | 平缓，专注 JS | 陡峭，需懂原生生态 |
| 团队协作效率 | 高（统一环境） | 中等（容易出现“我这边能跑”问题） |
| CI/CD 支持 | 简单（EAS Build 内置） | 复杂（需自建流水线） |
典型工作流对比
Expo 开发者的一天：
npx expo start- 扫码看效果 → 修改代码 → 实时刷新
- 添加新功能：
npx expo install expo-location - 发布前：
eas build -p android自动生成 APK - 提交应用商店
全程基本不碰 Xcode 和 Android Studio。
原生 CLI 开发者的一天：
npx react-native startnpx react-native run-ios→ 等待 Xcode 编译- 改了一行 JS？还得 Reload（Cmd+R）
- 加了个原生库？进
ios/Podfile加依赖，pod install - 发布？自己配 keystores、provisioning profiles…
累吗？累。但控制力强啊。
避坑指南：那些年我们都踩过的雷
❌ 坑点 1：Node 版本太旧或混乱
现象：Error: Cannot find module 'node:fs'或SyntaxError: Unexpected token 'export'
原因：Node < 14 不支持某些 ES Module 语法。
✅ 解法：
- 统一使用 Node 16 或 18
- 推荐搭配nvm管理版本
- 团队可在项目根目录加.nvmrc文件指定版本
echo "18" > .nvmrc # 切换时执行 nvm use❌ 坑点 2：依赖安装失败（尤其 Pod）
现象：pod install卡住、报错、无限重试
✅ 解法：
- 清理缓存bash pod cache clean --all rm -rf ~/.cocoapods/repos
- 更换镜像源（清华 TUNA）
- 使用 Yarn 替代 npm（锁版本更可靠）
- Mac M1 芯片用户尝试：bash arch -x86_64 pod install
❌ 坑点 3：真机调试连不上
iOS：
- 设置 → 通用 → 设备管理 → 信任开发者证书
- 断开重连，或重启 Expo Go
Android：
- 开启 USB 调试
- 执行命令打通端口：
bash adb reverse tcp:8081 tcp:8081 - 若使用无线调试，确保在同一局域网
通用技巧：关掉杀毒软件和防火墙试试。
最终建议：根据项目类型做决策
| 项目类型 | 推荐方案 | 理由 |
|---|---|---|
| MVP 原型 / 教学 demo | Expo | 秒级启动，专注逻辑验证 |
| 中小型商业应用（电商、社交） | Expo + EAS | 快速迭代 + 云端构建保障一致性 |
| 需要生物识别/BLE/OCR 等原生能力 | 原生 CLI | 自由引入任何原生库 |
| 超大型系统（金融、医疗） | 原生 CLI + Monorepo | 最大化可控性与长期可维护性 |
🔥 高阶提示：Expo 现在支持Config Plugins，允许你在不 eject 的情况下添加原生配置。这意味着你可以在享受 Expo 便利的同时，逐步扩展原生能力——这是近年来最大的进步之一。
写在最后：环境只是起点，理解才是关键
无论你选 Expo 还是原生 CLI，记住一点：
工具越自动化，出问题时越难排查。
所以哪怕你从 Expo 入门，也建议花时间了解：
- Metro 是做什么的？
- Bridge 通信机制是怎样的？
- JS 和原生之间如何传参？
- 为什么改了原生代码要重新编译？
这些底层知识不会立刻提升你的开发速度，但在关键时刻能救你一命。
未来，随着 React Native 新架构（Fabric + TurboModules）的普及，桥接机制将被重构，通信效率大幅提升，而环境配置也会进一步简化。
但对工程师而言，永远不变的是：知其然，更要知其所以然。
如果你正在尝试搭建环境却卡在某一步，欢迎留言描述具体错误信息，我可以帮你一起分析。毕竟，每个成功的 App，都是从第一个npx expo start开始的。
