齐齐哈尔市网站建设_网站建设公司_需求分析

从零开始搭建 React Native 开发环境：Android 篇实战全指南

你有没有经历过这样的场景？
兴致勃勃想用 React Native 写个 App，结果刚敲下npx react-native init，命令行就报出一连串红字错误：“SDK not found”、“Gradle sync failed”、“Could not start daemon”……折腾半天，项目没跑起来，心态先崩了。

别急，这太常见了。React Native 的开发环境配置，尤其是 Android 部分，是绝大多数新手的第一道“劝退关”。它不像纯前端那样开箱即用，而是横跨 JavaScript、Java、Android 原生工具链的复杂系统工程。

今天我们就来一次讲透——如何在 Windows 或 macOS 上，从零搭建一个稳定可用的 React Native 开发环境，重点攻克Android Studio 设置、SDK 路径、JDK 版本兼容性、环境变量配置等高频痛点，让你少走弯路，直接上车开发。

为什么 React Native 环境这么“难搞”？

React Native 并不是运行在 WebView 里的混合应用框架，它的核心理念是“用 JS 写代码，生成原生 UI”。这意味着：

你的 JavaScript 代码通过Metro 打包器编译
最终要交给 Android 的 Java/Kotlin 层去渲染真正的 Button、ScrollView
构建过程依赖完整的 Android 工具链：JDK、SDK、ADB、Gradle

所以，哪怕你只是写一行console.log()，背后也可能触发整个 Android 编译流程。任何一个环节断了，都会导致启动失败。

换句话说：你不仅是个前端开发者，还得懂点 Android 构建体系。

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

没有 Node.js，一切免谈。React Native CLI 和 Metro 都基于它运行。

✅推荐版本：使用LTS（长期支持）版本，目前建议选v18.x 或 v20.x。不要追求最新版，稳定性更重要。

你可以从 https://nodejs.org 下载安装包，或者用版本管理工具如nvm（macOS/Linux 推荐）或nvm-windows。

安装完成后，打开终端验证：

node -v npm -v

输出类似：

v18.17.0 9.6.7

✅ 只要能看到版本号，并且 Node ≥ 16，就没问题。

第二步：搞定 JDK —— 别让 Gradle 在半路翻车

很多人忽略这一点：Gradle 是跑在 JVM 上的，而 Android 项目的 Java/Kotlin 代码也需要编译。因此，必须安装合适的 JDK。

⚠️关键提示：
从 React Native 0.72 开始，官方推荐并默认使用JDK 17。
但注意！不能使用 JDK 18+，因为 Gradle 对高版本 JDK 支持还不完善，会导致构建失败。

推荐选择：OpenJDK 17（原 AdoptOpenJDK）

官网下载地址： https://adoptium.net/
选择 Temurin JDK 17，对应你的操作系统和架构（x64 / ARM64）。

安装后设置JAVA_HOME环境变量，并加入 PATH。

Windows 示例（PowerShell）：

setx JAVA_HOME "C:\Program Files\Eclipse Adoptium\jdk-17.0.8.7-hotspot" setx PATH "%PATH%;%JAVA_HOME%\bin"

macOS/Linux 示例（~/.zshrc）：

export JAVA_HOME=/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home export PATH=$PATH:$JAVA_HOME/bin

💡 修改.zshrc后记得执行source ~/.zshrc使配置生效。

最后验证：

java -version javac -version

你应该看到输出中包含17.0.8这样的字样，说明 JDK 安装成功。

第三步：Android Studio 全家桶 —— 核心中的核心

这是整个流程中最容易出错的部分。很多人以为装了 Android Studio 就万事大吉，其实远远不够。

1. 下载与安装

前往官网下载： https://developer.android.com/studio
安装时选择“Custom”模式，确保勾选以下组件：

☑ Android SDK
☑ Android SDK Platform
☑ Performance (Intel x86 HAXM) —— Intel 用户必装
☑ Android Virtual Device
☑ Android SDK Build-Tools

Apple Silicon（M1/M2）芯片用户无需 HAXM，但需确认模拟器支持 ARM 镜像。

2. 启动向导完成后进入 SDK Manager

路径：Configure → SDK Manager

必须安装的 SDK Platforms：

至少安装一个 Android 版本作为目标 API，推荐：
-Android 13.0 (API Level 33)
- 或 Android 12.0 (API 31)

📌 React Native 当前最低要求为 API 23（Android 6.0），但为了兼容性和功能完整性，建议使用较新版本。

必须安装的 SDK Tools：

