欢迎加入开源鸿蒙 PC 社区

欢迎在 PC 社区平台申请新建项目

框架与适配 · React Native for OpenHarmony 适配

AtomGit 文章与演示素材

开发时连着 Metro 能看到界面,不能由此推断交付包可以脱离开发机启动。现场版本应在 Metro 不可用时仍能从 HAP 读到前端代码。本文把包内文件、入口选择和运行日志分开验证,说明离线检查该卡在哪一道门槛上。

拆开两份 HAP,里面都能找到 bundle.harmony.js。关掉开发服务后,一份却仍找 localhost:8081,另一份能打开离线自检页。鸿蒙 PC 上这次 React Native 启动排查给了一个很实在的对照:知道包里有什么,还要知道鸿蒙入口实际选了谁。

核对项

Metro 对照包

资源版

JavaScript 加载入口

Metro 地址

包内 bundle.harmony.js

8081 和端口转发不可用时

开发页未启动

离线自检页显示

点击页面动作

没有进入自检页

读取计数更新并写出日志

两个包各自往哪儿找脚本

第一步是在开发机查 8081 没有监听,再查 HDC 当前的转发列表为空。这里没有关闭模拟器的所有网络,只让 Metro 的依赖不可用。第二步安装旧入口的对照包。应用窗口出现了,但页面显示无法加载 JS bundle,日志尝试访问 localhost。此时可以用 ZIP 查包,里面确实还有一个旧 bundle.harmony.js。之所以没用到它,是因为对照入口只注册了 Metro 的 provider。这一步把资源缺失和资源没有被选中分开了。

暂时无法在飞书文档外展示此内容

把 8081 的监听和 HDC 转发先排除,旧入口仍试图连接开发机。红色错误页证明应用没走到自检页,无法单凭它判断包里缺了什么。这次它还有旧资源,宿主却只配置了 Metro。需要将现有开发流程保留时,可以继续用开发 provider;在准备离线调试的版本里,要明确切换资源 provider,并检查它的名字与包内资源对应。

import {
  AnyJSBundleProvider,
  RNApp,
  RNOHErrorDialog,
  ResourceJSBundleProvider,
  RNOHCoreContext
} from '@rnoh/react-native-openharmony';
import { getRNOHPackages } from '../PackageProvider';

@Entry
@Component
struct Index {
  @StorageLink('RNOHCoreContext') private rnohCoreContext: RNOHCoreContext | undefined = undefined

  build() {
    Column() {
      if (this.rnohCoreContext) {
        if (this.rnohCoreContext?.isDebugModeEnabled) {
          RNOHErrorDialog({ ctx: this.rnohCoreContext })
        }
        RNApp({
          rnInstanceConfig: {
            name: "AwesomeProject",
            createRNPackages: getRNOHPackages,
            fontResourceByFontFamily: {},
            enableDebugger: this.rnohCoreContext?.isDebugModeEnabled,
          },
          appKey: "AwesomeProject",
          jsBundleProvider: new AnyJSBundleProvider([
            new ResourceJSBundleProvider(this.rnohCoreContext.uiAbilityContext.resourceManager, 'bundle.harmony.js'),
          ]),
        })
      }
    }
    .height('100%')
    .width('100%')
  }
}

资源版把这一步写到 RNApp 的配置里,选择 ResourceJSBundleProvider 读本地资源。JavaScript 负责渲染与交互,宿主决定加载来源。两份 HAP 的 JS 版本也不同,所以本次可以用来诊断哪套来源被实际选中。如果要单独衡量 provider 的影响,应在下一次构建时固定同一份 JavaScript,只换宿主加载配置。

import React, {useState} from 'react';
import {Pressable, StyleSheet, Text, View} from 'react-native';

