React Native搭建环境全面讲解：Windows全流程

从零开始在 Windows 上搭建 React Native 开发环境：一次讲透所有坑点

你是不是也曾在搜索“react native搭建环境”时，被各种过时教程、零碎步骤和莫名其妙的报错劝退？明明照着文档一步步来，结果gradlew卡死、python not found、Metro 启动失败……最后只能放弃，转投 Expo 的怀抱？

别急。今天我们就用一篇完整、真实、可落地的文章，带你把整个流程走通。不跳步、不省略，每一个环节都告诉你“为什么必须这么做”，而不是只扔给你一堆命令。

我们聚焦Windows 平台下的原生 CLI 搭建方式——虽然比 Expo 复杂一些，但它让你真正掌控项目底层，是进阶开发、集成原生模块、接入第三方 SDK 的必经之路。

为什么 React Native 在 Windows 上曾让人头疼？

React Native 最初由 Facebook 为 iOS 和 Android 双平台设计，早期开发体验主要围绕 macOS 展开。而 Windows 用户要构建 Android 应用，就必须依赖一套完整的 Java 工具链 + Android SDK + 构建脚本支持。

这意味着你在 Windows 上跑一个.js文件，背后其实调用了：
- Node.js 运行 JS 打包服务
- Python 执行某些旧版构建逻辑
- JDK 编译原生代码
- Gradle 调度整个构建流程
- ADB 安装 APK 到设备

任何一个环节出问题，都会导致“初始化项目成功，但 run-android 报错”。

所以，“react native搭建环境”的本质，其实是协调多个异构系统组件协同工作的过程。

下面我们从最基础的开始，一环扣一环地配置。

第一步：安装 Node.js —— 整个生态的地基

React Native 是基于 JavaScript 的框架，而 JavaScript 要运行在非浏览器环境中，就需要Node.js。

它不只是用来执行npx react-native init命令，更是启动 Metro 打包服务器的核心引擎。没有它，连 JS bundle 都打不出来。

✅ 推荐操作

1. 访问 https://nodejs.org
2. 下载LTS 版本（长期支持），目前推荐v18.x 或 v20.x
   - 不要用最新版（如 v21+），部分依赖尚未兼容
3. 安装时选择.msi安装包（Windows Installer）
4. 勾选“Add to PATH”选项，让系统自动配置环境变量

⚠️重要提示：
安装路径不要包含中文或空格！例如不要装在C:\Users\张三\Desktop\nodejs，否则后续 Gradle 构建可能失败。

验证是否安装成功

打开命令提示符（CMD 或 PowerShell），输入：

node -v npm -v

你应该看到类似输出：

v18.17.0 9.6.7

如果提示'node' 不是内部或外部命令，说明环境变量没配好，请重新安装并确保勾选添加到 PATH。

✅热词匹配点：这一步就是“react native搭建环境”的起点，Node.js 是基石中的基石。

第二步：Python 与 JDK 配置 —— 很多人栽在这里

你以为写 JS 就不用管 Java 和 Python？错。

尽管 React Native 主体用 JS 编写，但在构建 Android 工程时，仍然会调用大量由 Python 编写的脚本（尤其是旧版本工具链），以及 Java 编译器来打包 APK。

先说结论：你需要什么？

❗ 为什么必须是 Python 2.7？

因为很多 React Native 内部脚本（比如react-native upgrade或某些 Gradle 插件）仍使用 Python 2 语法编写。虽然社区正在迁移至 JS，但短期内无法完全替代。

如果你装了 Python 3 并命名为python，系统就会调用错误版本，导致报错：

'import' is a reserved keyword (some-script.py, line X)

这是典型的 Python 2/3 语法冲突。

如何安全安装 Python 2.7？

1. 去官网下载： Python 2.7.18
2. 选择Windows x86-64 MSI Installer
3. 安装路径建议设为：C:\Python27
4. 安装完成后手动设置环境变量：
   - 新建系统变量：PYTHON_PATH = C:\Python27
   - 编辑PATH，加入%PYTHON_PATH%

然后验证：

python --version

输出应为：Python 2.7.18

💡 小技巧：你可以保留 Python 3，只要不把它注册为默认python命令即可。可以用py -2来显式调用 Python 2。