在 “SDK Tools” 标签页中，勾选：
- ☑ Android SDK Build-Tools（最新稳定版，如 34.0.0）
- ☑ Android SDK Platform-Tools（含 adb）
- ☑ Android Emulator
- ☑ Android SDK Tools（旧版工具）
- ☑ Intel x86 Emulator Accelerator (HAXM installer)

点击 Apply 安装，耐心等待下载完成。

第四步：环境变量配置 —— 让命令行“认得清路”

即使你装了所有组件，如果命令行找不到它们，依然会报错。比如最常见的：

Error: Could not find SDK path, please set ANDROID_HOME

这是因为 React Native CLI 需要知道 Android SDK 在哪。

正确做法：设置`ANDROID_HOME`和`PATH`

Windows（CMD/PowerShell）：

setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk" setx ANDROID_SDK_ROOT "%LOCALAPPDATA%\Android\Sdk" setx PATH "%PATH%;%ANDROID_HOME%\platform-tools;%ANDROID_HOME%\tools;%ANDROID_HOME%\tools\bin"

macOS/Linux（~/.zshrc）：

export ANDROID_HOME=$HOME/Android/Sdk export ANDROID_SDK_ROOT=$ANDROID_HOME export PATH=$PATH:$ANDROID_HOME/platform-tools export PATH=$PATH:$ANDROID_HOME/tools export PATH=$PATH:$ANDROID_HOME/tools/bin

✅platform-tools包含adb，tools/bin包含sdkmanager，这两个一定要加进 PATH。

修改后重启终端或执行source ~/.zshrc，然后测试是否能识别 adb：

adb --version

如果输出版本信息，说明配置成功。

第五步：创建你的第一个 React Native 项目

现在终于可以动手了！

首先全局安装 React Native CLI（虽然npx可以临时拉取，但本地装一份更稳）：

npm install -g @react-native-community/cli

然后初始化项目：

# 创建普通项目 npx react-native init MyAwesomeApp # 使用 TypeScript 模板（推荐） npx react-native init MyAwesomeApp --template typescript

这个过程可能需要几分钟，因为它要：
- 下载模板
- 安装 npm 依赖
- 初始化 iOS 和 Android 原生工程

⚠️ 如果中途报错Cannot download template, 很可能是网络问题，稍后再试，或考虑换源。

进入项目目录：

cd MyAwesomeApp

第六步：连接设备 & 启动应用

有两种方式运行 App：

方式一：连接真机调试（推荐初学者）

用 USB 数据线连接手机
在手机上启用“开发者选项”和“USB 调试”
终端输入：
bash npx react-native run-android

第一次会自动安装 App 并启动 Metro 打包服务。之后每次修改 JS 文件，保存即可热重载。

方式二：使用 Android 模拟器

打开 Android Studio → AVD Manager
创建一个新的虚拟设备（推荐 Pixel 5, Android 13, AOSP with Google APIs）
启动模拟器
在项目根目录运行：
bash npx react-native run-android

💡 模拟器首次启动较慢，后续会快很多。M1 Mac 用户请选择 ARM64 镜像以获得更好性能。

国内开发者必看：加速构建的几个技巧

由于 Google 服务器访问受限，国内开发者经常会遇到：

Gradle 下载极慢
Maven 仓库超时
插件无法同步

解决办法很简单：换镜像源。

1. 更换 Gradle 分发地址（可选）

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

将原来的：

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

替换为腾讯云镜像：

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

2. 更换 Maven 仓库（强烈建议）

编辑：android/build.gradle

在allprojects -> repositories中添加阿里云镜像：