const readings = [
  ['本地入口', 'JS bundle 已执行'],
  ['内置样本', '3 条记录可读'],
  ['交互', '等待读取'],
];
export default function App() {
  const [count, setCount] = useState(0);
  return <View style={s.page}>
    <View style={s.header}><Text style={s.title}>离线启动检查</Text>
      <Text style={s.hint}>模拟器内检查包里的 JavaScript 与交互。</Text></View>
    <View style={s.panel}>
      {readings.map(([label, value], index) => <View style={s.line} key={label}>
        <Text style={s.label}>{label}</Text>
        <Text style={s.result}>{index === 2 && count ? '已读取 ' + count + ' 次' : value}</Text>
      </View>)}
    </View>
    <Pressable style={s.action} accessibilityRole="button" onPress={() => {
      setCount(count + 1);
      console.info('UGC_RNOH_OFFLINE local rows=' + readings.length + ' clicks=' + (count + 1));
    }}><Text style={s.actionText}>读取内置样本</Text></Pressable>
  </View>;
}
const s = StyleSheet.create({
  page: {flex: 1, padding: 25, backgroundColor: '#212936'},
  header: {marginBottom: 20},
  title: {color: '#edf4ff', fontSize: 29, fontWeight: '700'},
  hint: {color: '#b0bbcc', fontSize: 14, marginTop: 5},
  panel: {maxWidth: 800, borderWidth: 1, borderColor: '#4a586f', borderRadius: 12, backgroundColor: '#2b3647'},
  line: {minHeight: 48, padding: 12, gap: 10, flexDirection: 'row', justifyContent: 'space-between',
    flexWrap: 'wrap', borderBottomWidth: 1, borderColor: '#414d62'},
  label: {color: '#e4eaf5', fontSize: 15},
  result: {color: '#a4e2c8', fontSize: 15, fontWeight: '600'},
  action: {marginTop: 16, alignSelf: 'flex-start', paddingHorizontal: 16, paddingVertical: 10,
    borderRadius: 8, backgroundColor: '#b9dbf8'},
  actionText: {color: '#263648', fontWeight: '700'},
});

暂时无法在飞书文档外展示此内容

从端口、执行日志到点击回调

这次鸿蒙 PC 复测还遇到一个取证问题。换装 Metro 对照包后的第一次自动采集没有抓到相关行,单独重启并按 RNOH 日志筛选后才看到「None of the provided JSBundleProviders was able to load a bundle」。随后恢复资源版,读取到 JS bundle executed successfully,再点按钮验证回调。遇到两次启动互相干扰时,应分别保存两个进程的日志。

Metro:  Loading JS bundle: http://localhost:8081/index.bundle?platform=harmony&dev=true&minify=false
Metro:  None of the provided JSBundleProviders was able to load a bundle
内嵌版: Loading JS bundle: bundle.harmony.js
内嵌版: JS bundle executed successfully
内嵌版: UGC_RNOH_OFFLINE local rows=3 clicks=1

暂时无法在飞书文档外展示此内容

内嵌资源版在 MateBook 14 上能直接打开

早期这次 MateBook 14 只安装了资源版。下面的图和录屏记录了实际加载成功。这次在原生 DevEco 重新做了独立项目,并加入相同设备上的双包对照。

环境

版本

覆盖范围

HUAWEI MateBook 14(MNTXM-24B)

HarmonyOS 7.0.0,7.0.0.115(SP11C00E103R12P2patch01),API 26.0.0,aarch64

签名安装、内嵌版启动,读取内置样本后界面计数为 1

MateBook Pro 2in1 模拟器

HarmonyOS 6.1.0,6.1.0.125(SP12DEVC00E47R1P3),API 6.1.1(24),x86_64

Metro 对照包失败与内嵌版成功均有记录

暂时无法在飞书文档外展示此内容

点「读取内置样本」后,页面由「等待读取」变为「已读取 1 次」。这里用实际的窗口状态证明 React Native 处理了点击。应用副标题沿用了样例里的「模拟器内检查」字样,设备来源由 USB 目标、系统版本截图以及带程序坞的真机全屏共同确认。

