RNOH 版本升级、跨版本迁移与历史缺陷回溯的排查方法论与定位指南

在 RNOH 开发中，"升级到新版本后行为变化""同一代码在不同 RNOH 版本表现不一""历史崩溃在低版本偶现"是最容易误判的问题类型之一。本文档给出从现象到根因、从分类到处置的系统化定位方法。

一、问题概述

1.1 什么是"历史版本问题"

RNOH 的版本号形如 0.{RN 主版本}.{鸿蒙化迭代序号}（如 0.77.70），第三位是鸿蒙化独立迭代计数，不等于 RN 社区的补丁版本（见 docs/zh-cn/RNOH与RN版本关系.md）。RNOH 采用"固定版本采用"策略：仅选取 RN 社区特定大版本（0.72.5/0.77.1/0.82.1/0.84.1）做鸿蒙化适配，社区补丁不合入，鸿蒙平台特有 Bug 在自研迭代序号上修复（见 docs/zh-cn/RNOH与RN版本关系.md §二）。

由此产生三类与"版本"强相关的问题：

  • 同一 JS 代码在不同 RNOH 版本线（0.72 / 0.77 / 0.82 / 0.84）行为不一致；
  • 升级版本后出现编译失败、运行崩溃、白屏或交互变化；
  • 某个历史崩溃/冻屏，在低版本偶现，需判断是否已被某次迭代修复。

1.2 为什么必须先分类再处理

并非所有"升级后变了"都是 Bug。RNOH 的演进同时包含三类性质完全不同的变更，处置方向相反：

  • 把一个上游不兼容变更当成 Bug 去回退框架版本，会错过安全更新并长期偏离上游；
  • 把一个已被修复的历史缺陷当成"平台特性"放任，会导致开发者带着已知问题反复排错；
  • 把一个构建配置错配当成代码 Bug 去改业务代码，会越改越乱。

因此定位流程的第一步是分类，而不是第一步就改代码或回退版本。

1.3 三类版本问题的性质

类别定义是否需修复
历史缺陷（已在迭代修复）RNOH 在某次鸿蒙化迭代中已修复的崩溃/冻屏/内存问题（如 FontRegistry 死锁、EventEmitter UAF）；低版本未含修复故偶现✅ 升级到含修复的迭代版本
上游不兼容变更RN 社区在版本演进中引入的 API/行为/类型变更（refs 废弃、onLayout 优先级降低、codegen 入参检查趋严）✅ 按上游要求适配业务/三方代码
配置与构建错配升级后工程配置未同步：源码↔release 构建、RNOH_C_API_ARCH、bundle 缓存、codegen 产物路径、folly 编译选项✅ 修正工程配置

二、排查思路与整体分析

2.1 核心判定流程

定位版本问题的关键是回答一个问题：该行为差异是"已被 RNOH 修复的缺陷"，还是"上游契约变更"，还是"工程配置未同步"？

flowchart TB
    A["升级或换版后行为变化或历史崩溃"] --> B{"是否能在版本线稳定版<br/>release-notes 或稳定性修复汇总中<br/>找到对应修复条目?"}
    B -->|"是: 命中历史缺陷"| C["分类: 历史缺陷<br/>→ 升级到含修复的迭代"]
    B -->|"否"| D{"上游 RN 是否在该版本<br/>引入了不兼容变更?"}
    D -->|"是: 命中上游变更表"| E["分类: 上游不兼容变更<br/>→ 按变更说明适配代码"]
    D -->|"否"| F{"是否随升级改变<br/>构建模式、依赖或产物路径?"}
    F -->|"是: 源码与 release 构建或缓存"| G["分类: 配置与构建错配<br/>→ 修正工程配置"]
    F -->|"否"| H["转入通用缺陷定位<br/>黑屏、崩溃或三端差异"]
    C -.->|已修复| I["核对引入版本号"]
    E -.->|需适配| J["按上游 PR 适配代码"]
    G -.->|配置同步| K["清理产物并对齐配置"]

2.2 排查总思路：先定版本边界，再沿三层定位