再来看 JDK：Java 开发工具包

Android 应用本质上是一个 Java/Kotlin 程序，所以需要 JDK 提供编译器（javac）、打包工具（jarsigner）等。

推荐选择哪个 JDK？

不要再用 Oracle JDK！推荐使用开源发行版：

👉 Eclipse Temurin JDK 11 （原 AdoptOpenJDK）

特点：
- 免费商用
- 社区维护稳定
- 支持 Windows x64

安装步骤

1. 下载安装包（.msi格式）
2. 默认安装即可（路径通常为C:\Program Files\Eclipse Adoptium\jdk-11.x.x-hotspot）
3. 设置环境变量：
   - 新建系统变量：JAVA_HOME = C:\Program Files\Eclipse Adoptium\jdk-11.0.15.10-hotspot（根据实际路径调整）
   - 修改PATH，加入%JAVA_HOME%\bin

验证命令

java -version javac -version

正确输出示例：

openjdk version "11.0.15" 2022-04-19 OpenJDK Runtime Environment Temurin-11.0.15+10 (build 11.0.15+10) OpenJDK 64-Bit Server VM Temurin-11.0.15+10 (build 11.0.15+10, mixed mode) javac 11.0.15

⚠️ 注意事项：
- 如果你电脑上有多个 JDK（如 IDEA 自带的），请确保JAVA_HOME指向的是你手动安装的那个。
- Windows Defender 有时会阻止 Gradle 下载依赖，建议临时关闭防火墙或添加白名单。

✅热词匹配点：“Could not find tools.jar”、“python is not recognized” 这些经典错误，基本都源于这一步配置不当。

第三步：Android Studio 与 SDK 配置 —— 最关键的一环

现在轮到真正的“安卓构建大脑”登场：Android Studio。

即使你不打算用它的 IDE 功能，也需要它提供的SDK、Build Tools、Emulator 和 Gradle Wrapper。

下载与安装

1. 访问 https://developer.android.com/studio
2. 下载 Android Studio（推荐 Bundle 版，含 SDK）
3. 安装时务必勾选以下组件：
   - ☑ Android SDK
   - ☑ Android SDK Platform
   - ☑ Performance (Intel ® HAXM) —— CPU 支持 VT-x 才能启用加速
   - ☑ Android Virtual Device

安装完成后启动一次 Android Studio，进入欢迎界面 → Configure → SDK Manager。

SDK 配置要点

1. 安装目标 API Level

前往SDK Platforms选项卡，至少安装一个较新的 Android 版本，推荐：

• Android 13.0 (API 33)或
• Android 12L (API 32)

📌 注意：React Native 新项目通常要求最低 API 28（Android 9），但建议用新版本避免兼容性问题。

2. 安装构建工具（SDK Tools）

切换到SDK Tools选项卡，勾选：

• ☑ Android SDK Build-Tools
• ☑ Android SDK Platform-Tools（包含 adb）
• ☑ Android SDK Tools (Obsolete) —— 某些老脚本仍依赖此组件
• ☑ NDK（可选，仅用于开发 C++ 原生模块）

点击 Apply 开始下载。

环境变量设置（重中之重！）

这是很多人失败的根本原因：ANDROID_HOME 没配对。

默认 SDK 路径是：

C:\Users\<你的用户名>\AppData\Local\Android\Sdk

你需要设置两个东西：

1. 系统变量

新建：

ANDROID_HOME = C:\Users\YourName\AppData\Local\Android\Sdk

2. 添加到 PATH

将以下路径全部加入系统PATH：

• %ANDROID_HOME%\platform-tools← 包含adb
• %ANDROID_HOME%\tools
• %ANDROID_HOME%\tools\bin
• %ANDROID_HOME%\emulator

保存后重启终端。

验证 ADB 是否正常工作

打开 CMD，运行：

adb devices

如果是首次运行，会提示你授权 USB 调试（连接真机时）。若无设备连接，输出应为：

List of devices attached

表示 ADB 正常启动。

✅热词匹配点：能否顺利执行run-android，完全取决于这一步是否成功。“SDK location not found” 错误几乎全是环境变量惹的祸。

