从零开始：手把手教你搭建 React Native 开发环境并运行第一个应用
你是不是也曾在网上搜了一堆教程，下载了 Node.js、装了 Android Studio、折腾了半天 Xcode，结果一执行npx react-native run-android就报错一堆？别急——这几乎是每个 React Native 新手都会踩的坑。
今天，我就以一个“过来人”的身份，带你从零开始完整走一遍 React Native 环境搭建 + 项目初始化 + 成功运行应用的全流程。不讲空话，只说实战中真正有用的配置细节和避坑指南。无论你是 Windows 还是 macOS 用户，看完这篇都能把环境跑通。
为什么 React Native 的环境这么“难搞”？
React Native 并不是一个纯前端框架。它本质是JavaScript + 原生平台桥接的技术组合，这意味着：
- 你要写 JS/TS 代码（前端部分）
- 但最终这些代码要被“翻译”成 iOS 和 Android 的原生组件
- 所以背后依赖了一整套原生开发工具链：JDK、Android SDK、Xcode、CocoaPods……
换句话说：
你不仅是个前端开发者，还得临时客串一下 Android 和 iOS 工程师
这就导致很多初学者卡在第一步——环境没配好，连Hello World都跑不起来。
那怎么办？别慌。我们一步步来，拆解清楚每一个关键环节。
第一步：搞定基础运行时 —— Node.js 与 npm
所有 React Native 项目的起点，都是 Node.js。
为什么必须用 Node.js？
因为整个 RN 生态都建立在 Node 之上：
- CLI 命令行工具（如react-native init）是用 Node 写的
- Metro 打包服务是一个本地 Node 服务器
- 项目依赖通过 npm/yarn 安装
所以，没有 Node，寸步难行。
推荐版本 & 安装建议
✅推荐使用 Node.js 18.x LTS 版本
虽然官方支持 16~20，但 18 是目前最稳定的黄金版本，社区兼容性最好。
📌 小技巧：用nvm管理 Node 版本，避免多个项目冲突
# 安装 nvm（macOS/Linux） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装并切换到 Node 18 nvm install 18 nvm use 18如果你在国内，强烈建议换源加速依赖安装：
npm config set registry https://registry.npmmirror.com这样以后装包速度能快好几倍。
第二步：为 Android 准备好 JDK 和 SDK
1. JDK 到底要用哪个版本？
很多人不知道的是：React Native 对 JDK 版本非常敏感。
截至当前主流版本（RN 0.72+），你应该使用：
✅JDK 17（不是 JDK 8，也不是 JDK 20！）
原因很简单：新版 Gradle 构建系统要求 JDK 17，否则会抛出类似这样的错误：
Could not resolve all files for configuration ':classpath' Unsupported class file major version 61🔍 补充知识：Java 类文件版本号对应关系
- JDK 8 → v52
- JDK 17 → v61 ← 正确选择
- JDK 20 → v64 → 不兼容旧版 Gradle
如何安装 JDK 17？
- Windows/macOS：去 Adoptium 下载安装包（选 Temurin-17）
- macOS（Homebrew）：
bash brew install openjdk@17 - Linux（Ubuntu）：
bash sudo apt install openjdk-17-jdk
然后设置环境变量：
# macOS/Linux 示例 export JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home把这个加到你的 shell 配置文件里（.zshrc或.bashrc），不然每次重启终端都要重新设置。
2. 安装 Android Studio 与 SDK
即使你不打算打开 IDE，Android Studio 也是必须安装的，因为它包含了构建 APK 所需的核心工具。
必须安装的组件：
- ✔️ Android SDK
- ✔️ Android SDK Platform-Tools（包含 adb）
- ✔️ Android Emulator
- ✔️ 至少一个系统镜像（比如 Android 12 API 31）
安装时记得勾上这三个选项！
设置 ANDROID_HOME 环境变量
这是最容易出错的地方之一。Gradle 找不到 SDK 就会编译失败。
# macOS 默认路径 export ANDROID_HOME=$HOME/Library/Android/sdk # 添加到 PATH export PATH=$PATH:$ANDROID_HOME/platform-tools # adb export PATH=$PATH:$ANDROID_HOME/emulator # emulator保存后执行：
source ~/.zshrc # 或 .bashrc验证是否生效：
adb --version emulator -list-avds如果能正常输出，说明配置成功。
第三步：iOS 开发准备（仅限 macOS）
如果你用的是 Mac，恭喜你，可以同时开发 iOS 应用；如果是 Windows，请跳过此节。
核心依赖：Xcode + CocoaPods
- Xcode：苹果官方开发工具，提供编译器、模拟器和签名能力
- CocoaPods：iOS 的包管理器，用来集成 React Native 的原生模块
安装 Xcode
从 App Store 搜索 “Xcode” 下载安装即可（体积约 12GB，耐心等）。
安装完成后打开一次，让它自动安装命令行工具。
确认版本：
xcode-select --install xcodebuild -version # 应显示 Xcode 14+安装 CocoaPods
sudo gem install cocoapods⚠️ M1/M2 芯片注意：不要用 Rosetta 打开 Terminal，否则可能遇到架构问题。
第四步：创建你的第一个 React Native 项目
终于到了激动人心的时刻！
使用 CLI 初始化项目
npx react-native init MyFirstApp --version 0.72.5 cd MyFirstApp解释一下参数：
-npx：临时运行最新版 CLI，无需全局安装
---version 0.72.5：指定稳定版本，防止默认拉取不稳定的新版本
初始化过程大概需要几分钟，期间会：
- 自动生成android/和ios/目录
- 安装所有 JS 依赖
- 配置基本项目结构
💡 提示：国内用户若安装缓慢，可提前设置 npm 镜像或使用 cnpm
第五步：运行应用！让 Hello World 动起来
方式一：运行到 Android 设备/模拟器
先确保设备已连接或模拟器已启动。
# 启动 Metro 打包服务（监听 JS 变化） npx react-native start # 在另一个终端运行 Android npx react-native run-android常见情况：
- 如果有真机连接，优先安装到真机
- 没有设备则尝试启动 AVD 模拟器
- 成功后你会看到一个带“Welcome to React Native”字样的页面
方式二：运行到 iOS 模拟器（macOS）
首次运行前必须安装原生依赖：
cd ios && pod install --repo-update && cd ..然后启动：
npx react-native run-ios默认会启动 iPhone 14 模拟器并加载应用。
常见问题与解决方案（真实踩坑记录）
❌ 问题 1：Android 编译失败，“Could not determine the dependencies…”
典型报错：
Could not determine the dependencies of task ':app:compileDebugJavaWithJavac'根本原因：Gradle 找不到 JDK 或 SDK 路径
解决办法：
# 明确设置环境变量 export JAVA_HOME=/path/to/jdk-17 export ANDROID_HOME=$HOME/Library/Android/sdk # 清理缓存重试 cd android && ./gradlew clean && cd .. npx react-native run-android❌ 问题 2：iOS 报错 “No development teams are available”
这是 Xcode 签名问题。
解决步骤：
1. 打开MyFirstApp/ios/MyFirstApp.xcworkspace（一定要用 workspace）
2. 在左侧项目导航中选择主 target
3. 进入Signing & Capabilities
4. Team 选择你的 Apple ID（个人账户即可，无需付费开发者计划）
保存后重新运行。
❌ 问题 3：Metro 启动失败 / 端口占用
Metro 默认监听 8081 端口，常被其他进程占用。
查看谁占用了端口：
lsof -i :8081杀掉进程：
kill -9 <PID>或者换个端口启动：
npx react-native start --port=8082记得同步修改运行命令：
npx react-native run-android --port=8082实用技巧与最佳实践
✅ 启用 Hermes 引擎（默认已开启）
Hermes 是 Facebook 推出的轻量级 JS 引擎，显著提升启动速度和内存表现。
检查android/app/build.gradle中是否有：
project.ext.react = [ enableHermes: true ]iOS 侧也在 Podfile 中启用。
不用改，默认就是开的，放心。
✅ 使用 TypeScript 模板（推荐新项目使用）
TypeScript 能大幅提升代码可维护性。
创建 TS 项目：
npx react-native init MyTsApp --template react-native-template-typescript你会发现App.tsx文件，支持类型检查和智能提示。
✅ 国内优化：替换 CocoaPods 源（iOS 用户必看）
默认源在国外，pod install经常超时。
换成清华镜像：
pod repo remove trunk pod repo add tencent https://mirrors.cloud.tencent.com/cocoapods/repos/trunk/ pod repo add aliyun https://github.com/aliyun/aliyun-specs.git pod install速度立竿见影。
总结：你现在掌握了什么？
到现在为止，你应该已经完成了以下关键动作：
- ✅ 安装了正确的 Node.js 和 JDK 版本
- ✅ 配置好了 Android SDK 和环境变量
- ✅ 在 macOS 上装好了 Xcode 和 CocoaPods
- ✅ 成功初始化并运行了一个 React Native 项目
- ✅ 解决了最常见的编译和连接问题
更重要的是，你理解了：
- 为什么 RN 需要这么多工具链
- 每个组件（Node、JDK、SDK、Xcode）到底起什么作用
- 出错时如何定位问题根源，而不是盲目复制粘贴
下一步该做什么？
现在你可以：
1. 修改App.tsx文件试试热重载（保存即刷新）
2. 摇晃手机或按Cmd+D打开调试菜单
3. 选择 “Debug with Chrome” 用 DevTools 调试 JS
4. 开始学习 React Native 组件（View、Text、Image、ScrollView 等）
当你能在两台设备上同时跑起同一个应用，并且改动代码立刻同步更新时，那种“跨平台”的成就感，真的会上瘾。
如果你在搭建过程中遇到了文中没提到的问题，欢迎留言交流。毕竟每一个成功的开发者，都是从无数次失败的./gradlew中走出来的。