版本问题定位的本质是先确定"现象在哪两个版本之间分叉"，再沿 RNOH 三层链路找到分叉点：

版本边界(哪个版本引入/修复) → 分层定位(JS层 / 桥接层 / 原生层) → 变更性质(缺陷/上游变更/配置)

排查应按以下顺序逐层推进，每一层都读真实源码与 release 记录：

  1. 锁定版本边界 — 用稳定版号、release-notes、稳定性历史修复汇总确认现象在哪两个版本之间变化；
  2. 区分变更来源 — 是 RNOH 自研迭代修复（鸿蒙平台特有），还是 RN 上游引入（跨 iOS/Android/鸿蒙一致）；
  3. 核对工程配置 — 是否随升级切换了构建模式、依赖路径、产物路径或混淆配置；
  4. 判定问题性质 — 用 2.1 流程归入三类之一；
  5. 核验代码引用 — 每条引用必须指向真实读过的文件或在线 release 记录。

关键原则：版本对比只回答"在哪个版本分叉、分叉属于哪类"。找到分叉版本后，具体的崩溃根因（如锁顺序、UAF）按《黑屏白屏与渲染异常定位指南》《三端不一致定位指南》继续向下分析，不在本流程内重复。

2.3 RNOH 版本问题常见模式速查

模式分类说明
低版本偶现崩溃，高版本不复现历史缺陷命中稳定性历史修复汇总某条目（如 0.72.86 getSDKApiVersion 多线程 SIGABRT）
升级大版本后编译/打包失败上游不兼容变更命中上游不兼容变更表（refs 废弃、enableOptimisedVirtualizedCells 移除等）
升级后交互时序变化上游不兼容变更上游调整了事件优先级/默认值（如 onLayout 优先级降低、列表锚点策略变更）
切 release 构建后链接报错配置与构建错配F14LinkCheck/kEmptyTagVector、hermes/hermes.h not found、OH_GetSdkApiVersion 未定义
装新 HAP 后行为仍是旧的配置与构建错配FileJSBundleProvider 设备缓存未清除，加载了旧 bundle
release 混淆后 undefined 崩溃配置与构建错配混淆把 ArkTS 内联方法名改写，运行时找不到（如 px2vp）
同一行为三端都变上游不兼容变更非 RNOH 独有，参见 docs/zh-cn/RNOH与RN社区共性问题清单.md

三、分步排查过程（工具使用）

源码与文档查阅：文中引用可在本地仓库或社区仓库在线打开——RNOH 源码：ohos_react_native/{文件路径}；RNOH 文档：https://gitcode.com/CPF-RN/ohos_react_native/blob/main/docs/zh-cn/{文件路径}。

3.1 排查准备：确认版本基线与复现边界

定位版本问题的第一步不是读源码，而是把版本号与复现边界钉死：

  1. 三处版本号必须对齐：
    • RN 工程 package.json 的 react-native（必须落在 RNOH 指定的固定补丁版，如 0.77.1，不要用 0.77.2/0.77.3，见 docs/zh-cn/RNOH与RN版本关系.md §二）；
    • RN 工程的 @react-native-oh/react-native-harmony（前端 JS 侧，走 npm 0.XX-stable dist-tag）；
    • 鸿蒙工程 oh-package.json5 的 @rnoh/react-native-openharmony（原生侧，用与前端同号的具体版本号，ohpm 无 dist-tag）。

      实时查询某版本线当前 stable 指向：npm view @react-native-oh/react-native-harmony dist-tags（见 docs/zh-cn/05-运维/版本说明.md）。

  2. 记录当前 RNOH 源码版本：本仓库 packages/react-native-harmony/package.json 中 "version" 字段（当前为 0.84.3，对齐上游 0.84.1，见 [源码] packages/react-native-harmony/package.json）。
  3. 双版本复现：用同一段最小化 JS 代码，分别在"问题版本"与"目标版本/最新 stable"上运行，确认差异确实由版本引起（排除业务代码与缓存干扰）。
  4. 收集两端日志：鸿蒙端用 hilog / DevEco Studio LogView + FaultLog；崩溃抓 CppCrash/AppFreeze。对比两版本在同一操作下的事件序列与堆栈。