暂时无法在飞书文档外展示此内容

MateBook 14 真机冷启动实录。开录前确认无 Metro 转发,启动后界面显示包内 JS bundle 已执行、3 条内置记录可读,点击后计数变为 1。页面仍显示工程原有的「模拟器内检查」提示。原始全屏 MP4 为 2880 × 1920,拖窗期间一秒内录到 60 个不同画面,整段平均约 25.4 fps。

hvigor Finished :entry:default@BuildNativeWithNinja
hvigor Finished :entry:default@SignHap
install bundle successfully.
start ability successfully.
versionName: 1.0.0
hdc fport ls: [Empty]

第一次采集遗漏了旧入口的关键行,重新启动那份包并按 RNOH 标签单独查,才看清 provider 无法加载脚本。切换资源版以后,先等 JS 执行成功,再点「读取内置样本」。一次读取的状态和日志对上,证明进的不只是一个宿主空窗。宽窄窗都能看见计数是布局检查;资源实际来自哪里,仍看本次启动记录。

暂时无法在飞书文档外展示此内容

暂时无法在飞书文档外展示此内容

前次模拟器实录共 23.73 秒,保留 97 个不同画面。先看 Metro 未接通的出错页,再看资源版加载与点击后计数。桌面截图和日志可以分别对应到两个入口。

FAQ

日志已经有 Running,为什么还点按钮? 这行可以说明进入了 React Native 的入口,旧 JS 也可能有同名入口。当前包用自检标题、样本和点击记录一起核对。先检查标题,再点一次,能避免用启动阶段的一条记录代替交互验收。

包里已放新 bundle,怎么还访问 8081? 先查 RNApp 的 provider 配置及顺序。只换文件不会改变入口选用的来源。测试时也要确定正在运行的确实是刚安装的 HAP,重新启动再按进程号取日志。

两份包共用一份 bundle,只改加载入口

这是本次本机对照和早期记录的区别。前次两份包的 JavaScript 版本有差异,本次从同一个 App.tsx 生成 bundle,只构建一次前端,之后保持 rawfile/bundle.harmony.js 不动。第一次让宿主只用 Metro,第二次让宿主只用资源提供器。这样读者遇到离线启动问题时,可以先问实际选中哪个来源,再判断是否需要重打前端。

设备与工具

版本及验证

本机开发端与运行端

HUAWEI MateBook 14(MNTXM-24B),HarmonyOS 7.0.0,软件版本 7.0.0.115(SP11C00E103R12P2patch01),API 26.0.0,aarch64。DevEco Studio 26.0.0.220,Node.js 24.18.1,React Native 0.84.1,RNOH 0.84.4,目标 API 24。

早期模拟器

MateBook Pro 2in1,软件版本 6.1.0.125(SP12DEVC00E47R1P3),API 24,x86_64。上面的模拟器图片与 GIF 来自这组运行。

从本机终端在存在 package-lock.json 的目录生成新 bundle。鸿蒙工程放在 harmony,取用依赖的 HAR。打开工程配置后,把同一个包名 com.aasd23.ugcrnohoffline 绑定本机调试签名。首次运行选择「此电脑」。随后仅改 entry/src/main/ets/pages/Index.ets 并重新运行,仍使用同一签名和版本。每轮签名包都要在覆盖构建之前另存,才能回头检查到底变了哪个归档成员。

node --version
npm ci --ignore-scripts
node ./node_modules/react-native/cli.js bundle-harmony --dev false --minify false
ls -lh harmony/entry/src/main/resources/rawfile/bundle.harmony.js
cd harmony
ohpm install --all

检查同一台电脑的 127.0.0.1:8081 不接受连接,再装第一包。若端口上已有别的项目,可换一个明确未监听的回环端口,同时修改 Metro 对照入口和探针。保持实际实验条件尽可能简单,仅断开示例用的开发服务。用这组测试不能判断所有应用功能是否离线,包括数据同步、登录或外部资源下载。

