从零搭建 React Native 到项目运行全记录（0.73.6 稳定版）
作为一名开发者，我最近在搭建 React Native 项目时遇到了不少坑，从环境配置到依赖冲突，再到 Gradle 下载超时等问题，耗费了大量时间。为了方便日后换电脑或工作环境时快速复用，特意整理这篇从零到一的搭建教程，包含所有关键配置和避坑指南
一、环境准备
1. 安装必要工具
首先确保你的电脑上安装了以下工具：
- Node.js：v18.0.0 或更高版本（推荐使用 nvm 管理 Node 版本）
- 下载地址：https://nodejs.org/
- 验证：node -v 和 npm -v 能正常输出版本号
- Yarn：替代 npm 的包管理工具
npm install -g yarn
- JDK 17：React-Native推荐使用Java Development Kit [JDK] 17
- 下载 JDK 17
推荐使用 Oracle JDK 或 Amazon Corretto（免费开源，兼容性更好），这里以 Amazon Corretto 为例：
下载地址：https://aws.amazon.com/corretto/downloads/?version=17
选择对应系统版本：Windows 系统选择「Windows x64 Installer」（.msi 格式，自动配置环境变量）
补充：我下载的是.exe文件，相关环境配置在安装JDK17后边展示
-
安装 JDK 17
- 双击下载的 .msi 安装包，点击「Next」；
- 勾选「I accept the terms in the License Agreement」，点击「Next」；
- [关键步骤：勾选「Set JAVA_HOME variable」（自动配置环境变量，避免手动操作），其他保持默认，点击「Next」；
- 点击「Install」，等待安装完成，最后点击「Finish」。
手动配置JDK 17示例（系统变量）：
JAVA_HOME配置：
Path配置（位置必须移到最上边，首先加载）：
CLASSPATH配置：.;%JAVA_HOME%\lib;%JAVA_HOME%\lib\tools.jar(注意别少了点 .)
- 验证 JDK 安装与环境变量
- 打开新的 CMD 终端（注意：安装后需重启终端，环境变量才生效）；
- 执行以下命令验证：
# 查看 Java 版本（需显示 17.x.x）
java -version# 查看 JAVA_HOME 环境变量（需显示 JDK 安装路径，如 C:\Program Files\Amazon Corretto\jdk17.x.x_xx）
echo %JAVA_HOME%
- 若输出类似以下内容，说明 JDK 配置成功：
openjdk version "17.0.9" 2023-10-17
OpenJDK Runtime Environment Corretto-17.0.9.9.1 (build 17.0.9+9-LTS)
OpenJDK 64-Bit Server VM Corretto-17.0.9.9.1 (build 17.0.9+9-LTS, mixed mode, sharing)
- Git：版本控制工具
下载地址：https://git-scm.com/
2. 安装 Android 开发环境
2.1 下载并安装 Android Studio
- 下载地址：https://developer.android.com/studio
- 安装时确保勾选以下组件：
- Android SDK
- Android SDK Platform
- Android Virtual Device
2.2 配置 Android SDK
- 打开 Android Studio，进入 File > Settings > Appearance & Behavior > System Settings > Android SDK
- 在 SDK Platforms 标签页：
- 勾选 Android 13 (Tiramisu)（对应 API 33）
- 勾选 Show Package Details，确保勾选了：
- Android SDK Platform 33
- Intel x86 Atom_64 System Image（用于模拟器）
SDK Platforms ——> Android 13 (Tiramisu)
Intel x86 Atom_64 System Image(Android 13 (Tiramisu)目录老下边)
-
在 SDK Tools 标签页：
- 勾选 Show Package Details
- 找到 Android SDK Build-Tools，勾选 33.0.0 版本
- 找到 NDK (Side by side)，勾选 25.1.8937393 版本
- 找到 Android SDK Command-line Tools，勾选最新版本
Android SDK Build-Tools
NDK(现在使用的是25.1.8937393)
Android SDK Command-line Tools(这里用的不是最新版本)
另外还选择了CMake，Gradle构建的时候会涉及 C++ 代码
- 点击 Apply 安装所选组件
2.3 配置环境变量
2.3.1 新建系统变量 ANDROID_HOME，值为 SDK 安装路径（默认是 C:\Users\你的用户名\AppData\Local\Android\Sdk）
另外还配置了ANDROID_SDK_HOME，模拟器环境
2.3.2 在系统变量 Path 中添加：
- [ ] %ANDROID_HOME%\platform-tools
- [ ] %ANDROID_HOME%\emulator
- [ ] %ANDROID_HOME%\tools
- [ ] %ANDROID_HOME%\tools\bin
相关配置图
另外还配置了Sdk Platform-tools
2.3.3 验证开发环境
运行 React Native 提供的环境检查工具：
npx react-native doctor
确保所有检查项都显示为绿色对勾，如有问题按照提示修复。
二、创建 React Native 项目
1. 新建项目
使用指定版本创建项目（经过验证的稳定版本组合）：
# 进入工作目录
cd E:/react-native-test/react-native# 创建项目（指定 0.73.6 版本）
npx react-native@0.73.6 init AwesomeProject --version 0.73.6# 进入项目目录
cd AwesomeProject
2. 安装指定版本依赖
# 安装 Gradle 插件
yarn add @react-native/gradle-plugin@0.73.5# 安装安全区域组件
yarn add react-native-safe-area-context@4.8.2# 确保 React 版本正确（0.73.x 必须搭配 18.2.0）
yarn add react@18.2.0 --force
安装完成后，package.json 中的依赖应如下：
"dependencies": {"@react-native/gradle-plugin": "^0.73.5","react": "18.2.0","react-native": "0.73.6","react-native-safe-area-context": "4.8.2"
}
三、配置 Android 项目
1. 修改 android/build.gradle
这个文件控制项目的构建配置和依赖仓库，使用国内镜像加速下载：
buildscript {ext {buildToolsVersion = "33.0.0"minSdkVersion = 21compileSdkVersion = 33targetSdkVersion = 33ndkVersion = "25.1.8937393"kotlinVersion = "1.8.22"}repositories {google()maven { url "https://maven.aliyun.com/repository/google" }maven { url "https://maven.aliyun.com/repository/maven-central" }mavenCentral()}dependencies {classpath("com.android.tools.build:gradle")classpath("com.facebook.react:react-native-gradle-plugin")classpath("org.jetbrains.kotlin:kotlin-gradle-plugin")}
}
allprojects {repositories {maven { url "$rootDir/../node_modules/react-native/android" }maven { url "https://maven.aliyun.com/repository/google" }maven { url "https://maven.aliyun.com/repository/maven-central" }google()mavenCentral()maven { url "https://www.jitpack.io" }}
}
apply plugin: "com.facebook.react.rootproject"2. 修改 android/settings.gradle
配置依赖仓库和项目结构：
pluginManagement {repositories {gradlePluginPortal()google()mavenCentral()maven { url "https://maven.aliyun.com/repository/google" }}
}dependencyResolutionManagement {repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)repositories {google()mavenCentral()maven { url "https://maven.aliyun.com/repository/google" }maven { url "https://maven.aliyun.com/repository/maven-central" }maven { url "$rootDir/../node_modules/react-native/android" }maven { url "https://www.jitpack.io" }}
}
apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle");
applyNativeModulesSettingsGradle(settings)rootProject.name = 'AwesomeProject'
include ':app'
includeBuild('../node_modules/@react-native/gradle-plugin')3. 配置 Gradle 版本
修改 android/gradle/wrapper/gradle-wrapper.properties：
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-all.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists
四、解决 Gradle 下载问题
这是搭建过程中最容易出问题的环节，推荐手动下载 Gradle 包：
1. 手动下载 Gradle，大概200M左右，小于180M就是下载失败
- 官方地址：https://services.gradle.org/distributions/gradle-8.3-all.zip
- 国内镜像：https://mirrors.aliyun.com/gradle/distributions/gradle-8.3-all.zip（推荐）
2. 放置到指定目录
- 找到 Gradle 缓存目录：C:\Users\你的用户名.gradle\wrapper\dists\gradle-8.3-all
- 目录下会有一个随机字符串命名的子目录（如 a5gdekw7up59x6at40l00u7s2）
- 将下载的 gradle-8.3-all.zip 复制到这个随机字符串目录下（不要解压）
3. 验证 Gradle 配置
# 进入 android 目录
cd android# 测试 Gradle 是否能正常工作
gradlew clean
如果成功，会显示 BUILD SUCCESSFUL 信息，且不会重新下载 Gradle
五、配置模拟器
1. 创建模拟器
- 打开 Android Studio，点击工具栏的 AVD Manager 图标（手机形状）
- 点击 Create Virtual Device
- 选择一个设备（如 Pixel 6），点击 Next
- 选择 Tiramisu API 33 系统镜像，点击 Next
- 保持默认配置，点击 Finish 创建模拟器
这个是已经创建好的
未创建想要创建的界面，选择对应Device，如：Pixel6，点击Next
选择Tiramisu API 33，点击Next
保持默认配置，点击finsish
2. 启动模拟器在 AVD Manager 中，点击创建好的模拟器右侧的播放按钮启动模拟器，等待模拟器完全启动（显示安卓桌面）。
六、运行项目
1. 启动 Metro 服务(例如在AwesomeProject项目下)
Metro 服务启动成功后，会显示 Metro waiting on port 8081
# 在项目根目录执行，不是在Android目录中，如果在Android，需要cd..退出
yarn start --reset-cache
这里Metro 服务启动成功了
2. 安装并运行应用
打开新的终端窗口，执行：
# 安装并运行到模拟器
yarn react-native run-android
首次运行会进行编译，成功后应用会自动安装到模拟器并启动
这里项目启动成功了，可以修改东西联调了
七、常见问题及解决方案
1. Gradle 下载超时
- 原因：网络问题或国外服务器访问慢
- 解决：按本文第四步手动下载并放置 Gradle 包
2. 编译时出现 “warnings found and -Werror specified”
-
原因：Kotlin 将警告视为错误
-
解决：修改 node_modules/@react-native/gradle-plugin/build.gradle.kts，将代码中的allWarningsAsErrors = true 改为 false
就这里的代码块，这个版本可能用不到
3. 模拟器启动后应用无法连接 Metro 服务
-
解决：
- 确保 Metro 服务正在运行 在模拟器中按 Ctrl+M，选择 Dev Settings
- 选择 Debug server host & port for device
- 输入 localhost:8081，点击 OK
- 重新加载应用
4. 依赖冲突或版本不匹配
- 解决：严格按照本文指定的版本安装依赖，不要随意升级版本