3.2 步骤 1：锁定版本边界

目标：确定现象"在哪个版本引入"或"在哪个版本修复"，得到一个 [旧版本] → [新版本] 的分叉区间。

在哪查：

资料位置用途
docs/zh-cn/05-运维/release-notes/react-native-harmony-v0.84.*.md [在线源码]0.84 系列每次迭代的 Added/Fixed 条目（带 commit 链接）
docs/zh-cn/05-运维/稳定性历史修复/{0.72,0.77,0.82}稳定性修复汇总/README.md [在线源码]按版本线汇总的历史崩溃/冻屏/内存/资源修复，按修改日期排序，便于按故障现象回溯
本仓库 CHANGELOG.md [源码]顶层变更日志（如 0.84.3 的 Fabric 并行渲染、TextInput 修复，带 commit）
本仓库 git log --oneline / git log --branches --oneline [源码]跨分支（0.72-main/0.77-main/0.82-main/main）查找具体提交

要回答的关键问题：现象是否能在"稳定性历史修复汇总"中找到同模块、同现象的条目？找到即说明是历史缺陷，对应条目的"版本"列即修复落地版本。

示例点拨：字体相关死锁在 0.82.3、0.77.44 均有修复条目（FontRegistry 锁顺序不一致导致死锁），修复方式是 std::scoped_lock 原子加锁（见 [在线源码] 0.82稳定性修复汇总/02-应用冻屏.md）。若你的现象是"字体加载时卡死"，且当前版本低于上述迭代号，即可判定为历史缺陷。

3.3 步骤 2：区分变更来源（RNOH 自研 vs 上游 RN）

目标：判断分叉是"鸿蒙平台特有修复"还是"RN 上游引入的跨平台变更"，二者适配责任不同。

判定依据：

  • RNOH 自研修复：条目出现在"稳定性历史修复汇总"或 release-notes 的 Fixed 中，描述涉及鸿蒙原生模块（FontRegistry、RNInstance、TurboModuleProvider、ArkTSBridge、SchedulerDelegate），且社区 iOS/Android 不受影响 → 升级版本即可解决，无需改业务代码。
  • RN 上游变更：现象在 iOS/Android/鸿蒙三端一致变化，或命中 docs/zh-cn/05-运维/上游社区不兼容变更.md [在线源码] 的条目 → 必须按上游要求适配业务/三方代码，回退 RNOH 版本无效。

上游变更表关键条目速查（摘自 上游社区不兼容变更.md，含变更来源版本与影响场景）：

变更来源版本影响
字符串 refs 废弃0.77.0-rc.0编译失败，需改用 React.ElementRef
onLayout 事件优先级降低为固定异步批量0.74.0运行态：onLayout 及时性变差，影响依赖它的动画/布局时序
enableOptimisedVirtualizedCells 标志位移除（默认 true）0.77.0-rc.0编译失败
concurrentRoot 启动项移除0.77.0-rc.0编译失败
codegen 方法对 null 入参检查趋严0.75.0运行态：在不接受 null 的 TurboModule 方法传 null 会报错
SyncCallback 禁止拷贝0.75.0编译失败，需改 move 或创建多个
butter 组件移除0.73.0C++ 编译失败，需替换命名空间
View Manager 定义不再支持 .tsx0.73.0打 bundle 报错

示例点拨：升级到 0.77 后，依赖 onLayout 触发的动画出现"慢一拍"。这命中的是上游变更 onLayout 优先级降低（0.74.0 引入，RNOH 0.77 跟随上游），不是 RNOH Bug，应调整业务侧对 onLayout 时序的依赖，而非回退版本。

3.4 步骤 3：核对工程配置与构建模式

目标：排除"升级顺带改变了构建模式/依赖路径/产物路径"导致的假象。这是最易与代码 Bug 混淆的一类。

