每次有人问我“配置ReactNative环境难吗”我第一反应都是难的不是某个工具安装而是它们总在互相打架。ReactNative 环境配置牵扯到 Node.js、JDK、Android SDK、Gradle 好几套工具链任何一个环节版本对不上都会在创建第一个程序时给你点颜色看看。这篇文章不打算复制官方文档我会按自己亲手搭建、也帮别人补救过无数次环境的经验把从零配置到第一个 App 落地的完整过程讲清楚。无论你是从 Web 前端转过来的同学还是刚接触移动开发的新手跟着这个流程走下去大概率能在半小时左右让代码跑到模拟器上。1. 环境配置的整体思路与版本选择1.1 React Native 环境究竟需要有哪几块很多新手容易把 ReactNative 当成一个“框架装完就行”但实际上它是 JS 与原生代码的桥梁。你写的 JS/TS 代码要由 Node.js 配合 Metro 打包器负责转译和提供调试服务最终编译成 Android 安装包时又绕不开 JDK、Android SDK、Gradle 这一套 Java 生态工具。如果做 iOS 开发还必须有 Xcode不过绝大多数配置教程都以 Android 为主线因为 Windows 也能完成我也以 Android 为主来讲。你可以把整套环境想象成开一家店Node.js 是后厨的菜刀和炉灶负责把食材切好炒熟JDK 是厨师资格证书缺了它厨房根本不让你开火Android SDK 是食材供应商给你提供 Android 系统独有组件Gradle 则是店里的传菜机器人把各个菜按顺序送到前台。哪个环节掉链子你的“第一个程序”就端不上来。理解这个关系后续看报错时会冷静不少。实际配置时还有个容易忽视的点React Native 项目里藏着两套代码一套是你自己写的 JS一套是官方模板生成的原生壳。原生壳每次构建都需要 Android SDK 和 Gradle 参与所以就算你只想写一个“Hello World”也必须把整个原生工具链准备好省不了。1.2 版本选型别看到新版本就往上冲装环境最忌讳的是一股脑全装最新。官方文档一般会给“最低要求”和“推荐版本”但组件间有微妙的兼容性。以我常用的组合为例组件推荐版本说明Node.js18 LTS 或 20 LTS不要用太老的版本也不要追奇数版JDK17React Native 0.70 之后对 JDK 版本要求逐步提高Android Studio最新稳定版自带 SDK Manager省心Android SDK对应平台的稳定版即可建议安装 API 34 或 35 的系统镜像Gradle跟模板保持一致项目里的 wrapper 已锁版本别手动升级npm/yarnnpm 10 或 yarn 1.22二选一不要混用有个非常重要的原则优先使用 React Native 官方模板锁定的 Gradle 和 Android Gradle Plugin 版本。很多人手动升级 Gradle结果构建直接崩了。原因是 RN 在发布时会针对特定 AGP 版本做测试你单独升某个组件等于打破了一套已经调好的组合拳。写代码嘛稳定压倒一切。如果你手头已经有别的项目最好先查一下它们需要的 Node 版本。我在工作中会同时维护三四个 RN 项目有的老项目必须用 Node 16这时候建议用 nodenv 或 nvm-windows 做版本切换而不是反复卸载重装。不过第一次上手阶段直接装一个满足要求的新 LTS 就够用了。1.3 不同操作系统下的路径差异Windows、macOS、Linux 的环境配置大同小异真正的差异集中在环境变量和 SDK 默认路径上。Windows 上Android SDK 默认安装到C:\Users\你的用户名\AppData\Local\Android\SdkmacOS 上通常放在~/Library/Android/sdkLinux 则常有自定义路径。环境变量这块Windows 要走“系统属性 → 环境变量”macOS 或 Linux 要改~/.zshrc或~/.bashrc改完还要source一下才能生效。新手最容易在“明明配了环境变量新终端却不认”这件事上栽跟头。这是因为终端进程是在环境变量修改前启动的已经缓存的旧配置不会自动刷新关掉终端重新开一个就正常了。另外硬盘空间要留足Android Studio、SDK 系统镜像、Gradle 缓存加起来轻松超过 10GB。如果 C 盘紧张可以在安装时指定别的盘符并把 SDK 路径一并改过去。我不建议在路径里带中文或空格有些原生工具链对这类路径处理很不好后续会莫名报一些诡异错误。2. 动手安装底层依赖2.1 Node.js 安装与 npm 镜像配置Node.js 的安装最没技术含量但有细节。官网下载 LTS 版安装包Windows 用户记得安装时勾选“Add to PATH”macOS 用户下载 pkg 后一路下一步即可。装完打开终端输入node -v和npm -v看到版本号说明成功了。如果提示“不是内部或外部命令”大概率是 PATH 没配好。Windows 下可以手动把 Node 安装目录加到系统 PATH比如C:\Program Files\nodejs\。这里提醒一句有些安装器会同时帮你装一个老版本 npm如果发现npm -v和 Node 版本差距过大可以执行npm install -g npmlatest升级到新的 npm。国内网络环境下建议先把 npm 镜像切到国内源。我不太喜欢用那种全量替换注册表的方式但这一步确实能显著提升依赖下载速度。命令行敲这两句npm config set registry https://registry.npmmirror.com npm config get registry执行后如果看到https://registry.npmmirror.com说明镜像源配置成功。后面初始化 RN 项目时几十个依赖包瞬间就能拉完不然卡在进度条上会非常难受。用 yarn 也一样可以执行yarn config set registry https://registry.npmmirror.com来设置。2.2 JDK 安装与环境变量配置RN 对 JDK 版本有硬性要求。我用的是 OpenJDK 17你可以去 Adoptium 官网下载 Temurin 17也可以直接用 Android Studio 内置的 JBR但那样容易把环境搞乱还是单独装一份最靠谱。安装完成后需要设置JAVA_HOME环境变量并把它加到 PATH。Windows 用户在系统环境变量里新建JAVA_HOME值填 JDK 安装目录比如C:\Program Files\Eclipse Adoptium\jdk-17.0.xx。然后再编辑 Path新增%JAVA_HOME%\bin。macOS 上则在~/.zshrc里写入export JAVA_HOME$(/usr/libexec/java_home -v 17) export PATH$JAVA_HOME/bin:$PATH配置完重新开终端执行java -version看到版本 17 就说明成功。大部分人喜欢在 Android Studio 里点一点但只改项目设置是不够的命令行工具和 Gradle 很难直接继承 IDE 里的配置所以系统级环境变量才是更稳妥的方案。这个细节和git安装及配置教程里反复强调“配置 global 和 local 用户信息要分清”是同一个道理一个管系统一个管项目各司其职才不出乱子。2.3 Android Studio 与 Android SDK 准备Android Studio 是新手的“定海神针”也是我见过的环境配置里最耗时的一环。去官网下载最新稳定版安装时建议选择 Standard 安装它会帮你把 Android SDK、Platform-Tools、模拟器管理工具全部拉齐。如果空间有限也可以自定义组件但至少要保证有 Android SDK Platform-Tools。装好后第一件事是打开 SDK Manager确认这几个组件已经安装Android SDK Platform 对应你目标系统版本Android SDK Build-ToolsAndroid SDK Platform-Tools包含 adbIntel HAXM 或 Windows Hypervisor Platform模拟器加速SDK 下载同样可能遇到网络慢的问题可以在 Android Studio 的 HTTP Proxy 设置里配置国内镜像也可以用命令行工具sdkmanager来安装指定包。很多人问我要不要装所有 API Level真不用占空间又容易把工具链弄乱装单个稳定版本就够了。接下来配置ANDROID_HOME环境变量。Windows 用户新建系统变量ANDROID_HOME值指向 SDK 路径比如C:\Users\用户名\AppData\Local\Android\Sdk。再往 PATH 里加上两个路径%ANDROID_HOME%\platform-tools和%ANDROID_HOME%\emulator这样命令行里才能直接用adb和emulator命令。macOS 则是在 shell 配置文件里加export ANDROID_HOME$HOME/Library/Android/sdk export PATH$PATH:$ANDROID_HOME/platform-tools2.4 Git 安装与基础配置Git 不是跑 React Native 的必要条件但项目从创建开始就应该纳入版本管理所以我还是建议顺手装上。Windows 用户下载 Git for Windows安装时一路默认即可唯一注意的是在“调整 PATH 环境”这一步选择“从命令行使用 Git”否则以后在 cmd 和 PowerShell 里可能调不到git命令。装好后配置两行个人身份信息这是提交代码的基础git config --global user.name 你的名字 git config --global user.email 你的邮箱很多初学者容易忽略后续从 GitHub 拉旧项目时 SSH 密钥的问题。配置git本身不难真正麻烦的是密钥认证。如果你准备长期搞开发建议提前生成 SSH Key 并添加到代码托管平台避免每个项目都输一次用户名密码。3. 初始化第一个 React Native 项目3.1 使用 CLI 模板创建项目按要求装完底层依赖后终于到了令人愉悦的部分。打开终端进入你想放代码的目录执行npx react-native-community/clilatest init FirstApp这里用npx而不是全局安装 CLI能保证每次都用最新官方模板也避免全局命令版本过老影响项目。项目名建议用驼峰命名比如FirstApp、ShopApp不要包含中文、连字符或数字开头否则 Android 包名和目录名都会出现奇怪问题。执行后 CLI 会开始拉取模板、安装 npm 依赖第一次可能要等几分钟控制台会打印一些“Installing dependencies”的日志。这个过程千万别去反复 CtrlC依赖安装没完成的话项目结构会是残缺的后面怎么修都别扭。如果初始化过程中卡在“installing pods”这样的字样并且你不是在 macOS 上做 iOS 开发可以直接忽略或等它超时。CLI 默认会在 macOS 上尝试安装 CocoaPodsWindows 上不存在这一步。初始化结束后进入项目目录看看文件列表你会见到一个结构清晰的 RN 项目。3.2 读懂生成出来的项目目录FirstApp/ ├── android/ # Android 原生工程 ├── ios/ # iOS 原生工程 ├── node_modules/ # npm 依赖 ├── App.tsx # 主界面组件 ├── index.js # JS 入口文件 ├── package.json # 项目依赖声明 ├── metro.config.js # Metro 打包配置 └── tsconfig.json # TypeScript 配置新手最容易盯着android文件夹发呆不知道里面到底是什么。简单说android/app/src/main/java/com/firstapp/MainActivity.kt就是原生入口Android 系统启动 App 时先加载这个 Activity再由它加载 JS bundle。android/app/build.gradle里可以改 applicationId 和版本号平时这类原生文件基本不该碰除非你要调整图标或包名。package.json则是整个项目的中枢里面记录了react-native和react的版本号还有 npm scripts。我在多台电脑之间切换时只要新旧机器的 Node 和 JDK 版本一致执行npm install就能完全复现环境。这种“依赖锁版本”的思路和配置 Java/Python 环境时强调“版本一致性”是相通的热词里那些maven环境配置、hbase安装与配置之所以难一大半坏在版本失控上。3.3 让第一个程序在模拟器上跑起来启动模拟器这一步值得单独讲讲。打开 Android Studio找到 Device Manager 面板点击 Create Device选择一个手机型号模板我习惯用 Pixel 系列分辨率统一性能也好。然后选择系统镜像比如 API 34点击 Download 下载完成后按 Next 完成创建。首次启动模拟器会比较慢以后会快很多。模拟器起来后在项目根目录执行npm run android这个命令做了两件事启动 Metro 打包服务同时用 Gradle 构建原生 Android 应用。如果一切顺利控制台上会看到BUILD SUCCESSFUL随后模拟器自动安装并打开你的 App屏幕中央出现一行默认文字。第一次构建最费时间Gradle 要下载依赖要编译五到十分钟都很正常。期间如果卡在某个百分比半天不动十有八九是网络问题下文会讲怎么处理。当应用成功跑起来后你可以去App.tsx里把默认文本改成自己写的“你好React Native”按一下 R 键模拟器内重新加载界面就会更新。这大概就是“环境配置成功”的最好证明。4. 常见问题与排查实录4.1 Metro 服务端口占用和缓存异常Metro 默认监听 8081 端口。如果之前有项目没关干净端口被占用启动时会报Error: listen EADDRINUSE。这种情况不要重启电脑找到占用者杀掉即可。Windows 下执行netstat -ano | findstr :8081 taskkill /F /PID 这里填进程号macOS 下用lsof -i :8081找 PID再kill -9 进程号。如果端口没被占但页面一直加载不出来多半是 Metro 缓存出问题可以执行npx react-native start --reset-cache重启服务。我几乎每次切换分支后都会做一次缓存清理这套动作能解决一大批“明明代码改了却没反应”的玄学问题。4.2 Gradle 下载慢和构建失败Gradle 是另一个网络重灾区。首次构建时 Gradle wrapper 要下载Android 依赖要从 Google 和 Maven Central 拉取国内网络慢是常态。解决办法分两步。第一步修改android/gradle/wrapper/gradle-wrapper.properties里的distributionUrl。如果官方地址太慢可以换成腾讯云镜像distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-8.10.2-bin.zip第二步在android/build.gradle文件的 allprojects repositories 中添加国内镜像allprojects { repositories { maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/public } maven { url https://maven.aliyun.com/repository/gradle-plugin } google() mavenCentral() } }改完后重新执行npm run android。我也使用过把整个 Gradle 用户目录从 C 盘迁到别的盘的做法具体是在系统变量里新增GRADLE_USER_HOME这样可以避免C:\Users\xxx\.gradle越来越大。热词里那些pytorch环境搭建、ubuntu搭建qt开发环境之类的问题核心也多是镜像源和依赖缓存RN 这边只是换了个工具名而已。4.3 SDK 未找到和设备连接问题如果构建时出现SDK location not found说明 Gradle 找不到 Android SDK。最简单的修法是在android/目录下手动创建local.properties写入sdk.dirC\:\\Users\\你的用户名\\AppData\\Local\\Android\\Sdk注意路径里的反斜杠要转义。这个文件一般会被.gitignore忽略所以从仓库 clone 下来的项目不会带着它每次换机器或换账号都必须重新生成。如果你始终找不到 SDK 路径Android Studio 打开过项目后会在右下角提示安装缺失组件按提示操作也行。真机调试时先在手机里开启“开发者选项”和“USB 调试”插上电脑后执行adb devices能看到一串设备 ID 且带device后缀才算连上。连接成功后USB 模式下的 Metro 访问还需要一条反向路由执行adb reverse tcp:8081 tcp:8081然后再npm run android。我见过不少人模拟器里跑得好好的一换真机就白屏多半就是漏了这一步。4.4 高频环境变量问题速查报错信息原因解决思路node 不是内部或外部命令Node 未装或 PATH 未配检查 Node 安装目录是否在 PATH 中ERROR: JAVA_HOME is not setJDK 环境变量缺失新建 JAVA_HOME 并指向 JDK 17SDK location not foundANDROID_HOME 或 local.properties 缺失手动创建 local.properties 文件Gradle sync failed依赖拉不下来检查仓库镜像和 gradle-wrapper 地址Unable to load scriptMetro 没启动或端口不通启动 Metro确认 8081 端口和 adb reverseCommand failed: adbPlatform-Tools 损坏用 SDK Manager 重装 platform-tools这条速查表我基本每次指导别人都发一遍。记住一个原则遇到报错先读前 30 行不要只看最后一行。很多时候真正的原因在上面的日志里最后一行只是结果。5. 从环境配置走向日常开发的经验5.1 固定好一套组合拳少折腾配置完环境不是终点后续还要长期维护。对我来说最省心的方法是尽量保持 Node、JDK、Android SDK、Gradle 的版本组合在一个“已知可用区间”内。比如团队项目里确定 Node 用 18 LTS、JDK 用 17、Android 系统镜像用 API 34那就所有人统一别某个人悄悄升了 Node 20 引发潜在问题。如果你要同时维护多个项目可以考虑在项目根目录添加一个.nvmrc文件内容写18这样进入目录时 nvm 或 nodenv 能自动切换 Node 版本。虽然多一步配置但非常值得。这与ubuntu 24.04 lts配置教程等环境类教程里“先定基线再干活”的思路一样环境乱套往往是因为基线不清晰。5.2 把日志英文当线索别硬碰硬最后分享一个我实际带人时总强调的观点报错不是在找茬而是在提供线索。React Native 环境配置的坑绝大多数是另一批人早就踩过的常见坑。比如Could not find or load main class多半是 JDK 版本不对SDK map platform components missing多半是 SDK 组件没装齐。把这些关键词复制到搜索引擎或官方 issue 区答案几乎立刻出来。我见过太多人卡住后第一反应是“把环境卸了重装”其实治标不治本。我更推荐的做法是在报错现场多停一会儿把日志前十行认真读一遍再对照上面这张速查表去定位。环境这东西一次配好之后很少再出大问题真正频繁出问题的反而是那些没耐心看日志、反复重装的人。第一次搭建多花十分钟理清工具链关系后面开发就能把时间全部花在写业务上这才是这件事最划算的地方。