从零搭建 React Native 到项目运行全记录（0.73.6 稳定版）

晨旭缘2025-10-13 12:56

作为一名开发者，我最近在搭建 React Native 项目时遇到了不少坑，从环境配置到依赖冲突，再到 Gradle 下载超时等问题，耗费了大量时间。为了方便日后换电脑或工作环境时快速复用，特意整理这篇从零到一的搭建教程，包含所有关键配置和避坑指南

一、环境准备

1. 安装必要工具

首先确保你的电脑上安装了以下工具：

  • Node.js ：v18.0.0 或更高版本（推荐使用 nvm 管理 Node 版本）
  • Yarn：替代 npm 的包管理工具
bash 复制代码 
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」；

手动配置JDK 17示例（系统变量）：

JAVA_HOME配置：

Path配置（位置必须移到最上边，首先加载 ）：

CLASSPATH配置：.;%JAVA_HOME%\lib;%JAVA_HOME%\lib\tools.jar(注意别少了点 .)

  • 验证 JDK 安装与环境变量
    • 打开新的 CMD 终端（注意：安装后需重启终端，环境变量才生效）；
    • 执行以下命令验证：
bash 复制代码 
# 查看 Java 版本（需显示 17.x.x）
java -version

# 查看 JAVA_HOME 环境变量（需显示 JDK 安装路径，如 C:\Program Files\Amazon Corretto\jdk17.x.x_xx）
echo %JAVA_HOME%
  • 若输出类似以下内容，说明 JDK 配置成功：
bash 复制代码 
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)

2. 安装 Android 开发环境

2.1 下载并安装 Android Studio

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 提供的环境检查工具：
bash 复制代码 
npx react-native doctor
复制代码 
 确保所有检查项都显示为绿色对勾，如有问题按照提示修复。

二、创建 React Native 项目

1. 新建项目

使用指定版本创建项目（经过验证的稳定版本组合）：

bash 复制代码 
# 进入工作目录
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. 安装指定版本依赖

bash 复制代码 
# 安装 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 中的依赖应如下：

javascript 复制代码 
"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

这个文件控制项目的构建配置和依赖仓库，使用国内镜像加速下载：

kotlin 复制代码 
buildscript {
    ext {
        buildToolsVersion = "33.0.0"
        minSdkVersion = 21
        compileSdkVersion = 33
        targetSdkVersion = 33
        ndkVersion = "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

配置依赖仓库和项目结构：

kotlin 复制代码 
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：

kotlin 复制代码 
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就是下载失败

2. 放置到指定目录

  • 找到 Gradle 缓存目录：C:\Users\你的用户名.gradle\wrapper\dists\gradle-8.3-all
  • 目录下会有一个随机字符串命名的子目录（如 a5gdekw7up59x6at40l00u7s2）
  • 将下载的 gradle-8.3-all.zip 复制到这个随机字符串目录下（不要解压）

3. 验证 Gradle 配置

powershell 复制代码 
# 进入 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

powershell 复制代码 
# 在项目根目录执行，不是在Android目录中，如果在Android，需要cd..退出
yarn start --reset-cache


这里Metro 服务启动成功了

2. 安装并运行应用

打开新的终端窗口，执行：

bash 复制代码 
# 安装并运行到模拟器
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. 依赖冲突或版本不匹配

  • 解决：严格按照本文指定的版本安装依赖，不要随意升级版本

总结：核心是使用经过验证的稳定版本组合（React Native 0.73.6 + React 18.2.0），并通过国内镜像加速依赖下载

相关推荐
IT利刃出鞘4 小时前
WordPress--代码块添加折叠和展开功能
javascript
Onion4 小时前
解决 iframe 中鼠标事件丢失问题：拖拽功能的完整解决方案
前端·javascript·vue.js
Sailing4 小时前
🔥🔥「别再复制正则了」用 regex-center 一站式管理、校验、提取所有正则
前端·javascript·面试
GISer_Jing4 小时前
前端知识详解——HTML/CSS/Javascript/ES5+/Typescript篇/算法篇
前端·javascript·面试
一枚前端小能手4 小时前
🔧 jQuery那些经典方法，还值得学吗？优势与式微的真相一次讲透
前端·javascript·jquery
写不来代码的草莓熊4 小时前
vue前端面试题——记录一次面试当中遇到的题（4）
前端·javascript·vue.js·面试
被巨款砸中5 小时前
Jessibuca 播放器
前端·javascript·vue.js·web
不渡_5 小时前
Web项目-版本号
前端·javascript
Asort5 小时前
JavaScript设计模式(十一)：享元模式(Flyweight) - 优化内存与性能的利器
前端·javascript·设计模式
热门推荐
01BongoCat - 跨平台键盘猫动画工具02两千字总结：Codex 国内如何安装和使用的教程，以及如何设置中文回答03智能库存管理的需求预测模型：从业务痛点到落地代码的完整实践042025羊城杯网络安全大赛 wp05GitHub 镜像站点06UV安装并设置国内源07Linux下V2Ray安装配置指南08Spring Boot 实现微信登录，So Easy !095大DOM/BOM核心考点：从入门到精通，让面试官眼前一亮10Cursor Plan Mode：AI 终于知道先想后做了