必查项：

  1. 构建模式切换：从源码（debug）构建切到 release 预编译构建后，CMakeLists.txt 需补齐 autolinking、hermes 头文件路径、folly 编译选项、系统 NDK 库，否则三方库链接报错（详见 docs/zh-cn/三方库Release配置FAQ.md）：
    • ReanimatePackage.h 等找不到 → 缺 autolinking 配置（include(autolinking.cmake) + autolink_libraries）；
    • hermes/hermes.h file not found → include_directories 缺 ${RNOH_CPP_DIR}/third-party/hermes/API；
    • F14LinkCheck::check() / kEmptyTagVector 未定义 → 三方包缺 -DFOLLY_MOBILE=1（推荐 add_compile_options(${folly_compile_options}) 统一）；
    • OH_GetSdkApiVersion 未定义 → rnoh 链接列表缺 libdeviceinfo_ndk.z.so。
  2. **RNOH_C_API_ARCH**：CAPI 版本启动闪退，日志提示未设置 RNOH_C_API_ARCH → 设环境变量 RNOH_C_API_ARCH=1，重启 IDE，Build > Clean Project 后重编；不生效则删 .cxx 目录（见 [在线源码] docs/zh-cn/03-调测/运行类FAQ.md）。
  3. bundle 缓存：FileJSBundleProvider 从设备路径（如 /data/storage/el2/base/files/bundle.harmony.js）加载，优先级高于 HAP 内 rawfile bundle，且HAP 更新后不会自动清除。每次装新 HAP 前必须 hdc shell "rm -f /data/storage/el2/base/files/bundle.harmony.js"，否则加载旧 bundle 制造"升级没生效"假象（见 [源码] JSBundleProvider.ts FileJSBundleProvider.getBundle，及 docs/开发者指南/03-开发调试/OpenHarmony运行RN应用.md §2.6）。
  4. codegen 产物路径：release 字节码包报 cannot find record '&@rnoh/react-native-openharmony/generated/ts&<版本>' → codegen 把 ets 生成到 oh_modules 下导致运行时找不到 record；自 CLI 0.77.23 起用 --ets-output-path 生成到源码目录并调整 import 路径（见 [在线源码] 运行类FAQ.md）。
  5. 混淆配置：release 混淆把 ArkTS 内联声明的方法名改写，运行时解析成 undefined 崩溃（如 px2vp）→ 历史修复见 0.72.128/0.77.59/0.82.17，升级到含修复版本或调整混淆保留规则。
  6. 更新环境后旧产物：ohpm install 或同步依赖后，旧 .cxx/oh_modules/build 缓存未清 → Build > Clean Project + 手动删 .cxx、oh_modules + Sync and Refresh Project（见 [在线源码] docs/zh-cn/03-调测/定位定界指导类FAQ.md）。

3.5 步骤 4：判定问题性质

目标：套用 2.1 判定流程，把差异归入三类之一，并给出判定依据（引用 release 条目或上游变更表）。

回答三个问题：

  1. 现象是否能在稳定性历史修复汇总/release-notes 中找到同模块同现象的已修复条目？（是 → 历史缺陷）
  2. 现象是否命中上游不兼容变更表或三端一致变化？（是 → 上游不兼容变更）
  3. 升级是否顺带改变了构建模式/依赖路径/产物路径/混淆？（是 → 配置与构建错配）

输出：分类（历史缺陷 / 上游不兼容变更 / 配置与构建错配）+ 判定依据（引用具体 release 条目或上游 PR）。

3.6 步骤 5：核验代码与版本引用

目标：输出结论前，确保每条引用都指向真实读过的代码或 release 记录，杜绝"想当然"。

  • 历史缺陷引用必须给出修复落地版本号与修复汇总条目链接（commit/MR）；
  • 上游变更引用必须给出变更来源版本与上游 PR/commit（见 上游社区不兼容变更.md）；
  • 配置问题引用必须给出具体修改文件（如 entry/src/main/cpp/CMakeLists.txt、build-profile.json5）；
  • 在线查阅得到的标注 [在线源码]，本地源码标注 [源码]，未读引用标注 [待确认]，绝不编造。

