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文件进行定制。

但代价也很明显：你需要自己搞定所有环境依赖。

原生环境依赖一览表

✅ 数据来源： 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 开发者的一天：

1. npx expo start
2. 扫码看效果 → 修改代码 → 实时刷新
3. 添加新功能：npx expo install expo-location
4. 发布前：eas build -p android自动生成 APK
5. 提交应用商店

全程基本不碰 Xcode 和 Android Studio。

原生 CLI 开发者的一天：

1. npx react-native start
2. npx react-native run-ios→ 等待 Xcode 编译
3. 改了一行 JS？还得 Reload（Cmd+R）
4. 加了个原生库？进ios/Podfile加依赖，pod install
5. 发布？自己配 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
• 若使用无线调试，确保在同一局域网

通用技巧：关掉杀毒软件和防火墙试试。

最终建议：根据项目类型做决策

🔥 高阶提示：Expo 现在支持Config Plugins，允许你在不 eject 的情况下添加原生配置。这意味着你可以在享受 Expo 便利的同时，逐步扩展原生能力——这是近年来最大的进步之一。

写在最后：环境只是起点，理解才是关键

无论你选 Expo 还是原生 CLI，记住一点：

工具越自动化，出问题时越难排查。

所以哪怕你从 Expo 入门，也建议花时间了解：
- Metro 是做什么的？
- Bridge 通信机制是怎样的？
- JS 和原生之间如何传参？
- 为什么改了原生代码要重新编译？

这些底层知识不会立刻提升你的开发速度，但在关键时刻能救你一命。

未来，随着 React Native 新架构（Fabric + TurboModules）的普及，桥接机制将被重构，通信效率大幅提升，而环境配置也会进一步简化。

但对工程师而言，永远不变的是：知其然，更要知其所以然。

如果你正在尝试搭建环境却卡在某一步，欢迎留言描述具体错误信息，我可以帮你一起分析。毕竟，每个成功的 App，都是从第一个npx expo start开始的。