React Native环境配置全攻略：从零搭建到第一个App跑通

说实话，ReactNative的环境配置是我见过劝退率最高的一个环节。很多人不是卡在React Native本身有多难，而是第一天的“Hello World”就死在了环境配置上——Node版本不对、JDK装错版本、Android SDK路径找不到、模拟器起不来，任何一个环节断了，后面的所有步骤全部白费。我这些年帮同事们救过无数次场，自己也重装过好几遍，把所有弯路都走了一遍，这篇就把配置ReactNative环境并创建第一个程序的完整过程拆开揉碎，按一个0基础纯小白照着敲就能跑通的标准来写。文章以Windows环境为例，其他系统的差异点我会在对应位置单独说明。

1. 动手之前，先搞明白RN环境是怎么串起来的

很多教程一上来就让你装这个装那个，装完了也不知道为什么要装。我觉得最容易被忽略的一步，其实是先在脑子里建立一条完整的运行链路。

React Native写的虽然是JavaScript/TypeScript代码，但它最终跑起来的是一个真正的原生App壳。你写的JS代码不是直接在手机上执行的，而是被一个叫Metro的工具先打包成一份bundle文件，然后由壳子里的原生代码去加载这份bundle，渲染出界面。这个过程跟网页开发里webpack打包的概念高度类似，但多了一层Android/iOS的原生构建环节。

所以你的电脑上至少需要以下几样东西，各司其职：

这套链路可以类比成做饭：Node是菜刀和案板，JDK是炉灶，Android SDK和Studio是食材和天然气管道，模拟器是炒锅，Metro则是那个把食材端到锅前的传菜员。任何一个环节断了，菜都出不来。所以你在配置过程中会反复用到npm、java、adb这三组命令去验证链路是否打通。

另外先说明一下版本的总体思路：React Native的版本迭代挺快，新版对Node和JDK的要求也在变。官方在Environment Setup文档里写得清楚，但很多人不看，直接装了最新版就踩坑。后面每一节我都会给出具体的版本建议，你照着装就行，不用纠结“最新”两个字。

2. Node.js和JDK：两个必须先装好的底层依赖

为什么我坚持把这一步放在Android Studio之前？因为RN项目的脚手架、依赖安装、脚本执行都依赖Node，而Android构建又依赖JDK。如果把顺序反了，你后面会不停回头补装，来回测试很浪费时间。

2.1 Node.js：版本选对，比装新更重要

React Native对Node的要求在0.75版本之后是大于等于18.18，官方推荐直接用20 LTS或22 LTS。我的建议非常明确：去官网下载LTS版本号最大的安装包，别碰Current版本。LTS是长期维护版，React Native官方测试的重点就是这些版本，用Current那种尝鲜版等于给自己添堵。

Windows下安装就是典型的“下一步工程师”流程，下载msi文件一路Next，没有需要改的地方。有一点要注意，Node安装器默认会把npm一起装好，也会把PATH环境变量配好。装完务必新开一个终端窗口再验证，因为旧窗口不会刷新环境变量。

验证命令：

bash复制node -v
npm -v

能输出类似 v20.x.x 和 10.x.x 这样的版本号就说明Node部分没问题。

很多小白会卡在一个细节：为什么我明明装了Node，在终端里敲node却提示“不是内部或外部命令”？这要么是安装时没勾选“Add to PATH”，要么是装完没有重开终端。前者重装一次，勾上Add to PATH就行；后者重新开个窗口就好。

2.2 JDK：必须17，别用8也别用11

React Native从0.73版本开始正式要求JDK 17，所以我默认你已经准备用最新版RN的话，直接装JDK 17最稳。装JDK 8或11的老教程适合旧版RN，对现在的新项目来说会直接导致Gradle构建失败，报错信息里通常会写“Unsupported class file major version”之类的话。