3.7 工具速查

工具用途示例
npm view ... dist-tags查某版本线 stable 当前指向确认 0.77-stable 当前具体版本号
稳定性历史修复汇总按版本线回溯历史崩溃/冻屏在 0.72稳定性修复汇总 搜"ScrollView"找修复版本
release-notes0.84 系列逐迭代 Added/Fixed确认某修复是否在 0.84.3 已合入
git log --branches --oneline跨分支查提交在 0.82-main 与 main 间定位某 commit
DevEco FaultLog / hilog崩溃与运行日志对比对比两版本 CppCrash 堆栈
hdc shell rm ...清 bundle/缓存装新 HAP 前清 FileJSBundleProvider 缓存
AI 辅助定位堆栈 + 版本号 → 根因rnoh-version-issue-analyzer（触发词：版本差异、升级回归）

四、根因定位

4.1 定位方法：找到版本分叉点

根因定位的本质是先用 release 记录锁定分叉版本，再回到源码确认修复机制，最后对分叉分类。方法：

  1. 从步骤 1 锁定的版本区间出发，查稳定性历史修复汇总/release-notes，找同模块同现象条目；
  2. 命中条目则读其"详细修复内容"，回到本仓库源码核对修复机制是否与现象吻合；
  3. 用 4.2 的模式表识别分叉类型，用 4.3 的五问模板固化结论。

示例点拨：FontRegistry 死锁的分叉点落在 0.82.3/0.77.44。回到源码核对：FontRegistry.cpp 中 addFontData 用 std::scoped_lock lock(m_fontFileContentByFontFamilyMtx, m_fontCollectionMtx) 原子获取两把锁（见 [源码] src/main/cpp/RNOH/FontRegistry.cpp），正是为消除"JS 线程与 UI 线程加锁顺序相反"的死锁。若你的堆栈停在 FontRegistry::addFontData 的 mutex::lock，且版本低于修复版本，即可判定为该历史缺陷。

4.2 分叉模式识别指南

对照 2.3 速查表，每种给出"如何识别"与"在哪找"：

模式如何识别在哪找
低版本偶现崩溃，高版本不复现堆栈模块名与稳定性修复汇总某条目"影响模块"一致05-运维/稳定性历史修复/{ver}稳定性修复汇总/01-应用异常退出.md
升级大版本后编译/打包失败报错信息命中上游变更表（refs/标志位/命名空间）05-运维/上游社区不兼容变更.md
升级后交互时序变化现象三端一致，命中 onLayout 优先级/列表锚点变更上游变更表 + 上游 PR
切 release 后链接报错链接错误含 F14LinkCheck/hermes.h/OH_GetSdkApiVersion三方库Release配置FAQ.md
装新 HAP 行为仍是旧的日志显示加载的 bundle 路径为设备文件而非 rawfileJSBundleProvider.ts + OpenHarmony运行RN应用.md
release 混淆后 undefined 崩溃JS Crash 堆栈指向被混淆的方法名release-notes 搜"混淆/px2vp/undefined"

4.3 结论五问模板

每次定位完，用下表固化结论（作为待填模板，而非预填答案）：

问题含义
What现象是什么（崩溃/编译失败/行为变化，JS 侧可观察）
When在哪个版本引入 / 在哪个版本修复（版本号 + 修复汇总条目）
Where代码/配置何处（指明文件，源码或在线源码）
分类历史缺陷 / 上游不兼容变更 / 配置与构建错配
分类依据为什么归入此类（引用 release 条目或上游 PR）

五、解决方案

5.1 何时提出修复

仅在以下情况提出修复：

  1. 命中历史缺陷且当前版本低于修复落地版本 → 升级到含修复的迭代版本（首选）；
  2. 命中上游不兼容变更 → 按上游变更说明适配业务/三方代码，不要回退 RNOH 版本；
  3. 命中配置与构建错配 → 修正工程配置，不要改业务代码。

