这两天后台接连有人问“React Native环境到底怎么配”“为什么我照别人的教程折腾了三天还是红屏”。我干脆把从零开始配置React Native环境到跑起第一个App的完整过程重新捋了一遍。这篇文章不谈复杂理论只讲落地操作装什么、先后顺序怎么定、哪些坑能绕开全部按我实际跑通的方式写。适合刚入坑的移动端新手也适合从Web转过来的前端同事照着抄作业。我见过太多人死在最后一步Node装了、Android Studio也装了却在执行构建时被Gradle、SDK路径、端口冲突轮番折腾。React Native环境配置最怕的不是单个工具装不上而是各组件版本互相不认账。Node.js、JDK、Android SDK、模拟器、Gradle任何一环版本口径不一致都会在构建阶段集中爆发。下面这份配置过程我会把版本选择、安装顺序和每个踩过的坑都交代清楚。1. 环境配置的整体思路先统一版本口径1.1 为什么React Native环境配置总在最后一步翻车React Native的运行链路比普通前端项目长很多。你的JavaScript代码要先由Metro打包再经原生壳加载到Android或iOS应用中调试模式下原生应用还要回头连Metro服务。这意味着整个环境至少跨越三套体系Node生态、Java生态、Android SDK生态。任何一个体系的位置变了、版本不对了另外两个都会找不到入口。绝大多数教程默认你“已经有了基础环境”但现实里每个人的电脑底子完全不同。有的人装过JDK 8有的人用Homebrew装过OpenJDK 20有的Windows机器甚至同时存在三个Java版本。我在帮朋友排查时发现最常见的报错根本不是代码问题而是系统PATH里旧版本工具抢了新版本的位置。所以配置环境的第一原则永远不是“装最新”而是“让所有工具在同一个版本口径下工作”。1.2 先定版本再谈安装React Native每代版本都会绑定一组最低要求。我写这篇文章时以0.73及以上版本为基准对应的基础版本大概是这样组件推荐版本备注Node.js18 LTS或20 LTS必须16实测20.11.1最稳JDK170.73版本起官方推荐不建议直接上21Android Studio最新稳定版至少要能装SDK Platform 35Android SDKAPI 35对应Android 15Android Build-Tools34.0.0及以上默认勾选最新版即可模拟器系统镜像API 35 Google APIs x86_64根据电脑架构选x86_64或ARM64为什么强调先定版本因为后面所有配置项都跟着这份表格走。比如Gradle会在初始化项目时自动下载配套的distribution版本如果你全局装了不兼容的Java版本Gradle启动阶段就会直接报错。JDK 17这个位置尤其关键Gradle 8.x对Java 17支持完善但如果你用JDK 21部分老版本AGP插件会直接拒绝运行。与其到时候改配置不如一开始就守住这张表。1.3 推荐的安装顺序我推荐的顺序是Node.js → JDK → Android Studio → SDK与模拟器 → 创建项目。这个顺序背后的逻辑是依赖方向Metro依赖NodeGradle依赖JDKAndroid构建链依赖SDK。你不需要同时打开三个安装器硬灌每装完一个就检验一次能尽早暴露问题。反例是很多人先装Android Studio再去补Node和JDK。结果Android Studio自带的JRE版本不对等到项目初始化时才发现Gradle无法执行又要回头卸。按依赖顺序装每一步的验证都是清晰单一的。2. 基础工具安装Node.js、JDK与Watchman2.1 Node.js装完记得改registryReact Native的脚手架、Metro打包器全部跑在Node.js上这是整个环境的执行引擎。Windows用户直接到nodejs.org下载LTS版本安装包安装时务必勾选“Add to PATH”否则后面每一次命令都会提示“node不是内部或外部命令”。macOS用户建议直接用Homebrew安装brew install node20安装完后用node -v确认版本号。Node装好只算第一步国内网络环境下顺手改一下npm镜像源能省不少事。我在初始化RN项目时经常看到依赖下载卡在某个包上然后整体进度一直转圈。执行下面这条命令npm config set registry https://registry.npmmirror.com改完后再跑npm config get registry确认生效。这个操作不会影响项目运行只影响依赖包下载速度。另外提醒一句不要用太旧的Node版本我在0.72时期遇到过Node 14初始化项目后Metro启动直接崩溃的情况升到Node 18就好了。2.2 JDK 17JAVA_HOME到底怎么配JDK是Android构建链的地基没有它Gradle跑不起来。Windows用户建议安装Temurin或OpenJDK 17的Windows安装包安装时它会自动配置大部分环境变量但为了保险还是要手动检查一遍系统环境变量里的JAVA_HOME。设置JAVA_HOME时有两个高频坑。第一个是路径写错我记得有一次把JAVA_HOME指到了C:\Program Files\Java\jdk-17.0.12\bin这是错的JAVA_HOME要指到JDK安装根目录也就是能看到bin、lib、conf这一层。第二个坑是PATH里同时存在多个Java入口尤其是Windows会默认加上C:\Program Files\Common Files\Oracle\Java\javapath里面可能链到旧版。如果java -version和你装的不一致去PATH里把这类无关入口删掉。macOS用户用brew install openjdk17安装后Homebrew会提示JDK没有被自动链接到系统路径。你需要手动把下面这段加到~/.zshrcexport JAVA_HOME/opt/homebrew/opt/openjdk17 export PATH$JAVA_HOME/bin:$PATH配置完重新打开终端执行java -version看到“openjdk version 17.x”就算过关。关于JDK版本我建议直接忽略21甚至更高版本RN的构建生态对JDK版本非常保守装最稳的17能避免一大堆无关报错。2.3 WatchmanmacOS上建议装Windows可省Watchman是Meta开源的文件监听工具用于监控RN项目文件变化并触发Metro重新打包。macOS上我强烈建议装因为系统默认的文件监听句柄上限很低项目稍微大一点就会出现“too many open files”之类的崩溃。执行brew install watchman装完重启终端即可。Windows上RN官方文档已经不把Watchman作为Windows环境的必需项我用Windows跑RN项目时从来不装WatchmanMetro的文件监听走Node原生机制也够用。很多新手看到教程里装了Windows版Watchman也跟着装结果配置路径时反而多了一堆坑。没有特殊需求Windows用户可以直接跳过这一节。3. Android开发环境的搭建Android Studio、SDK与模拟器3.1 Android Studio安装与首次启动Android Studio是Android SDK的地基它不仅是IDE还负责管理SDK组件和模拟器。到官方网站下载安装包Windows用户安装时建议勾选“Android SDK”和“Android Virtual Device”这两个组件省得后面需要时还要去SDK Manager里补装。首次启动Android Studio会引导你下载SDK组件。这一步是网络状况的分水岭如果你的网络状态一般可能会看到进度条几十分钟纹丝不动。我的经验是不要盯着进度条干等先去把后面要装的SDK Platform和System Image在SDK Manager里勾选好让它在后台一起下载这样能节省一轮等待时间。极少数情况下某个组件下载失败点Retry基本能续上实在卡住可以考虑换一个网络环境再试比如手机热点实测对卡滞问题有奇效。如果你在命令行里执行react-native run-android报找不到SDK但Android Studio明明能正常打开那大概率是环境变量没指到SDK目录而不是SDK没装好不用重装。3.2 SDK组件到底勾哪些Android Studio安装好后进入设置里的SDK Manager按这个清单勾选Android SDK Platform 35对应Android 15RN 0.73及以上编译目标。Android SDK Build-Tools 34.0.0或更高用于编译原生代码。Android SDK Platform-Tools包含adb真机调试和安装APK都靠它。Android Emulator跑模拟器的核心组件。Android SDK Command-line Tools部分构建工具和脚本需要。一个System Image建议选android-35 Google APIs x86_64稍后创建虚拟设备要用。有些教程会让你把大量旧版本Platform全部装一遍完全没必要。RN项目只会用它自己声明的那一个API Level其他全是白占磁盘。我也见过只勾Platform不勾System Image的人创建模拟器时发现没有镜像可用那才是真正的时间杀手。3.3 ANDROID_HOME与PATH配置SDK装完后Android Studio会在固定位置生成SDK目录。Windows默认在C:\Users\你的用户名\AppData\Local\Android\SdkmacOS默认在~/Library/Android/sdk。手动新建系统环境变量ANDROID_HOME值填写这个目录。注意还有一个变量叫ANDROID_SDK_ROOT部分工具和脚本会把两者混淆。稳妥的做法是两个变量都配上值一样。接下来把platform-tools和emulator目录加入PATH# Windows PATH追加 %ANDROID_HOME%\platform-tools %ANDROID_HOME%\emulator # macOS ~/.zshrc export PATH$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator配置完成后新开终端执行adb --version能正常输出版本号就说明adb可用。这个验证非常关键因为很多后续报错比如“Unable to load script”到最后都是adb没配好导致的。我能理解大家装完Android Studio后懒得再配环境变量的心情但如果跳过这一步命令行工具根本感知不到SDK存在。3.4 创建模拟器AVD的关键参数模拟器是开发阶段最常用的运行目标。在Android Studio的Device Manager里点击创建设备设备型号随便选我一般选Pixel系列内存2GB对调试足够了。之后的系统镜像选择才是关键Windows/Intel机器选x86_64镜像Apple Silicon机器选arm64-v8a镜像千万别选错架构选错之后模拟器要么启动极慢要么直接黑屏。创建好后先试启动一次完成系统冷启动然后再回到命令行跑RN。这里有个容易踩的坑模拟器第一次启动时因为要加载系统镜像耗时可能几十秒到几分钟很多人以为卡死了又启动一遍结果出现多个并行模拟器进程。你只需要等引导画面出来确认能进入桌面再关掉重来或者直接用起来都行。Windows用户还得多看一眼“性能”设置里的虚拟化是否开启。如果任务管理器显示“虚拟化: 已禁用”模拟器会以极慢的纯软件模式运行这时候你需要进BIOS开启Intel VT-x或AMD-V。这一步跟RN代码本身没关系但环境配不好后面每次跑模拟器都是煎熬。4. 创建并运行第一个React Native项目4.1 用CLI初始化的正确姿势环境就位后创建项目就很简单了。打开终端进入你想存放项目的目录执行npx react-native-community/cli init FirstApp这个命令会拉取最新模板并自动执行依赖安装。FirstApp是项目名只能包含字母和数字不要用中文也不能带下划线。如果你本机有多个Node版本或者npm源配置不干净初始化过程中卡在依赖阶段多半是网络问题重试一次基本能过。还有一个细节是初始化完成后进入项目目录先跑一次npm start看看Metro能否正常启动。如果能看到Metro横幅和端口号就说明Node侧完全正常然后再开另一个终端执行npm run android。一上来就直接run-android会让你分不清Metro的问题还是构建的问题这是我自己踩过的最烦人的迷局。4.2 连接模拟器或真机先把目标确定好运行npm run android之前请确保至少有一个可用目标要么模拟器已经开机要么真机已经通过USB连上并开启了开发者选项。同时存在多个目标时adb有可能选中错误的设备导致安装完成后迟迟看不到应用启动。如果你用的是模拟器在模拟器里看到安装好的App图标就算成功一半。如果用的是真机Android 5.0以上需要先在设置里连续点击“版本号”开启开发者模式再到“开发者选项”里打开“USB调试”。连接后手机上弹出授权窗口记得点允许否则adb会一直显示unauthorized。在跑正式构建之前还可以用一条指令确认设备状态adb devices能看到设备序列号和device状态即可。这里的坑在于很多新手以为插上数据线就能用其实Windows上如果没装手机厂商的USB驱动adb根本发现不了设备。遇到这种问题先在Android Studio里用SDK Manager安装一次Google USB Driver再重插数据线。4.3 Metro、Gradle与首次启动的配合npm run android这条命令背后干了两件大事Gradle构建原生安装包然后通过adb安装启动。首次构建要拉取Gradle发行版和一大堆Maven依赖在冷环境下耗时从几分钟到二十分钟不等这期间终端会滚大量下载日志。很多人看到“Downloading gradle-8.x-bin.zip”就以为挂了其实只是慢观察下载进度条变化就行。App启动后会向Metro请求JS Bundle。如果Metro窗口显示“Bundling completed”并且模拟器上出现了初始页面恭喜你第一个React Native程序跑起来了。这时候你可以去改App.tsx里的文字保存后几秒钟模拟器界面会自动刷新整个过程就是React Native开发最核心的体验。如果Metro窗口完全没动静但App已经在模拟器上启动了极大概率是adb反向端口没通。最直接的方式是在项目执行adb reverse tcp:8081 tcp:8081这样模拟器可以稳定连到电脑上的Metro服务。若还是不行就看下一节的排查表。5. 常见问题与排查实录5.1 Metro端口冲突Metro默认跑在8081端口如果被其他进程占用了启动时会直接报Error: listen EADDRINUSE :8081。最常见的情况是上一次开发结束后Metro没关干净或者某个软件占用了8081。Windows下执行netstat -ano | findstr 8081找到占用进程的PID后在任务管理器里结束对应进程或者干脆换一个端口npm start -- --port 8082macOS用lsof -i :8081和kill -9 PID处理。这个问题我在连续工作一周后遇到过最后发现是自己开着一个旧的Metro窗口一直没关。遇到端口问题先别慌确定目标进程再动手。5.2 Gradle下载卡住或构建失败换库、换distributionUrlGradle构建卡住是国内用户最常见的烦恼。RN项目通过android/gradle/wrapper/gradle-wrapper.properties指定Gradle发行版地址如果官方地址下载不动可以手动把distributionUrl换成国内镜像地址或者用浏览器下载对应的zip包放到~/.gradle/wrapper/dists目录的缓存路径下。依赖解析失败时优先检查android/build.gradle里的仓库配置把阿里云Maven镜像仓库加在前面可以显著降低依赖拉取失败率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() }加完镜像后重新执行npm run android。注意改Gradle文件前最好备份原文件并且只在构建失败时再动这些配置不要想当然地提前加。5.3 SDK路径错误或platform-tools找不到如果构建时提示SDK location not found首先要确认SDK目录真实存在。Android Studio默认目录只适用于本机默认用户名如果项目换过路径或SDK被移到了其他盘就需要在android/local.properties里手动指定sdk.dirC\:\\Users\\你的用户名\\AppData\\Local\\Android\\Sdk注意Windows下路径里的反斜杠要转义。另一个常见情况是adb命令不被识别运行adb devices也会报command not found。返回去检查PATH里是否包含%ANDROID_HOME%\platform-tools然后重启终端再试。这类问题最浪费时间的点在于你改环境变量后忘了重开终端于是每次都以为没改生效。5.4 报错速查表我整理了平时工作里出现频率最高的几类报错和应对方案可以直接对照着处理现象常见原因处理方式模拟器启动后没有画面虚拟化未开启或镜像架构错误检查BIOS开启VT-x确认x86_64/arm64镜像与CPU匹配App停在白屏Metro未启动或8081被占确认npm start窗口正常执行adb reverseDevice unauthorized真机USB调试授权未确认重插USB并点击允许调试授权Gradle build很慢依赖未缓存、网络问题手动下载Gradle zip或配置Maven镜像JAVA_HOME is invalid环境变量路径错误或多版本冲突检查JAVA_HOME指向JDK根目录清理PATH旧入口File name too longWindows路径长度限制git config --global core.longpaths trueINSTALL_FAILED_INSUFFICIENT_STORAGE模拟器磁盘空间不足在AVD设置中增大内部存储或清理模拟器数据这些报错大多不是React Native代码本身的问题而是环境配置的延伸。遇到报错时养成分步排查的习惯先看Metro是否正常再用adb确认设备状态最后看Gradle日志。每一步都能用终端命令或日志定位比盲目重装节省几小时。5.5 真机调试的几个细节真机调试比模拟器多几道坎。USB连接时要注意Android 10以上的系统会默认使用“仅充电”模式需要下拉通知栏切到“使用USB传输文件”或类似选项否则adb可能识别不到。无线调试则要求电脑和手机处于同一局域网手机能通过IP访问电脑的8081端口后再用adb connect连接。实际开发中我最推荐的还是先用模拟器跑通再切真机因为模拟器省去驱动、授权、网络三层变量环境排障更纯粹。真机环境留着在需要测试真机相机、性能时再启用分工更清楚。6. 实操总结与后续建议这套流程我前后跑过不下十次最深的体会是环境配置是一场版本管理游戏不是安装游戏。每个组件能装起来都简单难的是让它们形成一条顺畅的依赖链。我建议新手在一开始就把版本对照表保存下来每装完一个工具就执行一次对应的验证命令发现问题立即回到上一步排查绝不往下走。Node装完跑node -vJDK装完跑java -versionSDK配完跑adb --version这一套下来能拦住绝大多数稀奇古怪的报错。最后再分享一个小技巧把第一次跑通的App.tsx备份起来。以后你想尝试新架构、升级RN版本、调整工程结构时随时拿一个已知能运行的版本做对照能帮你排除很多“代码看起来没错但就是起不来”的隐性环境问题。React Native的环境配置没有太多魔法保持耐心、拆着排查、多确认版本口径你很快就能看到自己的第一个App稳稳地运行在屏幕上。