从零到一：React Native 0.73 开发环境搭建与原生工程集成实战指南
在当今跨平台移动应用开发领域，React Native凭借其“一次编写，多端运行”的理念，已成为连接Web前端与原生移动开发的重要桥梁。对于熟悉React和前端框架的开发者而言，它能极大提升开发效率。然而，一个顺畅的开发环境是成功的第一步。本文将带你深入实践，从环境准备到RN工程与安卓原生工程的完整集成，并分享过程中遇到的典型问题与解决方案，助你快速上手。
一、环境准备：构建稳固的开发基石
在开始任何前端工具链的配置前，明确并验证基础环境是至关重要的。与Vue等框架类似，React Native对Node.js、JDK、Android SDK的版本有特定要求。我的基础环境配置如下，这确保了后续步骤的兼容性：
经验之谈：务必使用LTS版本的Node.js，并确保Android SDK的安装路径不含中文和空格。配置ANDROID_HOME环境变量是连接UI开发与原生编译的关键一步，许多“命令找不到”的错误都源于此。
二、创建与配置React Native工程
React Native的初始化命令在版本迭代中有所变化。直接使用传统的 react-native init 可能会遇到命令已废弃的提示。
✅ 正确做法：按照官方最新推荐，使用社区CLI进行初始化。以下命令创建了一个名为RNApp、指定版本为0.73.4的工程，并跳过初始安装以方便后续自定义配置。
npx @react-native-community/cli init RNApp --version 0.73.4 --skip-install
进入工程目录后，安装依赖是下一步。由于网络原因，直接使用npm官方源可能速度缓慢甚至失败。
# 进入工程目录
cd E:/android/projects/RNDemo4/RNApp/RNApp
# 清空npm缓存，解决因缓存导致的安装异常
npm cache clean --force
# 使用国内镜像源并增加超时时间，确保安装成功
npm install --registry=https://registry.npmmirror.com --timeout=600000安装完成后，可以通过以下方式验证：
至此，一个独立的React Native工程已准备就绪。[AFFILIATE_SLOT_1]
三、搭建安卓原生工程并集成RN
为了将React Native页面嵌入现有或全新的安卓应用，我们需要配置一个安卓原生工程。这里的关键在于正确配置Gradle文件，以引入React Native依赖。
首先，在项目根目录的 libs.versions.toml 文件中统一管理版本：
[versions]
agp = "8.2.0"
kotlin = "1.9.20"
coreKtx = "1.10.1"
junit = "4.13.2"
junitVersion = "1.1.5"
espressoCore = "3.5.1"
lifecycleRuntimeKtx = "2.6.1"
[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
junit = { group = "junit", name = "junit", version.ref = "junit" }
androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }
androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }
androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycleRuntimeKtx" }
[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }接着，修改模块级（app）的 build.gradle 文件，添加React Native依赖和必要的配置：
plugins {
alias(libs.plugins.android.application)
alias(libs.plugins.kotlin.android)
}
android {
namespace 'com.example.androidapp'
compileSdk 34
// 引入本地libs（兜底，若Gradle依赖仍有问题）
repositories {
flatDir {
dirs 'libs'
}
}
defaultConfig {
applicationId "com.example.androidapp"
minSdk 29
targetSdk 34
versionCode 1
versionName "1.0"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
ndk {
abiFilters 'armeabi-v7a', 'x86', 'x86_64', 'arm64-v8a'
}
}
buildTypes {
release {
minifyEnabled false
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
}
}
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = '17'
}
packaging {
resources {
excludes += ["META-INF/LICENSE.md", "META-INF/LICENSE-notice.md"]
}
}
}
dependencies {
// 原生基础依赖
implementation libs.androidx.core.ktx
implementation libs.androidx.lifecycle.runtime.ktx
testImplementation libs.junit
androidTestImplementation libs.androidx.junit
androidTestImplementation libs.androidx.espresso.core
// 核心修复：用react-android替代react-native（适配0.70+拆分版）
implementation "com.facebook.react:react-android:0.73.4"
implementation "com.facebook.react:hermes-android:0.73.4" // 可选，Hermes引擎
implementation "com.facebook.soloader:soloader:0.10.5" // RN必需
}项目根目录的 build.gradle 和 settings.gradle 也需要相应调整：
buildscript {
ext {
buildToolsVersion = "34.0.0"
minSdkVersion = 29
compileSdkVersion = 34
targetSdkVersion = 34
reactNativeVersion = "0.73.4"
}
repositories {
google()
mavenCentral()
maven { url "https://maven.aliyun.com/repository/central" }
}
}
plugins {
alias(libs.plugins.android.application) apply false
alias(libs.plugins.kotlin.android) apply false
}
allprojects {
repositories {
google()
mavenCentral()
maven { url "https://maven.aliyun.com/repository/public/" }
// RN官方Maven仓库（兜底）
maven { url "https://repo1.maven.org/maven2/" }
}
}
task clean(type: Delete) {
delete rootProject.buildDir
}pluginManagement {
repositories {
google {
content {
includeGroupByRegex("com\\.android.*")
includeGroupByRegex("com\\.google.*")
includeGroupByRegex("androidx.*")
}
}
mavenCentral()
gradlePluginPortal()
// 1. 新增：添加阿里云镜像（解决插件下载慢/失败）
maven { url "https://maven.aliyun.com/repository/public/" }
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
// 2. 新增：添加RN依赖的本地仓库路径（和根build.gradle的allprojects一致）
maven { url "E:/android/projects/RNDemo4/RNApp/RNApp/node_modules/react-native/android" }
maven { url "E:/android/projects/RNDemo4/RNApp/RNApp/node_modules/jsc-android/dist" }
// 新增：阿里云镜像（加速RN依赖下载）
maven { url "https://maven.aliyun.com/repository/public/" }
}
}
rootProject.name = "AndroidApp"
include ':app'gradle-wrapper.properties 文件决定了使用的Gradle版本：
#Tue Feb 17 21:48:50 CST 2026
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
#distributionSha256Sum=a17ddd85a26b6a7f5ddb71ff8b05fc5104c0202c6e64782429790c933686c806
#distributionUrl=https\://services.gradle.org/distributions/gradle-9.1.0-bin.zip
#distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.5-bin.zip
# ?????????SHA256???
distributionSha256Sum=9d926787066a081739e8200858338b4a69e837c3a821a33aca9db09dd4a41026
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/distsMainApplication代码如下：package com.example.androidapp
import android.app.Application
import com.facebook.react.ReactApplication // 保留接口
import com.facebook.react.ReactNativeHost
import com.facebook.react.ReactPackage
import com.facebook.react.defaults.DefaultReactNativeHost
import com.facebook.react.shell.MainReactPackage
import com.facebook.soloader.SoLoader
import java.util.ArrayList
// 实现ReactApplication接口（匹配抽象属性定义）
class MainApplication : Application(), ReactApplication {
// 核心修改：把方法改为接口要求的抽象属性（val）
override val reactNativeHost: ReactNativeHost = object : DefaultReactNativeHost(this) {
override fun getPackages(): List {
val packages = ArrayList()
packages.add(MainReactPackage()) // RN核心包
return packages
}
override fun getJSMainModuleName(): String {
return "index"
}
// 调试模式开启（直接返回true，避免BuildConfig问题）
override fun getUseDeveloperSupport(): Boolean {
return true
}
// 关闭新架构，避免额外依赖
override val isNewArchEnabled: Boolean
get() = false
override val isHermesEnabled: Boolean
get() = true
}
override fun onCreate() {
super.onCreate()
SoLoader.init(this, false)
}
} 安卓应用的核心入口 MainActivity 需要继承 ReactActivity：
package com.example.androidapp
import com.facebook.react.ReactActivity
import com.facebook.react.ReactActivityDelegate
import com.facebook.react.defaults.DefaultReactActivityDelegate
class MainActivity : ReactActivity() {
// 必须和RN工程package.json的name一致（RNApp）
override fun getMainComponentName(): String {
return "RNApp"
}
override fun createReactActivityDelegate(): ReactActivityDelegate {
return DefaultReactActivityDelegate(this, mainComponentName, false)
}
}最后，配置 AndroidManifest.xml 和 styles.xml：
同步Gradle后，你可能会看到依赖安装提示和漏洞警告：
⚠️ 注意：运行 npm audit fix 可以修复大多数非关键性漏洞。对于开发环境，这些警告通常可以暂时忽略，但生产环境需谨慎处理。
四、联调与离线Bundle方案
理想情况下，我们通过Metro服务进行实时调试。启动服务并设置端口转发：
adb reverse tcp:8081 tcp:8081
npx react-native start --port 8081然而，在实际开发中，网络环境、防火墙或代理设置可能导致Metro连接失败，页面无法加载。当实时调试遇到阻碍时，离线Bundle方案是一个可靠的备选方案，尤其适合集成测试或对网络有严格限制的环境。
在RN工程目录下，执行以下命令将JavaScript代码和资源打包成离线文件：
cd /d E:\android\projects\RNDemo4\RNApp\RNApp
npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res/如果 assets 目录不存在，需要手动创建：
命令执行成功后，会生成 index.android.bundle 文件：
将该bundle文件复制到安卓原生工程的对应目录：
最后，修改安卓原生的 MainApplication，使其从本地assets加载bundle，而非从开发服务器（Metro）加载：
package com.example.androidapp // 替换为你的实际包名
import android.app.Application
import com.facebook.react.ReactApplication
import com.facebook.react.ReactNativeHost
import com.facebook.react.ReactPackage
import com.facebook.react.defaults.DefaultReactNativeHost
import com.facebook.react.shell.MainReactPackage
import com.facebook.soloader.SoLoader
import java.util.ArrayList
class MainApplication : Application(), ReactApplication {
// 恢复默认的ReactNativeHost写法，仅修正Bundle路径
override val reactNativeHost: ReactNativeHost = object : DefaultReactNativeHost(this) {
override fun getPackages(): List {
val packages = ArrayList()
packages.add(MainReactPackage())
return packages
}
override fun getJSMainModuleName(): String {
return "index"
}
override fun getUseDeveloperSupport(): Boolean {
return true
}
override val isNewArchEnabled: Boolean
get() = false
override val isHermesEnabled: Boolean
get() = true
// 改用RN 0.73兼容的assets路径写法（核心修复）
override fun getBundleAssetName(): String {
return "index.android.bundle"
}
// 注释掉getJSBundleFile，改用getBundleAssetName
// override fun getJSBundleFile(): String {
// return "android_asset/index.android.bundle"
// }
}
override fun onCreate() {
super.onCreate()
SoLoader.init(this, false)
}
} 运行安卓原生工程，现在你将看到来自React Native的页面成功渲染：
成功！ 这证明React Native组件已成功集成到原生安卓应用中。这个页面正是你RN工程里 App.tsx 定义的组件。[AFFILIATE_SLOT_2]
五、总结与最佳实践
通过以上步骤，我们完成了一次完整的React Native开发环境搭建与原生集成。整个过程涵盖了从环境校验、工程创建、依赖安装、原生工程配置到最终打包集成的全链路。关键要点在于：确保环境版本兼容、善用国内镜像加速、理解Gradle依赖配置、掌握离线Bundle作为调试备选方案。
与Vue的跨端方案或纯原生UI开发相比，React Native在开发效率与性能之间取得了良好平衡。遇到连接问题时，不要局限于一种调试方式，灵活运用离线包可以极大提升开发体验。希望这篇实战指南能帮助你绕过初期的坑洼，顺利开启React Native跨平台开发之旅。
浙公网安备 33010602011771号