以下情况不要提出修复：现象是上游合理的跨平台行为变更且 RN 文档已说明；现象已在最新 stable 修复但你未升级；现象实际由 bundle 缓存或旧产物导致而非代码。

5.2 修复策略

适用时按以下策略之一落地。任何方案都必须指明文件/版本、改动思路与风险评估，并配套测试。

策略适用场景方法
升级到含修复的迭代版本历史缺陷升级 @rnoh/react-native-openharmony（ohpm 具体版本号）与 @react-native-oh/react-native-harmony（npm 0.XX-stable）到含修复版本；前端 RN 锁定在 RNOH 指定固定补丁版
按上游变更适配代码上游不兼容变更字符串 refs → React.ElementRef；onLayout 时序依赖 → 改用 useLayoutEffect/显式测量；codegen null 入参 → 补 null 校验；SyncCallback 拷贝 → 改 move
补全 release 构建配置源码↔release 切换autolinking + hermes 头文件 + FOLLY_MOBILE=1 + libdeviceinfo_ndk.z.so（见 三方库Release配置FAQ.md 参考配置片段）
清理缓存与产物bundle 缓存/旧产物rm .cxx oh_modules + hdc shell rm 设备 bundle 缓存 + Sync and Refresh Project
调整 codegen/混淆配置产物路径/混淆codegen 用 --ets-output-path 生成到源码目录；混淆保留规则保留被内联引用的方法名

风险评估要点：跨大版本升级（0.72→0.77→0.82→0.84）需同步升级 react/react-native/@react-native-community/cli/@react-native/babel-preset 等依赖到对应版本，并改 babel.config.js presets（见 docs/zh-cn/05-运维/版本升级指导.md [在线源码]）；升级后必须回归现有 iOS/Android 行为与三端差异。

5.3 仅文档输出（现象为上游合理变更时）

当分类为"上游不兼容变更"且属于 RN 既定演进方向时，输出应：清晰记录变更及上游来源版本；解释新行为机制；说明开发者侧影响；给出业务侧适配模式（如"用 React.ElementRef 代替字符串 ref""减少对 onLayout 时序的强依赖"）。

六、经验总结

6.1 六条核心教训

  1. 先确认三处版本号对齐 — react-native 必须落在 RNOH 指定固定补丁版，社区补丁不合入；前端 0.XX-stable 与原生具体版本号同号发布。版本号不对齐是一切误判的源头。
  2. 先查"是否已被修复"再读源码 — 稳定性历史修复汇总按版本线、按现象分类编排，命中条目即可省去源码级分析，直接升级。
  3. 区分 RNOH 自研修复与上游变更 — 自研修复升级即解，上游变更必须改代码；三端一致变化几乎都是上游，不是 RNOH Bug。
  4. 不要把构建配置错配当代码 Bug — 切 release、bundle 缓存、codegen 路径、混淆是"升级没生效/行为异常"的高频假象，先清缓存对齐配置。
  5. 不要用回退版本代替适配上游 — 上游不兼容变更是演进方向，回退 RNOH 版本无效且会错过安全更新。
  6. 不要跳过版本核验 — 每条引用指向真实读过的 release 条目或源码，未读标 [待确认]，绝不编造版本号或 commit。

6.2 排查清单（Checklist）

  • 三处版本号已对齐（react-native 固定补丁版 + 前端 stable + 原生同号）
  • 已在稳定性历史修复汇总/release-notes 中搜索同模块同现象条目
  • 已判定分叉属于 RNOH 自研修复还是上游变更（三端是否一致）
  • 已核对构建模式/依赖路径/产物路径/混淆是否随升级变化
  • 已清理 bundle 缓存与旧构建产物后复现
  • 若为历史缺陷：已指明修复落地版本号
  • 若为上游变更：已指明变更来源版本与上游 PR
  • 若为配置错配：已指明具体修改文件与配置项

6.3 常见误区对照

