云南省网站建设_网站建设公司_UX设计_seo优化

从零开始：在 Windows 上高效搭建 React Native 开发环境

你是不是也经历过这样的场景？
兴致勃勃想用 React Native 写个跨平台 App，打开命令行敲下npx react-native init MyAwesomeApp，结果卡在依赖安装、SDK 路径报错、模拟器起不来……折腾一整天，项目还没跑起来。

别担心，这几乎是每个新手都会踩的坑。尤其在 Windows 系统上，路径空格、环境变量、JDK 版本、端口冲突等问题层出不穷。但只要理清逻辑、按步骤来，React Native 的环境搭建其实并不可怕。

本文不是简单罗列“下载这个、安装那个”的操作清单，而是带你理解每一环的作用和背后的原理，让你不仅能配好环境，还能在出问题时快速定位、精准修复。

为什么是 Node.js？它到底干了什么？

React Native 是基于 JavaScript 的框架，而 JavaScript 原本只能运行在浏览器里。为了让它能在电脑上执行脚本（比如创建项目、启动打包服务），我们需要一个独立的 JS 运行时 —— 这就是Node.js的作用。

更进一步地说，当你运行：

npx react-native init MyApp

系统其实在做这些事：
- 启动 Node.js 引擎
- 通过npx找到@react-native-community/cli工具包
- 下载模板项目结构
- 自动运行npm install安装所有依赖
- 配置 Android 和 iOS 的原生工程文件

所以，Node.js 是整个 React Native 开发链的起点。没有它，连项目都建不了。

✅ 推荐配置

⚠️ 注意：某些第三方渠道打包的 Node 可能缺失组件或修改默认行为，建议始终使用官网版本。

🔍 验证是否成功

node --version npm --version

输出类似：

v20.12.0 10.5.0

说明 Node 和 npm 已正确安装。

JDK 不再是“随便装一个就行”——必须是 JDK 17+

很多老教程还在教你装 JDK 8，但在React Native 0.73+ 中，这是行不通的。

因为新版 React Native 使用的 Gradle 构建系统（7.5+）要求 Java 17 作为运行环境。如果你强行用 JDK 8，会遇到如下错误：

Could not determine java version from '1.8.0_301'.

或者 Gradle 编译失败、类加载异常等诡异问题。

所以你需要的是什么？

• OpenJDK 17 或更高版本
• 推荐使用 Eclipse Temurin 提供的构建版（原 AdoptOpenJDK）
• 安装后务必设置JAVA_HOME环境变量

如何检查？

java -version javac -version echo %JAVA_HOME%

理想输出：

openjdk version "17.0.10" 2024-01-16 OpenJDK Runtime Environment (build 17.0.10+7) OpenJDK 64-Bit Server VM (build 17.0.10+7, mixed mode) javac 17.0.10 C:\Program Files\Java\jdk-17.0.10

💡 小贴士：路径中不要有空格或中文！例如C:\Program Files (x86)\...容易导致构建工具解析失败。可以考虑安装到C:\Dev\jdk-17这样的简洁路径。

Android Studio：不只是 IDE，更是工具链中枢

很多人误以为只有写原生代码才需要 Android Studio，其实不然。

即使你只写 JavaScript，React Native 在构建 Android 应用时仍然重度依赖 Android SDK 中的一系列命令行工具：

这些都在Android SDK里，而最方便获取它们的方式就是安装Android Studio。

安装要点

1. 下载 Android Studio
2. 安装时勾选：
   - ✔️ Android SDK
   - ✔️ Android SDK Platform-Tools
   - ✔️ Android SDK Build-Tools
   - ✔️ Android Emulator
3. 创建一个 AVD（Android Virtual Device）用于测试

环境变量不能少

进入系统属性 → 高级 → 环境变量，添加以下内容：

然后验证：

adb version

应能看到版本信息，表示 ADB 正常工作。

🛠️ 提示：如果不想每次手动维护路径，可以在 Android Studio 的 Settings → Appearance & Behavior → System Settings → Android SDK 中复制实际路径。

初始化项目：别急着 run-android，先看懂流程

当你终于装好了前面所有依赖，就可以尝试初始化项目了：

npx react-native init MyFirstApp --template typescript cd MyFirstApp npx react-native run-android

但这几条命令背后发生了什么？

分步拆解

1. npx react-native init
   - 下载 React Native CLI 最新版本（无需全局安装）
   - 创建项目目录结构
   - 自动生成android/和ios/原生模块（即使你在 Windows 上也不能编译 iOS）

2. 依赖安装
   - 自动运行npm install
   - 如果网络慢，可能卡很久 —— 可换淘宝镜像加速：
   bash npm config set registry https://registry.npmmirror.com

3. run-android实际做了什么？
   - 启动 Metro bundler（默认端口 8081）
   - 调用 Gradle 构建 APK
   - 使用adb安装到已连接设备或模拟器
   - 加载 JS bundle 并显示应用界面

常见坑点与实战解决方案

❌ 问题 1：SDK location not found

报错信息：

Build failed: Could not determine the dependencies of task ':app:compileDebugJavaWithJavac'. > SDK location not found. Define location with an ANDROID_SDK_ROOT environment variable or by setting the sdk.dir path in your project's local.properties file.