暂时无法在飞书文档外展示此内容

留下两份可重做的样本

完整源码默认启用资源入口。开始反例之前,在工程根目录备份这份 Index.ets,再把 Index.metro.ets 放进鸿蒙模块同一位置。前端 bundle 在这里已经生成。切换入口期间保持资源目录不动,也不再运行生成脚本,以免第二轮应用实际用了更新的 JS。编译和安装都从「此电脑」启动。每次运行结束,从输出目录另存带签名的 HAP,确保保留的是两次打包的不同文件。

cp harmony/entry/src/main/ets/pages/Index.ets Index.local.ets
cp Index.metro.ets harmony/entry/src/main/ets/pages/Index.ets
# 在 DevEco 运行签名调试包,完成后单独保留
cp harmony/entry/build/default/outputs/default/entry-default-signed.hap metro-provider.hap
cp Index.local.ets harmony/entry/src/main/ets/pages/Index.ets
# 在 DevEco 再运行一次,保留资源版
cp harmony/entry/build/default/outputs/default/entry-default-signed.hap resource-provider.hap
node inspect-hap.mjs metro-provider.hap resource-provider.hap
node probe-metro.mjs

比对时对包内解压后的完整 JS 字节做哈希。文件名和大小可以相同,实际内容仍可能已经换掉。这里的检查也会在任意一个包缺少该条目时失败。得出结果后把日志按两次启动分别留存,红色错误页下方的请求地址和本机探针对应,资源版则记录它读取的文件名。若只截一个能打开的窗口,仍无法判断最近这次运行从哪条路径加载了代码。

当前样本的三条记录存在 JavaScript 里的固定数组,按钮只更新当前界面的读取次数。它能验证包内脚本执行和本地组件回调。应用每次重启会把次数从头计数,这是这个测试用状态的行为。后续若把内置数据改为文件数据库,应把读取失败、空表和重启后读回另设用例,原来的点击日志只留作启动链证据。

端口仍拒绝连接时,资源版已经能读样本

先安装 Metro 入口的签名包。系统受理启动,窗口弹出 RNOH 的报错页。此次地址显式设为 127.0.0.1:8081,本机探针返回 ECONNREFUSED。RNOH 日志也记录了请求这个地址,并报告没有提供器能加载 bundle。即使包里已经存在正确的脚本,只要当前入口没有选它,就进不了自检页。

jsBundleProvider: new AnyJSBundleProvider([
  MetroJSBundleProvider.fromServerIp('127.0.0.1', 8081),
]),

保留第一份 HAP,恢复上面的资源提供器写法,再从同一台电脑安装第二份签名包。两次安装的包名和版本一致,系统记录为 1.0.1。取出包里的 resources/rawfile/bundle.harmony.js 比较,哈希相同。归档里还有宿主字节码、源码映射和原生库字节差异,因此这里按相同 JS 和已核对的宿主配置解读两个结果。

资源版在这个端口条件下打开「离线启动检查」。读取三条内置记录后,宽窗计数变成一;缩到窄窗再点一次,计数变成二。另一次完全停止并重启时,RNOH 把实际加载来源写成 bundle.harmony.js。启动日志、画面和点击日志对应三个不同的检查点。

Metro: Loading JS bundle: http://127.0.0.1:8081/index.bundle?platform=harmony&dev=true&minify=false
Metro: None of the provided JSBundleProviders was able to load a bundle
资源版:Loading JS bundle: bundle.harmony.js
资源版:JS bundle executed successfully
资源版:UGC_RNOH_OFFLINE local rows=3 clicks=1
资源版:UGC_RNOH_OFFLINE local rows=3 clicks=2

结语

用同一份 bundle 把两次启动对起来后,排查可以从实际加载源开始。先核对包内文件,再读 RNOH 选择的地址,最后点一次只有 JS 执行以后才有反应的按钮。三条证据都吻合,就能确认这个示例的启动和本地交互已经脱离 Metro。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