误区正解
"升级后崩了，RNOH 新版本有 Bug，回退"先查稳定性修复汇总；可能是上游变更或配置错配，回退反而错过修复
"0.77.70 的第三位等于 RN 0.77 的第 70 个补丁"第三位是鸿蒙化独立迭代序号，与 RN 补丁版本无关
"RN 社区出了 0.77.3，我也升上去"RNOH 仅采用固定补丁版（0.77.1），社区补丁不合入，擅自升 RN 补丁会破坏稳定性
"装了新 HAP 还是一样的行为，代码没改对"FileJSBundleProvider 设备缓存优先级高于 rawfile，先 hdc shell rm 清缓存
"切 release 后链接报错，是三方库 Bug"是工程 CMakeLists.txt 缺 autolinking/folly 选项/系统库，按 三方库Release配置FAQ.md 补齐
"引用大概在哪个版本修了就行"必须指明具体修复落地版本号，读过的才算数

附录

附录 A：版本线与历史缺陷分叉高发区

下图标注了 RNOH 版本问题的分叉高发层：

flowchart TB
    subgraph VER["版本边界（先定分叉版本）"]
      V1["稳定性历史修复汇总<br/>release-notes<br/>⚠️ 命中=历史缺陷"]:::ver
    end
    subgraph SRC["变更来源判定"]
      S1["RNOH 自研修复<br/>鸿蒙原生模块<br/>✅ 升级即解"]:::own
      S2["RN 上游变更<br/>三端一致<br/>⚠️ 需适配代码"]:::up
    end
    subgraph CFG["配置与构建层（高发假象区）"]
      C1["源码↔release 构建<br/>folly/hermes/autolinking"]:::warn
      C2["bundle 缓存<br/>FileJSBundleProvider"]:::warn
      C3["codegen 产物路径<br/>--ets-output-path"]:::warn
      C4["release 混淆<br/>方法名改写"]:::warn
    end
    V1 --> S1
    V1 --> S2
    V1 -.配置未同步.-> C1
    V1 -.配置未同步.-> C2
    V1 -.配置未同步.-> C3
    V1 -.配置未同步.-> C4
    classDef ver fill:#dbeafe,stroke:#3b82f6
    classDef own fill:#dcfce7,stroke:#16a34a
    classDef up fill:#fef3c7,stroke:#d97706
    classDef warn fill:#fee2e2,stroke:#dc2626

分叉高发区说明：

层高发模式排查动作
版本边界低版本偶现、高版本不复现查稳定性修复汇总，锁定修复落地版本
变更来源上游引入的 API/类型/时序变更查上游不兼容变更表，确认三端是否一致
构建模式切 release 后链接/头文件/系统库报错按 三方库Release配置FAQ.md 补齐 CMakeLists
产物缓存装新 HAP 行为不变清 FileJSBundleProvider 设备缓存 + .cxx/oh_modules
混淆release 后 undefined 崩溃升级含修复版本或调混淆保留规则

附录 B：判定流程图（完整版）

flowchart TB
    A["升级/换版后行为变化或历史崩溃"] --> B{"稳定性修复汇总/<br/>release-notes 命中?"}
    B -->|"是"| C["历史缺陷<br/>→ 升级到含修复版本"]
    B -->|"否"| D{"命中上游不兼容变更/<br/>三端一致?"}
    D -->|"是"| E["上游不兼容变更<br/>→ 按上游 PR 适配代码"]
    D -->|"否"| F{"构建模式/依赖路径/<br/>产物/混淆 变化?"}
    F -->|"是"| G["配置与构建错配<br/>→ 修正工程配置"]
    F -->|"否"| H["转入通用缺陷定位"]
    C --> C1["指明修复落地版本 + 升级三处版本号"]
    E --> E1["指明变更来源版本 + 上游 PR + 改动文件"]
    G --> G1["指明修改文件 + 清缓存 + 对齐配置"]