allprojects { repositories { maven { url 'https://maven.aliyun.com/repository/google' } maven { url 'https://maven.aliyun.com/repository/jcenter' } mavenCentral() google() // 可保留，但前面优先级更高 } }

这样 Gradle 会优先从国内源拉取依赖，速度提升显著。

常见问题排查清单

错误现象	可能原因	解决方案
`SDK location not found`	`ANDROID_HOME`未设置	检查环境变量，确认路径正确
`Unable to launch emulator`	HAXM 未安装 / BIOS 关闭 VT-x	安装 HAXM，进入 BIOS 开启虚拟化
`Gradle project sync failed`	网络问题或仓库不可达	换镜像源，或检查防火墙
`Building and installing the app on the device (cd android && ./gradlew installDebug)`卡住	JDK 版本过高	降级到 JDK 17
`error Failed to install the app.`+`Could not find com.android.tools.build:gradle:x.x.x`	Gradle 插件版本不匹配	检查`android/build.gradle`中 classpath

🔍 小技巧：遇到问题先看日志最后一行，通常会有明确线索。也可以尝试cd android && ./gradlew clean清理缓存再重试。

最佳实践建议

统一团队环境版本
在项目中使用.nvmrc、package.json锁定 Node 版本，文档注明 JDK 和 RN 版本，避免“在我电脑上能跑”。
预留足够磁盘空间
Android SDK + 模拟器镜像轻松突破 10GB，建议 SSD 存储。
权限问题别忽视
确保当前用户对~/Android/Sdk有读写权限，否则sdkmanager无法更新组件。
自动化脚本提效
新同事入职重复配环境？写个.sh或.ps1脚本一键部署吧。

结语：环境搭好了，接下来才是开始

看到这里，你应该已经成功运行起第一个 React Native 项目了。也许过程中踩了些坑，但现在回头看，你会发现这套工具链的设计逻辑其实很清晰：

Node.js负责 JS 层打包
JDK + Gradle负责 Android 构建
Android SDK提供底层 API 和调试能力
CLI 工具把这些串联成一条流畅的工作流

掌握这套环境配置，不只是为了跑通 demo，更是理解 React Native 如何桥接 Web 与原生世界的关键一步。

下一步，就可以深入学习组件通信、原生模块集成、性能优化等高级主题了。

如果你在搭建过程中遇到了其他棘手问题，欢迎留言交流，我们一起解决。毕竟，每一个成功的 App，都是从一次顺利的run-android开始的。

齐齐哈尔市网站建设_网站建设公司_需求分析_seo优化

从零开始搭建 React Native 开发环境：Android 篇实战全指南

为什么 React Native 环境这么“难搞”？

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

第二步：搞定 JDK —— 别让 Gradle 在半路翻车

推荐选择：OpenJDK 17（原 AdoptOpenJDK）

Windows 示例（PowerShell）：

macOS/Linux 示例（~/.zshrc）：

第三步：Android Studio 全家桶 —— 核心中的核心

1. 下载与安装

2. 启动向导完成后进入 SDK Manager

必须安装的 SDK Platforms：

必须安装的 SDK Tools：

第四步：环境变量配置 —— 让命令行“认得清路”

正确做法：设置`ANDROID_HOME`和`PATH`

Windows（CMD/PowerShell）：

macOS/Linux（~/.zshrc）：

第五步：创建你的第一个 React Native 项目

第六步：连接设备 & 启动应用

方式一：连接真机调试（推荐初学者）

方式二：使用 Android 模拟器

国内开发者必看：加速构建的几个技巧

1. 更换 Gradle 分发地址（可选）

2. 更换 Maven 仓库（强烈建议）

常见问题排查清单

最佳实践建议

结语：环境搭好了，接下来才是开始

热门文章

文章分类

标签云

需要专业的网站建设服务？

齐齐哈尔市网站建设_网站建设公司_需求分析_seo优化

从零开始搭建 React Native 开发环境：Android 篇实战全指南

为什么 React Native 环境这么“难搞”？

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

第二步：搞定 JDK —— 别让 Gradle 在半路翻车

推荐选择：OpenJDK 17（原 AdoptOpenJDK）

Windows 示例（PowerShell）：

macOS/Linux 示例（~/.zshrc）：

第三步：Android Studio 全家桶 —— 核心中的核心

1. 下载与安装

2. 启动向导完成后进入 SDK Manager

必须安装的 SDK Platforms：

必须安装的 SDK Tools：

第四步：环境变量配置 —— 让命令行“认得清路”

正确做法：设置ANDROID_HOME和PATH

Windows（CMD/PowerShell）：

macOS/Linux（~/.zshrc）：

第五步：创建你的第一个 React Native 项目

第六步：连接设备 & 启动应用

方式一：连接真机调试（推荐初学者）

方式二：使用 Android 模拟器

国内开发者必看：加速构建的几个技巧

1. 更换 Gradle 分发地址（可选）

2. 更换 Maven 仓库（强烈建议）

常见问题排查清单

最佳实践建议

结语：环境搭好了，接下来才是开始

热门文章

文章分类

标签云

相关文章

如何在5分钟内构建浏览器内代码演示环境：Playground终极指南

Python离线地理编码终极指南：快速逆向地址解析实战

如何快速掌握RadeonTop：AMD GPU监控的完整指南

需要专业的网站建设服务？

正确做法：设置`ANDROID_HOME`和`PATH`