JDK我推荐用Eclipse Temurin的17版本，这是开源社区里用得最广泛的发行版，也可以直接用Android Studio自带的JBR（JetBrains Runtime），但为了少绕弯，我还是建议单独装一个，因为后面配置JAVA_HOME时更省心。

装完JDK需要手动加两个环境变量：

• 新建系统变量 JAVA_HOME，值为JDK的安装根目录，比如 C:\Program Files\Eclipse Adoptium\jdk-17.0.11
• 在系统变量 Path 里追加 %JAVA_HOME%\bin

然后在终端里验证：

bash复制java -version
javac -version
echo %JAVA_HOME%

第一个输出里应该能看到 openjdk version "17.0.x"，第二个javac也有版本号，第三个能打印出你设置的JDK路径。如果java有输出但javac没有，说明JAVA_HOME或者Path里的bin路径配错了，回头检查一下。

2.3 顺手处理npm的下载速度问题

这一步不算是环境配置的必选项，但以我帮别人装机的经验，基本上十个人里有八个会被npm的下载速度逼疯。npx创建项目时要从npm仓库拉取几百MB的依赖包，默认源在国外的话，等上十分钟还没动静是常有的事。

国内常用的做法是把npm registry切到npmmirror（淘宝镜像），这是一个常规的网络优化手段：

bash复制npm config set registry https://registry.npmmirror.com

配好后执行 npm config get registry 验证一下。这跟后面Android Studio里配Gradle仓库是同一个思路，都是把下载源换到离自己更近、更稳定的地方，属于开发环境优化的常规操作。介意的话可以跳过，但等依赖的时候别怪我没提醒你。

3. Android Studio与SDK：大头戏在这里

Android Studio体积大、下载慢、配置项多，是整个环境配置里最让人头疼的一块。但它没办法跳过，Android SDK、模拟器、构建工具基本都靠它来管理。

3.1 安装时别一路Next，看清这些选项

从官网下载Android Studio的安装包，启动安装向导时它会问你要不要同时装Android SDK和模拟器，这一步建议全部勾上。虽然你后面可以用SDK Manager手动补，但安装器一起装好会更省事。

安装向导里还有一项是选择安装类型，建议选Custom而不是默认的Standard，这样你能看到SDK要装到哪里。记住这个路径，默认情况下Windows是：

code复制C:\Users\你的用户名\AppData\Local\Android\Sdk

这个路径后面配环境变量时要反复用到，建议直接复制保存到笔记里。

3.2 SDK Manager里到底要装什么

启动Android Studio后，在欢迎页选择More Actions -> SDK Manager（如果你已经进了项目界面，通过Tools -> SDK Manager也能打开），你会看到一堆复选框，别全选，装多了没用还占空间。针对React Native开发，你只需要确认这几个组件安装了：

最后一个“System Image”是在创建虚拟设备时才需要下载的，它相当于模拟器的操作系统镜像，可以理解为给虚拟机装系统时需要的iso文件。建议选择API 34或API 35的Google APIs版本镜像，不要选带“Google Play”标记的，因为带Play Store的镜像默认没有root权限，调试时限制多。

3.3 创建并启动你的第一台模拟器

SDK就绪后，打开Android Studio右侧的Device Manager面板（找不到就在View菜单里搜），点击Create Virtual Device，按下面几步操作：

1. 在设备定义里选Pixel系列，我习惯选Pixel 6或Pixel 7，屏幕大小适中，跑起来不会太卡
2. 选择系统镜像：下载API 34的Google APIs x86_64镜像。这里注意，如果你的电脑是AMD处理器或者不支持Intel的硬件加速，选同样的x86_64镜像即可，Android Studio会自动处理加速方案
3. 给模拟器起个名字，点Finish完成创建
4. 在设备列表里点启动按钮，等模拟器完全开机，出现Android桌面界面就算成功