附录 C：版本号与代码引用格式约定

  • 版本线：0.72.x / 0.77.x / 0.82.x / 0.84.x（x 为鸿蒙化迭代序号）
  • 稳定版：0.XX-stable（npm dist-tag，随迭代前移，不锁版本号）
  • 历史缺陷引用：修复落地版本号 + 稳定性修复汇总条目 + commit/MR 链接
  • 上游变更引用：变更来源版本 + 上游 PR/commit
  • 本仓库源码标注 [源码]，在线文档标注 [在线源码]，未读标注 [待确认]，绝不编造

附录 D：相关资料

  • 版本关系：RNOH 与 RN 版本关系 — 版本号命名规则、固定版本采用策略、开发者协同建议
  • 版本升级指导：[在线源码] docs/zh-cn/05-运维/版本升级指导.md — 小版本升级、大版本升级（0.72→0.77→0.82→0.84）依赖与配置改动
  • 版本说明：[在线源码] docs/zh-cn/05-运维/版本说明.md — dist-tag 命名、稳定版安装、实时查询
  • 上游不兼容变更：[在线源码] docs/zh-cn/05-运维/上游社区不兼容变更.md — 22 条上游变更的影响与适配
  • 稳定性历史修复：[在线源码] docs/zh-cn/05-运维/稳定性历史修复/{0.72,0.77,0.82}稳定性修复汇总/ — 按版本线分类的历史崩溃/冻屏/内存/资源修复
  • release-notes：[在线源码] docs/zh-cn/05-运维/release-notes/ — 0.84 系列逐迭代 Added/Fixed
  • 三方库 Release 配置 FAQ：三方库 Release 配置 FAQ — 源码↔release 切换的 C++ 编译链接错误根因与解决
  • 运行类 FAQ：[在线源码] docs/zh-cn/03-调测/运行类FAQ.md — 启动闪退、libRNOHApp is undefined、codegen record 找不到
  • 稳定性问题定位：[在线源码] docs/zh-cn/03-调测/RNOH应用稳定性问题定位指南.md — 内存泄漏/卡死/崩溃的日志与符号化方法
  • AI 辅助问题定位：[在线源码] docs/zh-cn/05-运维/AI辅助问题定位指导.md — 借助 AI 结合堆栈与版本号快速获得根因
  • OpenHarmony 运行 RN 应用：OpenHarmony 运行 RN 应用 — 开发板版本差异与版本专属 patch
  • 配套指南：黑屏白屏与渲染异常定位指南 · 三端不一致定位指南
# 鸿蒙问答专区 # react native
Logo
开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

Windows 上开发 React Native iOS App，用 KXBuild 连接 iPhone 真机跑 Metro、Fast Refresh 和原生断点

在 Windows 上开发 React Native iOS App 的全流程：用 KXBuild 的模板或社区 CLI 新建项目、体检、在 ios 目录 pod install，接上 iPhone 按 F5，Metro 加载 JS、保存即 Fast Refresh 热更，Swift/OC 原生代码也能断点，已有的 xcodebuild 脚本原样兼容，最后用 Release 配置打出可上架 ipa

avatar 开源鸿蒙跨平台开发者社区

RNOH 黑屏白屏与渲染异常定位指南

RNOH 应用启动白屏/黑屏、组件渲染异常、运行期冻屏的排查方法论与定位指南 在 RNOH 开发中，"应用一片白/黑""组件不显示或显示错""滑动一会就卡死"是最常见、也最易误判的问题类型之一。本文档给出从现象到根因、从分类到处置的系统化定位方法。 一、问题概述 1.1 什么是"黑屏、白屏、渲染异常" RNOH 的渲

avatar 开源鸿蒙跨平台开发者社区

RNOH 历史版本问题定位大全

RNOH 版本升级、跨版本迁移与历史缺陷回溯的排查方法论与定位指南 在 RNOH 开发中，"升级到新版本后行为变化""同一代码在不同 RNOH 版本表现不一""历史崩溃在低版本偶现"是最容易误判的问题类型之一。本文档给出从现象到根因、从分类到处置的系统化定位方法。 一、问题概述 1.1 什么是"历史版本问题" RNO

avatar 开源鸿蒙跨平台开发者社区