去年底开始，我们团队有一个跨端项目需要落到鸿蒙设备上。技术栈固定在 React Native，于是先想到了一个问题：RN 打出来的 bundle 文件，能不能直接在鸿蒙的 DevEco Studio 工程里跑起来？这里说的 DevEco Studio，就是华为官方的鸿蒙应用开发 IDE，不少人手滑打成 DevEvo Studio，标题里这个拼法就是这么传开的。整个迁移过程里，最折磨人的不是环境搭建，也不是容器集成，而是"一切看起来都正常，但 run 起来就是白屏"。先后排查了 bundle 文件是否进包、是否有日志、是否资源缺失，最终才定位到根因：从 Android 构建产物里拷出来的 bundle，其实是 Hermes 字节码，不是 JS 源码。这篇文章把完整的现象、排查思路、定位过程和解决方法都记录下来，给正在做同样迁移的同学一个参照。
1. 为什么要把 React Native 的 bundle 搬进鸿蒙：迁移背后的真实背景
1.1 项目诉求：一套业务代码，尽可能多的运行平台
以前跨端项目主要盯 Android 和 iOS，业务逻辑、组件、状态管理全都沉淀在 React Native 代码里。鸿蒙这边用户量在涨，业务不能不做，但如果为鸿蒙单独维护一整套原生代码，开发、测试、上架的成本都要翻倍，小团队根本扛不住。所以最理想的方案是：业务代码不变，鸿蒙端只提供一个能加载 RN bundle 的容器。
这里需要先理清一个概念：React Native 的产物是 JS 文件（也就是 bundle），它本身不依赖某个具体的操作系统，靠的是宿主环境提供的 JS 引擎和原生能力桥接。因此在鸿蒙上跑 RN，本质上就是把"宿主环境"从 Android/iOS 换成鸿蒙。鸿蒙提供 ArkTS 和原生 C++ 能力，RN 容器完全可以构建在这套能力之上。
另外要说明一点，HarmonyOS NEXT 已经不支持直接加载 Android 的 APK，也没法去复用安卓里的 RN 容器。想跑 React Native，只能走"鸿蒙原生容器 + RN JS bundle"这条路。这也是为什么必须在 DevEco Studio 里做集成编译，而不是简单拿个 APK 塞进去。
1.2 技术选型：为什么用社区维护的 react-native-harmony
做技术选型的时候，摆在我面前无非两条路：一是自己基于 ArkTS/ArkUI 写一套 RN 运行时桥接层，二是直接用社区已经适配好的方案。自己写的成本极高，RN 的原生模块、事件机制、渲染映射、网络栈全都要重新对接，不是一个人短期内能完成的。社区这边，OpenHarmony 生态里已经有人在做 RN 适配，形成了 react-native-harmony 这样的框架，接口尽可能对齐 React Native 官方 API。
实际集成的时候，发现它的工作方式跟 RN 官方在 Android 上的容器很像：初始化一个 RNApp 或者 RNInstance 对象，指定 bundle 名称和入口组件，然后交给 JS 端渲染。听起来不难，但正是这种"看起来不难"，让我在后面吃了不少苦头。因为框架只负责把容器搭起来，bundle 文件怎么生成、怎么放、怎么命名，都需要你自己确认。任何一步不匹配，最终表现就是白屏。
1.3 DevEco Studio 在整条链路里的作用
DevEco Studio 是华为官方的鸿蒙应用开发 IDE，基于 IntelliJ IDEA 二次开发，支持 ArkTS、C++、Java 等语言，负责鸿蒙应用的工程管理、编译、签名、模拟器和真机调试。在 RN 迁鸿蒙这个场景里，DevEco Studio 承担的角色是"把鸿蒙容器代码和 RN bundle 一起打包成 hap 安装包"。你可以把它理解成 Android 开发里的 Android Studio，只不过最终产物是鸿蒙的 hap，不是 apk。
这里有一个关键点：如果只是把 bundle 文件放到鸿蒙工程里，编译的时候，bundle 的二进制内容本身不会被二次处理。它会被当成 rawfile 资源原样打进 hap；真正参与编译的是容器代码。很多人以为 IDE 会做 "RN 优化"，其实不会，bundle 是什么格式，进包就是什么格式。这个认知在后面排查 Hermes 字节码问题时非常重要。
2. 打包与集成：Metro、bundle 和鸿蒙工程的对接方式
2.1 从 RN 到 bundle：Metro 打包命令的关键参数
React Native 的 JS 代码默认由 Metro 打包器输出成 bundle 文件。在 Android/iOS 工程里，这个动作通常由 Gradle 或 Xcode 自动完成，但鸿蒙工程不会主动帮你做，所以需要手动执行打包命令。
我当时用的命令大致是这样：
npx react-native bundle \ --platform android \ --dev false \ --entry-file index.js \ --bundle-output ./dist/index.bundle \ --assets-dest ./dist/assets几个参数分别解释一下：
--platform声明目标平台。这里写 android 还是 harmony，取决于适配层有没有提供对应的平台解析规则。如果配置里没有单独映射 harmony，沿用 android 的解析方式通常也能跑，因为 RN 业务代码里很少用平台专属分支，即便有，也可以通过Platform.OS判断。--dev false产出 release 模式的 JS 代码，关闭调试器连接和部分 dev-only 逻辑。--entry-file指定入口文件，一般是 index.js。--bundle-output是 bundle 文件的输出路径。--assets-dest是静态资源输出目录，图片、字体等资源会按相对路径放好。
这一步最需要注意的是：不同 RN 版本、不同适配层对 bundle 文件名的预期可能不一样。有的工程固定要index.bundle，有的要main.jsbundle。别想当然，先去看容器初始化代码里写的名字，再决定打包参数。
2.2 bundle 在鸿蒙工程里的落位：rawfile 目录
Metro 打包完成之后，得到dist/index.bundle和dist/assets目录。接下来把它们放进鸿蒙工程。默认鸿蒙工程里，entry 模块的资源目录是entry/src/main/resources，其中 rawfile 子目录专门放"原样打包、不做编译处理"的文件，bundle 就应该放这里。
目录结构大概长这样：
entry/src/main/ ├── ets/ │ ├── entryability/ │ └── pages/ ├── resources/ │ ├── base/ │ └── rawfile/ │ ├── index.bundle │ └── assets/把这两个东西放进去之后，DevEco Studio 构建 hap 时会把 rawfile 中的内容原封不动地打包进产物。
这里有一个小坑：Metro 的 assets 输出是按平台路径组织的，比如assets/src/...，如果打包时用--platform android，资源内部路径可能包含drawable-mdpi之类的目录。鸿蒙容器加载资源的时候，通常使用相对 bundle 文件位置的路径，对目录结构的要求和 Android 不完全一致。所以打包后最好检查一下 assets 目录的结构，确保和容器代码里引用的资源路径对得上。
2.3 容器初始化代码：bundle 名称和入口的对应关系
bundle 文件放进 rawfile 之后，还需要确认鸿蒙容器那边初始化时指向的文件名和入口组件。在 react-native-harmony 的集成代码里，一般会看到类似这样的初始化逻辑：
new RNApp('MyRNApp', { bundleName: 'index.bundle', entryComponent: 'App', })这里的bundleName必须和 rawfile 里的文件名完全一致，大小写也要一致。否则运行时会去加载一个不存在的文件，直接失败。我第一次运行就栽在这里：rawfile 里放的是index.bundle，但初始化代码里写的是index.android.bundle，结果运行时提示 "Unable to load script"。
这种问题属于"低级错误"，但往往不容易一眼发现，因为 IDE 不会报编译错误，只有运行日志里才会暴露出来。
3. 现场还原：白屏、加载失败与日志排查链路
3.1 现象：页面白屏，没有红屏也没有错误弹窗
把 bundle 文件放好、初始化代码对齐之后，我在 DevEco Studio 里构建出 hap，装到模拟器上启动，结果页面一片空白。没有红屏警告（RN 在开发模式经常出现的那种），没有弹窗，进程也没崩溃。就感觉 JS 完全没有执行，或者执行了但 UI 渲染不出来。
最让人头疼的是，模拟器上没有任何明显的 JS 异常提示。我当时的第一反应是：是不是容器初始化的时序问题，导致页面挂载失败？于是反复调整入口组件和生命周期，改了好几版，还是白屏。
这里提醒一下还在用模拟器的朋友：鸿蒙模拟器对运行环境的支持目前还有限制，有些版本只能在 arm64 平台上跑 JS 运行时，如果开发机是 x86 架构，用模拟器就可能遇到环境层面的不兼容。排查问题时，先确认模拟器本身能正常跑一个 hello world 鸿蒙应用，再往下查 RN 层的问题，不然很容易被误导。
3.2 第一步排查：bundle 文件到底有没有进 hap
解决白屏问题，第一步不是看代码，而是确认最终的 hap 安装包里到底有没有我们放的 bundle 文件。因为有时候 rawfile 路径放错了，或者构建缓存没刷新，bundle 根本没被打进安装包，模拟器启动后容器在加载路径上找不到文件，自然白屏。
我当时的验证方法很简单：构建完成后，直接从 DevEco Studio 的 build 输出目录找到entry-default-signed.hap，用解压工具打开，检查resources/rawfile/下有没有index.bundle和assets目录。
如果发现没有，问题多半出在：
- rawfile 目录路径写错，比如放到了
resources/base下面； - 构建缓存没刷新，先试一下 Build 菜单里的 Clean Project；
- 配置了多模块工程，但 bundle 放到了非 entry 模块的 rawfile 里，导致最终 hap 没包含它。
我这次的情况是：bundle 确实打进去了，文件大小也对得上，所以这一步可以排除。
3.3 用 hdc 抓日志：hilog 里的关键线索
排除了"文件没进包"之后，就得看运行日志了。鸿蒙系统有自己的日志系统 hilog，对应 Android 的 logcat。连接模拟器或真机后，先清空缓冲区再启动应用，避免被历史日志淹没：
hdc shell hilog -r hdc shell hilog | grep ReactNativeJS通过ReactNativeJS这个标签，可以过滤出 RN 容器里 JS 层的日志和异常信息。当时的输出大概是这样：
E ReactNativeJS: Unable to load script. Make sure you're either running Metro (try 'npx react-native start') or that your bundle 'index.bundle' is packaged correctly for release.这一句非常经典，基本上等于告诉你：bundle 文件加载失败了。但这个报错没有给出具体原因——是文件不存在？还是格式不对？还是文件内容有问题？它只说"要么你去跑 Metro，要么确认 bundle 正确打包"。
到这里，排错思路就清晰了：Metro 肯定没在跑，我们是离线加载 bundle，所以问题出在 bundle 文件本身。可这个 bundle 是从我们正式的 RN 构建流程里出来的，Android 端验证过没有任何问题。那为什么 Android 正常，鸿蒙就不行？这是我接下来一直在想的问题。
4. 根因定位：这份 bundle 是 Hermes 字节码，不是 JavaScript
4.1 为什么 Android 上正常、鸿蒙上就白屏
这里要回到 Android 端的一个构建细节。现在的 React Native 在 Android 上默认使用 Hermes 作为 JS 引擎。Hermes 有一个特点：它可以把 JS 源码预编译成字节码，在启动时直接加载字节码，省去解析和执行脚本的开销，从而加快冷启动。
在 Android 的 release 构建流程里，Gradle 插件会自动调用 Hermes 编译器，把 Metro 输出的 JS bundle 转成 Hermes 字节码文件，文件名通常还是index.android.bundle。所以很多团队从 Android 构建产物目录里拿到的"bundle"，本质上已经不是 JS 源码了。
我当时犯了同样的错误：为了省事，直接从 Android 的构建产物里复制了index.android.bundle，觉得"反正都是同一个 RN 项目打出来的包，鸿蒙应该也能用"。这个认知在鸿蒙这条路线上完全不成立。
4.2 用文件头魔数确认 Hermes 格式
要确认一个 bundle 到底是 JS 还是 Hermes 字节码，不需要复杂的工具。Hermes 字节码文件有固定的文件头魔数，十六进制下前四个字节是c6 1f bc 03；而纯 JS bundle 文件的第一行通常以注释开头，内容类似var __BUNDLE_START_TIME__或者/**。
在终端里执行：
xxd index.android.bundle | head -n 3如果输出像这样：
00000000: c61f bc03