模拟器的启动速度取决于电脑硬件和加速环境。Windows下如果设备列表里显示“Running”但窗口一直黑屏或者转圈，最常见的两个原因是：电脑的虚拟化技术（VT-x/AMD-V）没有在BIOS里开启，或者Hyper-V/Windows Hypervisor Platform相关功能没启用。前者需要进BIOS开，后者在Windows的“启用或关闭Windows功能”里把Windows Hypervisor Platform勾上，重启后再试。

这里有个实用技巧：模拟器窗口打开后，不需要一直开着Android Studio，模拟器的运行进程跟Redis独立。你甚至可以先关掉Android Studio，单独留着模拟器窗口，后面跑React Native项目时就不会两个大程序抢内存。

4. 环境变量和环境联通性检查

环境变量是纯小白最容易懵的地方，但它本质很简单：就是给命令行留了一组“快捷方式”，告诉系统去哪里找adb、emulator这些可执行文件。如果你现在不配，后面在终端敲adb devices就永远只会得到“不是内部或外部命令”。

4.1 ANDROID_HOME必须设置

在Windows搜索框里输入“环境变量”回车，打开系统属性里的“高级系统设置” -> “环境变量”。注意看清楚是选“系统变量”，不是“用户变量”，然后按下面的列表新增：

新建系统变量：

• 变量名：ANDROID_HOME
• 变量值：C:\Users\你的用户名\AppData\Local\Android\Sdk（换成你第3节里记住的实际路径）

然后在已有的系统变量 Path 里点“编辑”，新增以下三项：

• %ANDROID_HOME%\platform-tools
• %ANDROID_HOME%\emulator
• %ANDROID_HOME%\cmdline-tools\latest\bin

为什么ANDROID_HOME这个变量很重要？因为React Native的Android构建过程中，Gradle的Android插件会读取这个环境变量来定位SDK的位置。如果你不设置，构建时大概率会看到“SDK location not found”的报错。有些教程还会提到ANDROID_SDK_ROOT，它是老版本的命名，两个都设成同一个值也没问题，不影响。

设置完必须重开所有终端窗口，否则环境变量不会生效。这一步是“下课铃”级别的关键操作，我见过太多人配完了没重开终端，然后怎么验证都不对。

4.2 命令行验证这套链路

新开一个终端，逐一输入以下命令，确认输出正常：

bash复制node -v
npm -v
java -version
echo %JAVA_HOME%
echo %ANDROID_HOME%
adb version
adb devices
emulator -list-avds

重点看adb和emulator。adb version能输出一大段信息说明Platform-Tools可用；adb devices显示设备列表，现在没启动模拟器所以列表是空的也没关系；emulator -list-avds能列出一行你刚才创建的模拟器名字，说明模拟器核心命令也都指向正确了。

如果你在启动模拟器之前就执行 adb devices，有时候会看到 no permissions 或 device unauthorized 的提示，这通常是adb服务异常，执行 adb kill-server 再 adb start-server 重置一下就好。到这里，整条工具链全部打通，可以进入项目创建环节了。

5. 从零到第一个页面：init、Metro和run-android

环境配置最终要落到一个能跑起来的项目上才有意义。我在这个环节经历过太多次“命令卡住不动”、“红屏找不到入口”的情况，所以下面的每一步都写清原理和判定标准。

5.1 用官方脚手架创建项目

在命令行里cd到你准备放代码的工作目录，比如 C:\Projects，然后执行：

bash复制npx @react-native-community/cli@latest init HelloWorld

这里解释一下这条命令背后的动作：npx是Node自带的工具，它会在本次执行时临时拉取 @react-native-community/cli 这个脚手架包，然后init命令会用最新模板生成一个名叫HelloWorld的项目目录，自动装好npm依赖。整个过程的耗时取决于网络，正常情况下三到十分钟不等。

执行过程中如果长时间没有任何输出，最烦人的情况是npm在静默下载。这时候你可以看HelloWorld目录是否在变大，node_modules文件夹是否在生成。如果实在等太久，大概率是registry出了问题，回到第2.3节把npm源切过去再重试。