原因分析：Gradle 找不到 Android SDK 路径。

解决方法：

编辑项目根目录下的android/local.properties文件，添加：

sdk.dir=C\:\\Users\\YourName\\AppData\\Local\\Android\\Sdk

注意：反斜杠要转义成双反斜杠，且路径不能带引号。

❌ 问题 2：Unable to load script from assets

现象：App 启动白屏，提示无法加载 JS bundle。

根本原因：开发模式下，JS 代码应该由 Metro 动态提供；但如果 Metro 没启动，或首次构建时没生成 assets，就会回退到读取本地 bundle，而该文件不存在。

修复步骤：

1. 手动生成 bundle 文件：

mkdir android/app/src/main/assets npx react-native bundle --platform android \ --dev false \ --entry-file index.js \ --bundle-output android/app/src/main/assets/index.android.bundle

2. 重新构建：

npx react-native run-android

✅ 建议：此命令仅用于首次修复。正常开发中应保持 Metro 运行，无需手动打 bundle。

❌ 问题 3：端口 8081 被占用

错误提示：

Error: Port 8081 is already in use.

谁占用了 8081？
- IIS（Windows 自带 Web 服务）
- Skype
- Docker
- 其他 Node 服务

解决方案一：终止占用进程

netstat -ano | findstr :8081 taskkill /PID <进程ID> /F

解决方案二：更换 Metro 端口

npx react-native start --port=8082 # 新开终端 npx react-native run-android --port=8082

手机端摇一摇调出开发者菜单 → “Dev Settings” → “Bundle URL”
输入：http://<你的PC局域网IP>:8082/index.bundle?platform=android

💡 查看 PC IP：ipconfig→ 找 IPv4 地址（如192.168.1.100）

开发效率提升技巧

1. 使用 SSD + 启用 Gradle Daemon

Gradle 构建非常吃磁盘 IO。使用 SSD 可显著缩短首次构建时间（从 10 分钟降到 3~5 分钟）。同时确保gradle.properties中启用了守护进程：

org.gradle.daemon=true org.gradle.parallel=true

2. 避免中文/空格路径

不要把项目放在D:\学习资料\我的项目\react native demo这种路径下！

推荐统一使用英文路径，如：

C:\Dev\MyApp

否则容易触发各种工具链解析错误。

3. 快速重置缓存（当一切都不对时）

# 清除 Metro 缓存 npx react-native start --reset-cache # 删除 node_modules 和重建 rm -rf node_modules && npm install # Android 端清理构建 cd android && ./gradlew clean && cd ..

架构视角：React Native 在 Windows 上是如何跑起来的？

我们来看一张简化的系统架构图：

[你的 Windows 电脑] ├── Node.js → 运行 CLI 和 Metro ├── JDK 17 → 支撑 Gradle 构建 └── Android SDK → 提供 adb、emulator、build-tools ↓ [React Native 项目] ↓ Metro Bundler (8081) ↓ [Android 设备/模拟器] ←─── adb 连接 ───→

关键流程如下：

1. Metro 将index.js编译成 JS Bundle
2. Gradle 将原生代码编译成 APK
3. adb install把 APK 安装到设备
4. App 启动时通过 WiFi 或 USB 请求http://<PC_IP>:8081/index.bundle
5. Metro 返回最新 JS 代码，实现热更新

这也是为什么你改一行 JS，保存就能刷新 —— 因为真正的“编译”发生在你的开发机上，设备只是动态加载资源。

给团队的建议：标准化环境配置

如果你是技术负责人或团队新人导师，强烈建议将以下内容整理成一份内部文档：

# React Native 开发环境配置指南（Windows） ## 必备软件 - Node.js v20.x LTS - OpenJDK 17（Temurin） - Android Studio + SDK API 33+ - Git Bash（可选，兼容性更好） ## 环境变量 | 变量名 | 值 | |------------------|----| | JAVA_HOME | C:\Dev\jdk-17 | | ANDROID_SDK_ROOT | C:\Users\%USERNAME%\AppData\Local\Android\Sdk | ## 推荐命令别名（添加到 .bashrc） alias rn-start='npx react-native start --port=8082' alias rn-run='npx react-native run-android --port=8082'

这样新人入职一天内就能跑通第一个 App，极大降低上手成本。

写在最后：环境只是开始

React Native 的环境配置看似繁琐，但它本质上是在帮你建立对跨平台机制的理解：

• 你知道了 JS 是如何与原生层通信的
• 明白了构建流程为何依赖 Java 和 Android 工具链
• 学会了如何排查底层工具的问题

这些经验在未来面对 Hermes 引擎、TurboModules、Fabric 渲染器等新特性时，都会成为你的底气。

而且好消息是：随着 React Native 向New Architecture演进，社区也在推动自动化配置（如自动链接、预设模板），未来环境搭建会越来越简单。

但现在，请先稳扎稳打地走完这一程。当你看到手机屏幕上弹出 “Welcome to React” 的那一刻，所有的等待都是值得的。

如果你在配置过程中遇到了其他棘手问题，欢迎留言讨论，我们一起排雷。