鸿蒙版React Native加载Bundle的三种方式

鸿蒙版 React Native 应用加载 Bundle 的三种方式

本文介绍在 OpenHarmony 上为 React Native 应用加载 bundle 的三种方式，并给出验证步骤与常见问题排查。

方式一：本地资源加载（rawfile）

将 bundle.harmony.js（或 Hermes 字节码 hermes_bundle.hbc）与图片资源放在 entry/src/main/resources/rawfile/ 目录下；在 entry/src/main/ets/pages/Index.ets 中通过 ResourceJSBundleProvider 指定：

// Hermes 引擎字节码（推荐在 Hermes 模式下使用）
new ResourceJSBundleProvider(this.rnohCoreContext.uiAbilityContext.resourceManager, 'hermes_bundle.hbc')

// JS bundle（Hermes 与 JSVM 均可使用）
new ResourceJSBundleProvider(this.rnohCoreContext.uiAbilityContext.resourceManager, 'bundle.harmony.js')

要点与建议：

• Hermes 引擎可运行 bundle.harmony.js，但性能通常不如 hermes_bundle.hbc
• 适合线上发布或无需热更新的场景

方式二：使用 Metro 服务加载（开发调试）

开发期可使用 Metro 实现热刷新。详细流程参考「调试调测 · Metro 热加载」（https://gitcode.com/openharmony-sig/ohos_react_native/blob/master/docs/zh-cn/调试调测.md#metro热加载）。

在 entry/src/main/ets/pages/Index.ets 中使用：

new MetroJSBundleProvider()

要点与建议：

• 启动 RN 工程的 Metro：npm run start
• 设备端口转发：hdc rport tcp:8081 tcp:8081
• 适合开发调试与快速迭代

方式三：加载沙箱目录的 bundle（文件系统）

应用沙箱是一种以安全防护为目的的隔离机制，应用可见的目录范围即为“应用沙箱目录”。

向应用沙箱推送文件的常见方式：

1. 通过 DevEco Studio 向应用安装路径中放入目标文件（参考：应用安装资源访问）
   • https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/quick-start/resource-categories-and-access.md
2. 使用 hdc 工具推送到沙箱路径（参考：向应用沙箱推送文件）
   • https://gitcode.com/openharmony/docs/blob/master/zh-cn/application-dev/file-management/send-file-to-app-sandbox.md

推送命令示例：

hdc file send ${本地bundle路径} ${沙箱路径}

在 entry/src/main/ets/pages/Index.ets 中通过 FileJSBundleProvider 指定沙箱内 bundle：

new FileJSBundleProvider('/data/storage/el2/base/files/bundle.harmony.js')

要点与建议：

• 适合离线调试或按需分发 bundle 的场景
• 注意沙箱实际可读路径与应用权限

验证方式（通用）

1. 启动应用后观察 RN/Metro 日志：是否看到 "Welcome to Metro" 或自定义日志
2. UI 是否正常渲染、是否能响应交互
3. 切换不同 Provider 后，确认 bundle 切换生效
4. 白屏时检查 RNApp 的 appKey 与 RN 工程中 AppRegistry.registerComponent 的 appName 是否一致

常见问题（FAQ）

1. 白屏或无法加载

• 确认 appKey 与 RN 工程 appName 一致
• 检查目标文件是否放置在正确路径（rawfile/沙箱）
• Hermes 使用 .hbc 是否匹配当前引擎模式

1. Metro 无法连接

• 执行端口转发：hdc rport tcp:8081 tcp:8081
• 确认本机 8081 端口无占用，并已启动 Metro

1. 图片不显示

• 确认 assets 是否一并拷贝到 rawfile
• 资源路径、大小写是否正确

学习鸿蒙版 RN，一切尽在GitCode[1]。

GitCode 鸿蒙版 RN 社区

社区价值与定位

GitCode 鸿蒙版 RN 社区是面向React Native 鸿蒙适配开发者打造的专业技术交流平台，致力于为开发者提供从入门到精通的完整学习路径和实战支持。

核心功能特色

• 技术文档中心：提供完整的 RNOH 适配指南、API 文档和最佳实践
• 代码示例库：汇聚各类适配场景的完整代码示例，支持一键复制使用
• 问题解答社区：资深开发者与官方工程师实时解答技术问题
• 版本发布跟踪：及时更新 RNOH 版本动态和兼容性信息
• 工具链支持：提供鸿蒙特有的编译调试工具和自动化脚本

如何参与社区

1. 学习交流：浏览技术文档，参与讨论，分享经验
2. 代码贡献：提交适配案例，完善文档，修复问题
3. 问题反馈：报告 Bug，提出改进建议，参与功能讨论
4. 生态共建：认领三方库适配任务，推动生态繁荣

社区资源链接

• 主仓库：ohos_react_native[2]
• 三方库集合：react-native-oh-library[3]
• 技术讨论：Issues 讨论区[4]

参考资料

[1]

GitCode: https://gitcode.com/oh-react-native/

[2]

ohos_react_native: https://gitcode.com/openharmony-sig/ohos_react_native

[3]

react-native-oh-library: https://github.com/react-native-oh-library

[4]

Issues 讨论区: https://gitcode.com/oh-react-native/docs/issue