第四步：创建并运行你的第一个 React Native 项目

终于到了激动人心的时刻！

我们使用官方推荐的 CLI 方式初始化项目：

npx react-native init FirstRNApp cd FirstRNApp npx react-native run-android

让我们拆解每一步发生了什么：

1.npx react-native init

• 下载最新模板（含 iOS & Android 工程结构）
• 自动生成android/目录下的 Gradle 配置
• 安装react,react-native等核心依赖

耗时较长，耐心等待。

2.npx react-native run-android

这个命令触发了一系列动作：

1. 检查JAVA_HOME,ANDROID_HOME,python等环境
2. 启动 Metro 打包服务（监听 8081 端口）
3. 调用android/gradlew.bat编译 debug APK
4. 使用adb install安装到已连接设备
5. 启动应用并建立 WebSocket 连接加载 JS bundle

如果一切顺利，你会在模拟器或手机上看到熟悉的欢迎界面：

“Welcome to React Native!”
“You can start editing this app with any text editor…”

恭喜你，react native搭建环境成功了！

常见问题及解决方案（实战经验总结）

❌ 问题1：SDK location not found

原因：ANDROID_HOME环境变量未设置或路径错误。

解决方法：
- 检查变量名是否拼写正确（注意大小写）
- 检查路径是否存在（可用dir %ANDROID_HOME%查看）
- 重启命令行窗口使变量生效

❌ 问题2：Unable to load script from assets index.android.bundle

现象：白屏、红屏报错，提示找不到 JS bundle。

常见原因：
- Metro 服务未启动
- 设备与电脑不在同一网络（真机调试时）
- USB 调试未开启文件传输模式

解决方法：
- 确保 Metro 正在运行（端口 8081）
- 在设备上摇晃唤出开发者菜单 → Reload JS
- 或执行：npx react-native start --reset-cache

❌ 问题3：Gradle 下载极慢甚至超时

国内访问services.gradle.org和jcenter.bintray.com极不稳定。

优化方案：替换为国内镜像源

1. 修改 Gradle 分发地址

编辑文件：android/gradle/wrapper/gradle-wrapper.properties

原内容：

distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip

改为腾讯云镜像：

distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-7.5.1-bin.zip

2. 替换 Maven 仓库源

编辑android/build.gradle，在repositories中优先使用阿里云：

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

保存后执行：

cd android && ./gradlew clean

再重新运行项目，速度提升明显。

实用技巧与最佳实践

✅ 使用 Yarn 提升依赖管理效率

相比 npm，Yarn 安装更快、锁文件更可靠：

npm install -g yarn yarn install

之后可用yarn android替代npx react-native run-android

✅ 清理缓存三连击

当遇到奇怪问题时，试试这套组合拳：

# 重置 Metro 缓存 npx react-native start --reset-cache # 清理 Gradle 构建缓存 cd android && ./gradlew clean # 清除 npm/yarn 缓存（可选） npm cache clean --force # 或 yarn cache clean

✅ 推荐开发工具组合

• 编辑器：VS Code + React Native Tools 插件
• 模拟器：Pixel 4 API 30（x86_64）+ HAXM 加速
• 调试：Chrome DevTools（F12 打开）或 Flipper

总结：你现在拥有了什么？

通过这篇文章，你应该已经完成了一个完整、可工作的 React Native 开发环境，包括：

• ✅ Node.js v18+ 环境
• ✅ Python 2.7 与 JDK 11 正确配置
• ✅ Android SDK 全套组件安装到位
• ✅ 成功运行首个 React Native 项目
• ✅ 掌握常见问题排查思路

更重要的是，你不再只是“按步骤操作”，而是理解了每个组件的作用：

下一步你可以做什么？

• 学习使用useState,View,Text,Image构建 UI
• 尝试接入摄像头、GPS 等原生功能
• 集成第三方库如react-navigation、axios
• 探索如何打包 release 版 APK

而这一切的基础，都始于你刚刚亲手搭建的这个环境。

如果你在过程中遇到了其他问题，欢迎留言交流。毕竟，每个成功的开发者，都是从一次次“环境配不通”中走出来的。

Keep coding.