从零开始搭建 React Native 开发环境：实战一个电商 App 的诞生
你有没有遇到过这样的场景？团队里 Android 和 iOS 各自为战，同一个功能要写两遍代码，改一个 UI 要同步两边，上线节奏永远对不上。尤其在电商业务中，大促前频繁迭代商品页、购物车、优惠券逻辑，开发效率直接决定能否抓住流量红利。
而今天我们要聊的React Native，正是为解决这类问题而生的利器。它不是“伪原生”，也不是简单的 WebView 套壳，而是真正用 JavaScript 构建出接近原生体验的移动应用。更重要的是——一次开发，双端运行。
但再强大的框架，也得先能跑起来。很多开发者卡在第一步：环境搭不起来。红屏、白屏、依赖报错、模拟器连不上……本文就带你手把手打通 React Native 环境搭建的“任督二脉”，并以一个真实的电商项目为例，从安装到运行，全程实战。
为什么电商项目特别适合用 React Native？
在进入技术细节之前，先回答一个问题：为什么我们选择“电商 App”作为示例？
因为电商是典型的高频交互 + 快速迭代 + 多原生能力调用的应用类型：
- 商品列表、分类导航、搜索框 → 高度组件化 UI
- 购物车状态跨页面共享 → 需要成熟的状态管理
- 支付宝/微信支付、相机扫码、推送通知 → 深度依赖原生模块
- 大促期间每日更新 → 热重载和快速构建至关重要
这些需求恰好与 React Native 的优势高度契合：
✅ 组件复用性强
✅ 支持热重载（改完即看）
✅ 可无缝集成原生 SDK
✅ 社区生态丰富（导航、动画、状态管理均有成熟方案）
所以，掌握如何为这样一个复杂度适中的项目搭建环境，远比做一个“Hello World”更有实战价值。
第一步：准备好你的“地基”——Node.js 与包管理器
任何 React Native 项目都建立在 Node.js 之上。你可以把它理解为 JS 的“发动机”，没有它，后续所有工具链都无法运转。
推荐配置清单：
- Node.js: 使用 LTS 版本（v18 或 v20），稳定且兼容性好
- 包管理器: 优先使用Yarn，而非 npm
别小看这个选择。我在多个项目中见过因npm install安装出不同版本依赖导致“在我机器上能跑”的经典坑。Yarn 的yarn.lock文件能锁定每个依赖的具体版本，确保团队成员拿到的是完全一致的依赖树。
# 检查是否已安装 node --version yarn --version如果你还没装，推荐通过 nvm 来管理 Node 版本，尤其是当你需要在多个项目间切换时。
💡 小贴士：Mac 用户可以用 Homebrew 一键安装基础工具：
bash brew install node yarn watchman其中
watchman是 Facebook 开发的文件监控工具，Metro 打包器靠它感知代码变化，实现热重载。
第二步：选对“起点”——CLI 还是 Expo？
React Native 有两种主流开发方式：React Native CLI和Expo CLI。很多人一上来就被这个选择难住。我们来划重点。
| 对比项 | React Native CLI | Expo CLI |
|---|---|---|
| 是否可访问原生代码 | ✅ 完全自由 | ❌ 受限（需 EAS 解锁） |
| 配置难度 | ⚠️ 较高 | ✅ 极低 |
| 启动速度 | 较慢（首次编译久） | 极快（扫码即用） |
| 原生库兼容性 | 高 | 中等 |
| 适用阶段 | 成熟产品、复杂业务 | MVP 验证、教学演示 |
听清楚了：如果你要做的是真实电商项目，涉及微信支付、地图定位、摄像头扫码等功能，那必须选React Native CLI。
Expo 虽然上手快，但它像一辆“封闭座舱”的车，你想加个外挂设备都得申请权限。而 CLI 则像一辆开放平台的皮卡，你想装什么都可以。
初始化命令如下：
npx react-native init ECommerceApp这条命令会生成一个包含完整 Android 和 iOS 原生工程的目录结构，意味着你可以随时深入底层做定制。
第三步：搞定双端构建环境——Android Studio 与 Xcode
React Native 最终还是要编译成 APK 和 IPA 包，这就绕不开官方开发工具。
Android 端：Android Studio 不只是 IDE
即使你不写 Java/Kotlin，Android Studio 也是必不可少的。你需要它来：
- 安装 Android SDK（特别是 Platform-tools 和 Build-tools）
- 管理模拟器（AVD）
- 查看 Logcat 日志调试原生问题
安装完成后，记得设置环境变量。否则react-native run-android时可能会找不到 SDK。
# 添加到 ~/.zshrc 或 ~/.bash_profile export ANDROID_HOME=$HOME/Android/Sdk export PATH=$PATH:$ANDROID_HOME/emulator export PATH=$PATH:$ANDROID_HOME/platform-tools常见问题如gradlew.bat app:installDebug失败，大概率是因为 JDK 版本不对。建议统一使用JDK 11，过高或过低都会引发兼容性问题。
iOS 端：Xcode 是唯一选择
抱歉，iOS 开发只能在 macOS 上进行。
从 App Store 下载 Xcode 后，还需执行以下命令：
# 安装命令行工具 xcode-select --install # 接受许可协议 sudo xcodebuild -license acceptM1/M2 芯片 Mac 用户注意：部分 CocoaPods 插件尚未完全适配 ARM 架构，可能遇到ffi错误。解决方案是强制用 Rosetta 模式安装：
arch -x86_64 gem install ffi arch -x86_64 pod install第四步：处理 iOS 依赖——CocoaPods 到底是什么？
当你进入ios目录看到那个Podfile，是不是有点懵？其实很简单：CocoaPods 就是 iOS 的 npm。
React Native 的很多功能（比如网络请求、本地存储、传感器）其实是通过原生模块实现的，这些模块由第三方提供，并通过 CocoaPods 自动集成到你的 Xcode 工程中。
关键操作只有一步：
cd ios pod install --repo-update cd ..执行后会生成.xcworkspace文件，之后打开 iOS 项目一定要用这个文件，而不是.xcodeproj。
📌重要提醒：
- 不要手动修改 Pods 目录下的内容
- 把Podfile.lock提交进 Git，保证团队依赖一致
- 若想支持某些静态库冲突，可在Podfile中添加use_frameworks!
第五步：让 JS 动起来——Metro 打包器详解
现在原生环境齐了，JS 代码怎么送到手机上运行？答案就是Metro Bundler。
Metro 是 React Native 默认的 JS 打包器。它的核心职责是：
- 将所有
.js文件打包成一个 bundle - 通过 WebSocket 推送到设备
- 监听文件变化，实现热重载
启动命令很简单：
npx react-native start你会看到一个终端界面，显示打包进度和连接状态。默认监听localhost:8081。
调试技巧三连击：
- 在手机上摇一摇（或模拟器快捷键）→ 弹出开发者菜单
- 选择 “Debug” → 浏览器打开 Chrome DevTools，查看 console 输出
- 安装React Developer Tools插件，实时查看组件树结构
还可以自定义 Metro 配置，比如直接把 SVG 当作组件引入（电商图标多，这很实用）：
// metro.config.js const {getDefaultConfig} = require('metro-config'); module.exports = (async () => { const { resolver: {sourceExts}, } = await getDefaultConfig(); return { transformer: { babelTransformerPath: require.resolve('react-native-svg-transformer'), }, resolver: { sourceExts: [...sourceExts, 'svg'], }, }; })();这样就可以这样用了：
import Logo from './assets/logo.svg'; <Logo width={50} height={50} />实战：跑通第一个电商页面
环境都配好了，来点真家伙。
假设我们要做一个首页，展示某个分类的商品列表。结构清晰：API 请求 → 数据解析 → 列表渲染。
1. 接入 API 服务
// services/api.js import axios from 'axios'; const API_BASE = 'https://api.ecommerce-demo.com'; export const fetchProducts = async (category) => { try { const response = await axios.get(`${API_BASE}/products`, { params: { category } }); return response.data; } catch (error) { console.error('Failed to fetch products:', error); throw error; } };2. 渲染商品列表组件
// components/ProductList.js import React, { useEffect, useState } from 'react'; import { View, FlatList, Text, ActivityIndicator } from 'react-native'; import { fetchProducts } from '../services/api'; const ProductList = ({ category }) => { const [products, setProducts] = useState([]); const [loading, setLoading] = useState(true); useEffect(() => { const loadProducts = async () => { setLoading(true); try { const data = await fetchProducts(category); setProducts(data); } catch (err) { // 可弹出 Toast 提示 } finally { setLoading(false); } }; loadProducts(); }, [category]); if (loading) { return ( <View style={{ padding: 20 }}> <ActivityIndicator size="large" color="#0000ff" /> </View> ); } return ( <FlatList data={products} keyExtractor={item => item.id} renderItem={({ item }) => ( <View style={{ padding: 16, borderBottomWidth: 1, borderColor: '#eee' }}> <Text style={{ fontSize: 16 }}>{item.name}</Text> <Text style={{ color: 'red', marginTop: 4 }}>¥{item.price}</Text> </View> )} /> ); }; export default ProductList;然后运行：
# 启动 Metro npx react-native start # 构建 Android npx react-native run-android # 构建 iOS（macOS） npx react-native run-ios几分钟后，你就会在模拟器或真机上看到商品列表成功加载。
常见问题避坑指南
别以为配完就能一帆风顺。以下是我在项目中总结的高频问题及对策：
| 问题现象 | 原因分析 | 解决方案 |
|---|---|---|
Command failed: gradlew.bat app:installDebug | JDK 版本不匹配 | 安装 JDK 11 并设置JAVA_HOME |
No connected devices found | USB 调试未开启 | 检查手机“开发者选项” |
Unable to load script | Metro 未启动或端口被占 | 重启 Metro，或指定端口--port 8082 |
CocoaPods not installed | Ruby 环境缺失 | sudo gem install cocoapods |
| 白屏或红屏 | JS 语法错误 / 依赖未 link | 检查终端日志，用console.log分段排查 |
特别提醒：红屏不是失败，而是调试助手！它会告诉你哪一行出了错，充分利用它。
电商项目的最佳实践建议
环境能跑了，接下来才是真正的开始。为了让项目更健壮，这里分享几点来自一线的经验：
1. 统一使用 Yarn，杜绝依赖漂移
// package.json "scripts": { "start": "react-native start", "android": "react-native run-android", "ios": "react-native run-ios" }团队协作时，明确要求所有人使用yarn install，不要混用 npm。
2. 环境隔离，避免误连生产接口
使用react-native-config实现多环境配置：
# .env.development API_URL=https://dev-api.ecommerce.com # .env.production API_URL=https://api.ecommerce.com代码中通过process.env.API_URL读取。
3. 启用 Hermes 引擎，提升性能
Hermes 是 Facebook 推出的轻量级 JS 引擎，专为 React Native 设计，能显著缩短启动时间和降低内存占用。
只需在android/app/build.gradle中启用：
project.ext.react = [ enableHermes: true ]iOS 端也在 Podfile 中开启：
use_react_native!( :path => config[:reactNativePath], :hermes_enabled => true )4. 敏感信息绝不硬编码
API 密钥、支付凭证等应使用原生存储，例如：
yarn add react-native-keychain将 token 存入系统钥匙串，避免被反编译泄露。
写在最后：环境搭建，不只是“第一步”
很多人觉得环境搭建是入门最简单的部分，但实际上，它是整个项目生命周期中最关键的一环。
一个配置混乱的环境会导致：
- 新人入职三天还跑不起项目
- CI/CD 流水线频繁失败
- 生产包构建不一致
而一个标准化、文档化的环境配置流程，则能让团队快速响应需求变更，在大促前夜也能安心发版。
本文以电商场景为切入点，不仅教你“怎么做”，更讲清楚“为什么这么做”。当你下次面对一个新的 RN 项目时，不会再盲目复制命令，而是能判断：该用 CLI 还是 Expo？要不要开 Hermes？Yarn lock 提不提交？
这才是真正的工程能力。
如果你正在考虑用 React Native 重构现有 App，或者启动一个新的跨平台项目，不妨从今天开始，把环境搭建当作一项正式的技术任务来对待。
欢迎在评论区分享你在搭建过程中踩过的坑，我们一起填平它。
