鸿蒙 PC 的 React Native 应用能离线启动吗,从 Metro 报错查到 HAP 里的 bundle
框架与适配 · React Native for OpenHarmony 适配
开发时连着 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。
更多推荐
所有评论(0)