创建过程的等待期，我有个经验可以分享：先打开Android模拟器让它慢慢启动，因为首次构建时模拟器开机耗的时间跟Gradle构建时间差不多，并行操作能省好几分钟。

5.2 Metro打包器与构建指令

项目生成后，cd进HelloWorld目录（新版本会自动进入），执行：

bash复制npm start

这会启动Metro Bundler，它会占住当前终端窗口，打印出一段QR码和地址：

code复制Metro waiting on exp://...

Metro相当于前端开发里的dev server，只要你不关掉它，它会监听代码变化，实时把最新代码打包给App。这个终端窗口不要关，它在整个开发过程中都要保持运行。

然后新开一个终端，同样cd到HelloWorld目录，执行：

bash复制npm run android

这条命令做的事情相当多：先调用Gradle执行Android构建，生成debug版APK，然后通过adb把这个APK安装到正在运行的模拟器上，最后通知模拟器里的App去连接Metro，把JS bundle加载进来。首次构建会特别慢，因为Gradle除了要编译项目，还要下载对应的Gradle发行版和大量Android依赖仓库，五到二十分钟都是正常的。这一步很多人以为电脑死机了，其实进度都藏在Gradle那一大坨滚动日志里。

构建期间建议时不时看一眼终端，如果长时间卡在某一行，比如停在下载依赖但百分比不动，大概率是网络问题，要么切换镜像源（后面第6节有具体配置），要么就耐心等一等。如果构建失败，直接去找“FAILURE: Build failed with an exception”那一段，别在上面几千行里抓狂。

5.3 看到默认页面之后怎么验证

构建成功且模拟器亮起后，你会看到React Native的默认页面，背景是深色，中间有个“Welcome to React Native”标题，下方是一些操作说明。这个页面一出现，说明环境配置算是正式跑通了。

接下来的验证我认为更有意义：用VS Code之类的编辑器打开HelloWorld目录，找到App.tsx文件，把中间的文本改成你自己的内容，比如改成“我的第一个App”，保存后你会看到模拟器里的界面几乎在保存的瞬间就会刷新。这就是Fast Refresh热更新的效果，也是React Native开发体验里最爽的一个环节。

顺便把项目目录结构给纯小白解释一下，省得你看半天不知道哪里写代码：

• App.tsx：应用的根组件，前端代码的主要入口
• index.js：注册App组件到React Native的入口文件
• android/：Android原生工程目录，Gradle构建的核心
• ios/：iOS工程目录，这个在Windows上暂时用不到
• package.json：依赖和脚本管理文件

后续日常开发里，最常用的命令其实就是 npm start 开Metro，然后 npm run android 构建运行。你也可以直接npm run start和npm run android分开开两个终端，日常习惯完全看个人。

6. 纯小白最容易踩的坑与排查指南

这一节我整理的是帮别人排查时遇到频率最高的几个问题，前四个几乎占了所有求助的八成，强烈建议你收藏留档。

6.1 Gradle构建巨慢或直接失败

症状就是 npm run android 卡在下载Gradle依赖的地方大半天不动，或者报了“Could not resolve”之类的下载错误。原因很简单：gradle仓库、Gradle发行版的默认下载地址在国内访问速度不稳。解决方案是给项目配置国内镜像仓库源。

打开 android/build.gradle，在allprojects的repositories节点里，把原来的google()、mavenCentral()替换或补充为国内镜像。一个常用的参考配置长这样：

groovy复制buildscript {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        google()
        mavenCentral()
    }
}

allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/google' }
        google()
        mavenCentral()
    }
}

另外，android/gradle/wrapper/gradle-wrapper.properties里的distributionUrl也可以换成国内镜像的地址，镜像域名写的是腾讯云的Gradle镜像，路径跟原地址保持一致即可。这个操作属于常规的下载源替换，很多老手都是这样配的。配完之后，重新执行npm run android，构建速度会直观地快很多。

