关于这次体验这是一次在鸿蒙PC上本地开发React Native应用的完整体验。如果你手上有一台鸿蒙PC想尝试在本机上直接开发跨平台应用这份文档会带你走完整个流程。与传统的跨平台开发不同你不需要Windows或Mac作为开发主机——所有开发工作都在鸿蒙PC上完成。目录体验前的准备环境搭建创建React Native项目在鸿蒙原生工程中运行常见问题处理关键技术要点一、体验前的准备需要准备的硬件和环境一台鸿蒙PCHarmonyOS PC版本 6.1.0 稳定的网络连接用于下载SDK和依赖包基础的命令行操作能力会用终端执行简单命令可选一台鸿蒙手机或平板用于真机测试也可以用模拟器本次体验包含的内容在鸿蒙PC上安装并配置DevEco Studio创建一个React Native项目在鸿蒙设备上运行这个应用理解开发流程中的关键步骤二、环境搭建1. 安装 DevEco StudioDevEco Studio 是鸿蒙应用开发的官方IDE类似于Android开发中的Android Studio。申请鸿蒙PC专用版本访问官方申请页面https://developer.huawei.com/consumer/cn/activity/developerbeta/deveco-studio-preview申请后会有审核审核通过了就会发送邮件至邮箱中点击邮件中的链接就可以进行安装了。下载并安装按照页面提示下载安装包双击安装即可首次启动配置启动DevEco Studio按照向导完成SDK下载选择OpenHarmony SDK配置网络代理如果需要2. 配置 hdc 调试工具hdc是鸿蒙的命令行调试工具类似于Android的adb。需要把它加入到系统环境变量中。配置步骤下载Harmonybrew安装指南docs/zh-CN/user/install.md-代码预览-docs:基于 OpenHarmony 的包管理器移植项目 - AtomGitHarmonybrew是鸿蒙 / OpenHarmony 专用命令行软件包管理器照搬 macOS 主流工具 Homebrew 的逻辑一键下载gcc、cmake、ohos-sdk等开发工具不用手动找安装包、配依赖。打开终端-验证brew安装成功localhost ~ % brew--version如果显示版本号说明配置成功。安装ohos-sdk**localhost ~ % brewinstallohos-sdk下载ohos-sdk后hdc工具自动配置。验证是否配置成功hdc--version如果显示版本号说明配置成功。3. 配置 CAPI 架构环境变量这是React Native在鸿蒙上运行的必要配置。配置步骤继续编辑~/.zshrcvim~/.zshrc添加环境变量exportRNOH_C_API_ARCH1保存后生效source~/.zshrc验证echo$RNOH_C_API_ARCH应该输出14. 配置 npm 镜像源使用国内镜像可以加速依赖包下载。配置步骤编辑 npm 配置文件vim~/.npmrc添加以下内容按i进入编辑模式strict-sslfalse sslVerifyfalse registryhttps://repo.huaweicloud.com/repository/npm/保存并退出按Esc输入:wq回车清理缓存使配置生效npmcache clean--force5. 连接调试设备真机使用流程在设备上开启开发者模式设置 → 关于手机/平板 → 连续点击版本号7次返回设置 → 系统和更新 → 开发者选项 → 开启USB调试用USB连接设备到鸿蒙PC验证连接hdc list targets应该显示设备序列号三、创建你的第一个RN应用1. 初始化React Native项目打开终端执行以下命令# 创建项目项目名可以自定义npx react-native-community/clilatest init AwesomeProject--version0.77.1 --skip-install提示首次执行会下载一些依赖可能需要几分钟时间。2. 进入项目目录cdAwesomeProject3. 安装鸿蒙适配依赖步骤 1修改 package.json用文本编辑器打开package.json在scripts部分添加一行{scripts:{android:react-native run-android,ios:react-native run-ios,start:react-native start,dev:react-native bundle-harmony --dev// 添加这一行}}步骤 2安装鸿蒙专用包npminstallreact-native-oh/react-native-harmony0.77.59 react-native-oh/react-native-harmony-cli --legacy-peer-deps说明本文以0.77.59RNOH版本为例可以去官网搜索React Native和RNOH对应版本。4. 配置 Metro 打包工具Metro 是React Native的JavaScript打包工具。需要让它支持鸿蒙平台。修改 metro.config.js用文本编辑器打开项目根目录的metro.config.js替换为以下内容const{mergeConfig,getDefaultConfig}require(react-native/metro-config);const{createHarmonyMetroConfig}require(react-native-oh/react-native-harmony/metro.config);constconfig{transformer:{getTransformOptions:async()({transform:{experimentalImportSupport:false,inlineRequires:true,},}),},};module.exportsmergeConfig(getDefaultConfig(__dirname),createHarmonyMetroConfig({reactNativeHarmonyPackageName:react-native-oh/react-native-harmony,}),config);5. 生成鸿蒙 bundle 文件npmrun dev成功后你会在harmony/entry/src/main/resources/rawfile/目录下看到bundle.harmony.js- 打包后的JavaScript代码assets/- 静态资源文件夹将rawfile/ 目录下的所有文件复制到 后面第四步创建的鸿蒙原生工程MyApplication/entry/src/main/resources/rawfile/下四、在鸿蒙原生工程中运行1. 用 DevEco Studio 打开鸿蒙工程启动 DevEco StudioFile→New→Create Project→Empty Ability点击Next按钮创建一个名为 “MyApplication” 的项目2. 配置签名首次必须File→Project Structure→Signing Configs登录你的华为开发者账号点击 Apply → OK3. 安装鸿蒙 HAR 依赖包在 DevEco Studio 的终端中执行cdentry ohpminstallrnoh/react-native-openharmony0.77.59注意这个包比较大几百MB下载需要一些时间。等待ohpm install完成后IDE会自动同步依赖。4. 配置 C 底层代码React Native需要通过C层来桥接JavaScript和鸿蒙原生代码。步骤 1创建 C 目录和文件在harmony/entry/src/main/下创建cpp文件夹然后创建以下文件文件 1:cpp/CMakeLists.txtproject(rnapp) cmake_minimum_required(VERSION 3.4.1) set(CMAKE_SKIP_BUILD_RPATH TRUE) set(OH_MODULE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules) set(RNOH_APP_DIR ${CMAKE_CURRENT_SOURCE_DIR}) set(RNOH_CPP_DIR ${OH_MODULE_DIR}/rnoh/react-native-openharmony/src/main/cpp) set(RNOH_GENERATED_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated) set(CMAKE_ASM_FLAGS -Wno-errorunused-command-line-argument -Qunused-arguments) set(CMAKE_CXX_FLAGS -fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie) add_compile_definitions(WITH_HITRACE_SYSTRACE) set(WITH_HITRACE_SYSTRACE 1) add_subdirectory(${RNOH_CPP_DIR} ./rn) add_library(rnoh_app SHARED ./RNOHAppNapiBridge.cpp ) target_link_libraries(rnoh_app PUBLIC rnoh)文件 2:cpp/PackageProvider.cpp#includeRNOH/PackageProvider.h#includeRNOHCorePackage/RNOHCorePackage.husingnamespacernoh;std::vectorstd::shared_ptrPackagePackageProvider::getPackages(Package::Context ctx){return{std::make_sharedRNOHCorePackage(ctx),};}重要提示如果你只返回空数组{}应用会崩溃并提示undefined is not callable。必须注册RNOHCorePackage。文件 3:cpp/RNOHAppNapiBridge.cpp#includeRNOH/PackageProvider.h#includeRNOHCorePackage/RNOHCorePackage.husingnamespacernoh;std::vectorstd::shared_ptrPackagePackageProvider::getPackages(Package::Context ctx){return{std::make_sharedRNOHCorePackage(ctx),};}#include../../../oh_modules/rnoh/react-native-openharmony/src/main/cpp/RNOHAppNapiBridge.cpp步骤 2配置构建选项编辑harmony/entry/build-profile.json5添加 C 编译配置{ apiType: stageMode, buildOption: { externalNativeOptions: { path: ./src/main/cpp/CMakeLists.txt, arguments: , cppFlags: } }, targets: [ { name: default } ] }5. 配置 ArkTS 页面代码步骤 1修改 EntryAbility.ets打开harmony/entry/src/main/ets/entryability/EntryAbility.ets替换为import{RNAbility}fromrnoh/react-native-openharmony;import{Want}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;exportdefaultclassEntryAbilityextendsRNAbility{getPagePath(){returnpages/Index;}// ⚠️ 非常重要必须先调用 super.onCreate()overrideonCreate(want:Want):void{super.onCreate(want);// 这一行必须放在第一行hilog.info(0x0000,testTag,%{public}s,EntryAbility onCreate);}}关键点super.onCreate(want)这行代码会初始化React Native运行时环境。如果忘记调用应用会崩溃并提示Cannot read property logger of undefined。步骤 2创建 RNPackagesFactory.ets在harmony/entry/src/main/ets/目录下创建RNPackagesFactory.etsimport{RNPackageContext,RNPackage}fromrnoh/react-native-openharmony/ts;exportfunctioncreateRNPackages(ctx:RNPackageContext):RNPackage[]{return[];}步骤 3修改首页 Index.ets打开harmony/entry/src/main/ets/pages/Index.ets替换为以下内容import{AnyJSBundleProvider,ComponentBuilderContext,FileJSBundleProvider,MetroJSBundleProvider,ResourceJSBundleProvider,RNApp,RNOHErrorDialog,RNOHLogger,TraceJSBundleProviderDecorator,RNOHCoreContext,wrapBuilder}fromrnoh/react-native-openharmony;import{createRNPackages}from../RNPackagesFactory;BuilderexportfunctionbuildCustomRNComponent(ctx:ComponentBuilderContext){}constwrappedCustomRNComponentBuilderwrapBuilder(buildCustomRNComponent)EntryComponentstruct Index{StorageLink(RNOHCoreContext)privaternohCoreContext:RNOHCoreContext|undefinedundefinedStateshouldShow:booleanfalseprivatelogger!:RNOHLoggeraboutToAppear(){this.loggerthis.rnohCoreContext!.logger.clone(Index)conststopTracingthis.logger.clone(aboutToAppear).startTracing();this.shouldShowtruestopTracing();}onBackPress():boolean|undefined{this.rnohCoreContext!.dispatchBackPress()returntrue}build(){Column(){if(this.rnohCoreContextthis.shouldShow){if(this.rnohCoreContext?.isDebugModeEnabled){RNOHErrorDialog({ctx:this.rnohCoreContext})}RNApp({rnInstanceConfig:{createRNPackages,enableNDKTextMeasuring:true,enableBackgroundExecutor:false,enableCAPIArchitecture:true,arkTsComponentNames:[]},initialProps:{foo:bar}asRecordstring,string,// ⚠️ 重要这里必须和你的RN项目名完全一致appKey:AwesomeProject,wrappedCustomRNComponentBuilder:wrappedCustomRNComponentBuilder,onSetUp:(rnInstance){rnInstance.enableFeatureFlag(ENABLE_RN_INSTANCE_CLEAN_UP)},jsBundleProvider:newTraceJSBundleProviderDecorator(newAnyJSBundleProvider([newMetroJSBundleProvider(),newResourceJSBundleProvider(this.rnohCoreContext.uiAbilityContext.resourceManager,bundle.harmony.js)]),this.rnohCoreContext.logger),})}}.height(100%).width(100%)}}关键配置说明appKey: AwesomeProject- 必须和你的RN项目名完全一致包括大小写MetroJSBundleProvider()- 支持热加载开发时非常方便ResourceJSBundleProvider- 从应用资源加载bundle文件6. 启动Metro服务推荐在React Native项目根目录AwesomeProject打开终端执行npmrun start这会启动Metro开发服务器支持代码热更新。7. 运行应用在DevEco Studio中确保已连接设备点击工具栏的Run按钮绿色三角形选择entry模块等待编译完成首次编译需要几分钟如果一切顺利你会在设备上看到React Native的欢迎界面五、遇到问题怎么办常见问题 1应用崩溃提示Cannot read property logger of undefined原因EntryAbility.ets中忘记调用super.onCreate(want)解决方法打开harmony/entry/src/main/ets/entryability/EntryAbility.ets确保onCreate方法的第一行是super.onCreate(want);常见问题 2应用崩溃提示undefined is not callable原因PackageProvider.cpp中没有注册RNOHCorePackage解决方法打开harmony/entry/src/main/cpp/PackageProvider.cpp确保代码如下#includeRNOH/PackageProvider.h#includeRNOHCorePackage/RNOHCorePackage.husingnamespacernoh;std::vectorstd::shared_ptrPackagePackageProvider::getPackages(Package::Context ctx){return{std::make_sharedRNOHCorePackage(ctx),// 这行很重要};}常见问题 3白屏提示Couldnt run a JS bundle原因bundle文件没有正确生成或加载解决方法在项目根目录执行npm run dev检查harmony/entry/src/main/resources/rawfile/bundle.harmony.js是否存在确保Index.ets中的appKey和项目名一致常见问题 4编译失败找不到librnoh_app.so原因C 配置不正确解决方法检查harmony/entry/build-profile.json5是否配置了externalNativeOptions检查harmony/entry/src/main/cpp/CMakeLists.txt是否存在在 DevEco Studio 中执行Build → Clean Project然后重新构建查看详细日志如果遇到其他问题可以通过日志来诊断# 实时查看设备日志hdc shell hilog六、技术要点说明1. React Native 在鸿蒙上的架构React Native 应用在鸿蒙上分为三层JavaScript 层你写的React代码ArkTS 层鸿蒙的UI层C 桥接层连接JS和鸿蒙原生能力三层缺一不可任何一层配置错误都会导致应用无法运行。2. appKey 的作用appKey不是一个随便取的名字它是JavaScript和原生代码的约定JavaScript侧AppRegistry.registerComponent(AwesomeProject, ...)原生侧appKey: AwesomeProject两边必须完全一致包括大小写否则应用会白屏。3. 为什么需要 super.onCreate()RNAbility是React Native提供的基类它的onCreate()方法会初始化整个运行时环境。如果你重写了这个方法却不调用super.onCreate()运行时环境就无法初始化导致应用崩溃。4. Metro 开发服务器的作用Metro 是React Native的打包工具开发模式启动本地服务器支持热更新改代码立即生效生产模式打包成.js文件内嵌到应用中开发时推荐使用Metro模式可以大幅提升效率。5. bundle 加载优先级在Index.ets中配置了多种加载方式MetroJSBundleProvider- 优先从Metro服务器加载开发模式ResourceJSBundleProvider- 从应用资源加载生产模式应用会按顺序尝试找到第一个可用的就使用。七、下一步探索修改代码试试在项目根目录打开App.tsx修改一些文字比如把 “Welcome to React Native” 改成 “你好鸿蒙”保存文件如果Metro服务正在运行应用会自动刷新添加新的组件React Native 提供了很多内置组件你可以试试import{View,Text,Button,Alert}fromreact-native;functionApp(){return(ViewTextHello HarmonyOS!/TextButton title点击我onPress{()Alert.alert(你点击了按钮)}//View);}学习更多React Native 官方文档https://reactnative.dev/React Native 中文网https://reactnative.cn/RNOH 官方仓库https://gitee.com/openharmony-sig/ohos_react_native鸿蒙开发者文档https://developer.harmonyos.com/七、体验感悟开发体验的亮点1. 本地化开发的便利性在鸿蒙PC上直接开发React Native应用最大的感受是一体化。不需要在Windows和设备之间来回切换所有工作都在一台设备上完成编写代码、调试、运行全程本地设备之间的数据同步更流畅如果用鸿蒙账号终端、IDE、文档可以在同一个工作区管理2. Metro 热更新的开发效率使用 Metro 开发服务器后代码修改几乎是秒级生效。这种即时反馈的开发体验非常适合UI调试和快速迭代修改代码 → 保存 → 设备自动刷新 2秒相比传统的改代码 → 重新编译 → 重新安装效率提升了一个数量级。3. C 层的学习曲线React Native 在鸿蒙上需要配置 C 桥接层这对前端开发者来说可能是一个挑战。但好在模板化大部分 C 代码是固定的模板一次配置配置好后基本不需要再改动文档完善RNOH 社区提供了详细的参考经过这次体验对 React Native 的架构理解更深了——它不仅仅是 JavaScript 框架而是一个完整的跨平台桥接系统。遇到的挑战1. 首次构建的耗时第一次编译 C 代码时时间确实比较长5-10分钟。这是因为需要编译 RNOH 的完整 C 库需要链接大量的依赖首次构建会做完整的依赖检查建议首次构建时可以去喝杯咖啡后续的增量编译会快很多。2. 错误信息的理解当配置不正确时错误信息有时不够直观。比如Cannot read property logger of undefined→ 实际是super.onCreate()没调用undefined is not callable→ 实际是PackageProvider没注册经验遇到错误时先检查文档中常见问题部分列出的那几个关键点90%的问题都在那里。3. 依赖包的下载速度由于网络原因ohpm install和npm install有时会比较慢。特别是rnoh/react-native-openharmony这个包体积较大。解决方案配置好镜像源后情况会好很多华为云的镜像源速度还是很可靠的。与传统开发的对比传统方式Windows/Mac 鸿蒙设备代码编辑 (PC) → 编译打包 (PC) → 传输到设备 → 运行测试 → 查看日志 (PC)优点PC性能强编译快缺点需要维护跨设备的开发环境调试链路长鸿蒙PC本地开发代码编辑 → Metro热更新 → 即时预览 → 查看日志 → 继续编辑优点一体化调试链路短移动办公友好缺点首次编译耗时较长适合的场景通过这次完整体验我认为鸿蒙PC本地开发特别适合以下场景原型快速验证需要快速搭建一个 Demo验证想法的可行性UI 交互调试频繁调整界面布局、动画效果需要即时反馈移动办公只带一台鸿蒙PC出差或远程工作也能完成开发任务学习和实验学习 React Native 或鸿蒙开发体验完整的技术栈不太适合的场景大型项目的重度开发如果项目有几十个原生模块构建时间会比较长需要频繁切换平台调试如果需要同时调试 Android、iOS、鸿蒙三端在PC上可能更方便未来的期待经过这次体验对鸿蒙PC作为开发平台有了信心。如果未来能有以下改进体验会更好增量编译优化希望 C 层的编译速度能进一步提升更友好的错误提示特别是配置错误时能给出更明确的定位开发工具链完善比如支持更多的调试工具、性能分析工具社区生态丰富更多的第三方库适配鸿蒙平台总体评价作为一次尝鲜体验在鸿蒙PC上开发 React Native 应用是可行且流畅的。虽然有一些小挑战但并不妨碍完整走通开发流程。推荐指数⭐⭐⭐⭐4/5如果你是鸿蒙PC用户想尝试跨平台开发 → 强烈推荐体验如果你在学习React Native → 这是一个很好的实践平台如果你是移动办公族 → 一台设备完成开发的体验很棒最大的收获理解了 React Native 的完整架构从 JavaScript 到原生桥接再到设备运行整个链路清晰了。八、版本信息React Native 版本0.77.1RNOH 版本0.77.59推荐 DevEco Studio 版本6.1.0反馈与支持如果在体验过程中遇到问题仔细阅读遇到问题怎么办章节使用hdc shell hilog查看详细日志在RNOH社区寻求帮助祝你在鸿蒙PC上的React Native开发之旅顺利