6.2 报错“SDK location not found”

这算是React Native Android的环境经典报错之一，出现的原因是Gradle找不到你SDK的安装路径。你已经设置过ANDROID_HOME的话一般不会遇到，但如果你换过Android Studio的SDK目录，或者用的是便携式SDK，就会踩到这个坑。

最直接的解决办法：在 android/ 目录下新建一个 local.properties 文件，写入：

properties复制sdk.dir=C\:\\Users\\你的用户名\\AppData\\Local\\Android\\Sdk

注意Windows下路径里的反斜杠要用转义符，也就是写成双反斜杠 \，或者直接用正斜杠 C:/Users/xxx/AppData/Local/Android/Sdk 也可以。保存后重新构建，错误就消失了。

6.3 模拟器红屏/白屏，显示“Unable to load script”

运行后App界面看起来像是代码完全没加载，这在React Native里最常见的原因是Metro没有运行，或者Metro运行的端口和App请求的端口不一致。你先确认一下第5.2节里那个 npm start 的窗口是不是还开着，没问题的话再看一下App加载的地址。

比较常见的场景是我先跑了npm run android，又手动关掉了Metro窗口，然后模拟器里的App再按R键刷新就找不到脚本源了。解决方法是重新开终端执行npm start，等Metro输出“Connected”日志后，再回到模拟器里按R键或者在App界面点击Reload按钮（真机上是双指点击屏幕）。如果端口被其他程序占用，可以在启动Metro时用：

bash复制npm start -- --port 8082

同时 npm run android 也要带上对应的端口参数保持一致，整个链路才能对上。

6.4 adb devices里看不到设备

装了模拟器，但 adb devices 的输出列表是空的，这是连接层出问题了。先确认设备管理器里模拟器显示的状态是Running，然后执行 adb kill-server 和 adb start-server 重置adb服务，再执行 adb devices 看是否出现 emulator-5554 之类的结果。

如果是真机调试没识别到，依次检查三件事：手机开发者选项里的USB调试是否打开、USB连接模式是不是“文件传输（MTP）”、数据线是否支持数据传输。最后一步是回到Android Studio的SDK Manager，把Platform-Tools更新到最新版。这属于设备连接的常规排查，跟手把手的通用流程一致。

6.5 JDK版本跟Gradle/SDK冲突

构建日志里出现“Unsupported class file major version 65”或者“Could not determine java version from '21'”之类的话，不用怀疑，就是JDK版本不对。React Native在版本说明里明确推荐JDK 17，Gradle的当前版本也正好适配17。安装路径里如果有多个JDK，用JAVA_HOME把执行入口锁定到17即可，把其他JDK临时从Path里移除也可以，但改JAVA_HOME是最标准的做法。

我个人排查这套问题时的习惯是：所有环境类报错，第一反应永远是看执行命令时实际选中的版本，而不是看你装了哪个版本。一个终端窗口都可能因为加载顺序问题选中了不同的JDK实例，所以务必在项目终端里用 java -version 确认一遍再用。

7. 装机几遍之后总结的一点心得

配置React Native环境的整个过程说穿了不复杂，但确实把系统级依赖、编辑器工具链、移动开发SDK三套体系绑在了一起，任何一个环节出问题都会异常难排查。我帮同事配置过太多次以后，最大的体会就是：别急着一次跑通，一步一步验证，每一步都确保输出正常再进下一步。Node验证完再装JDK，JDK验证完再装Android Studio，最后再初始化项目，这样即使出错，你也知道错在哪一段。

还有个小建议，初始化好的模拟器镜像别经常删，它占的磁盘空间虽然不小，但重下一次系统镜像的时间成本更贵。如果你打算长期做React Native，顺手把npm和Gradle的缓存目录管理一下，别让C盘悄悄爆掉，后面你会感谢自己。