CI/CD / DevOps

2026 HarmonyOS NEXT RN 迁移上线前怎么验收?

获胜者:分层验收,而不是“能编译、能打开”验收。 只要核心链路、原生模块、长列表交互、设备兼容或发布材料中有一项无法稳定回归,就不应直接全量切换;应根据风险保留双轨、先做灰度,或延后发布。

最后更新于 2026 年 9 月 23 日,工具链与适配信息核实自官方升级指南、版本说明、性能诊断文档及 OpenHarmony-SIG 的 React Native 仓库。

这篇内容适合三类人:发布负责人用它判断项目是否具备提测、灰度或正式发布条件;测试负责人用它把 RN 页面、鸿蒙原生能力和设备差异变成可执行用例;前端与客户端负责人则可以据此定位问题究竟来自社区分支、三方库、ArkTS 改造,还是构建工具链。

先锁定验收口径

HarmonyOS NEXT RN 迁移上线前,第一件事不是继续修页面,而是写清本次交付到底验收什么。以下三种目标不能混用:

  • RN 容器可发布:主要验证现有 JavaScript 业务、路由、网络、存储和基础原生模块能否在目标环境运行。
  • 局部 ArkTS 重写:除 RN 页面外,还要验证 RN 页面与 ArkTS 页面之间的路由、状态、权限和返回行为。
  • 全量原生化:验收对象已经不只是 React Native for OpenHarmony 工程,还包括 ArkTS 页面、ArkUI 组件、原生模块和新的发布链路。

官方升级适配资料明确要求同步关注 DevEco Studio、SDK、命令行工具、API 行为变化,以及 HAR、HSP 等三方依赖;因此“同一份代码在开发机打开过”不能替代可复现的构建证据。HarmonyOS 应用升级适配指南

发布负责人应在验收单上提前写出:

  • 必须上线的核心用户链路;
  • 本次暂不迁移的页面;
  • 允许保留的已知问题;
  • 每个问题的责任人、关闭条件和证据位置;
  • 发生失败时回退到 RN 版本、继续双轨,还是暂停迁移。

如果这些边界没有形成书面记录,团队很容易把“页面能打开”误认为“项目已交付”,最后却在登录、支付、推送、文件上传或后台恢复阶段暴露阻断问题。

发布负责人的工程基线

工程基线的目标,是证明任何成员或流水线都能用同一套工具复现同一类产物,而不是只证明某台开发机成功过一次。

版本与工具链

验收前应固定并记录以下信息:

  • HarmonyOS NEXT 系统版本与目标 API;
  • DevEco Studio 版本;
  • HarmonyOS SDK 与 compatibleSdkVersion、targetSdkVersion;
  • 命令行工具、Hvigor、ohpm 和 JDK 信息;
  • RN 鸿蒙化分支、提交号及项目自维护补丁;
  • 本地 IDE 构建命令与流水线构建命令;
  • Debug、Release、灰度候选包的文件名和校验值。

官方资料说明,开发套件与命令行工具需要保持匹配,尤其是流水线构建不能继续使用旧版命令行工具;否则本地构建通过、流水线构建失败,或者两边生成的产物行为不同。命令行工具说明

如果项目正在跟随 API 版本升级,还应运行 DevEco Studio 的 API Change Assistant,导出扫描结果并绑定到代码位置。它能帮助定位 ArkTS API 或 C API 的行为变化,但不能替代真实设备回归。API 版本与升级说明

构建与交付产物

验收时不能只构建 Debug 包。至少要分别确认:

  • Debug 包能够安装、启动和调试;
  • Release 包能够完成签名、安装和核心链路回归;
  • 依赖的 HAR、HSP、资源和 native 产物没有遗漏;
  • 混淆、压缩、日志开关和环境配置符合发布要求;
  • 产物由本地 IDE 与流水线各构建一次,并比较关键日志;
  • 包内模块的 releaseType、API 相关配置和签名信息保持一致。

如果出现 HAP 安装失败,不能只重复安装。应核对设备 API 与工程 compatibleSdkVersion;官方排障资料也建议使用设备命令查询 API 版本,再与工程配置进行比对。设备 API 与 HAP 兼容排障

前端负责人的分支与三方库核对

React Native for OpenHarmony 不能被默认当作 React Native 官方主线的同等实现。前者属于 OpenHarmony 社区维护内容,项目还可能叠加公司自维护补丁;这三层代码必须分开登记:

  1. React Native 主线依赖与 JavaScript 代码;
  2. React Native for OpenHarmony 社区分支;
  3. 项目自行修改的 C++、NAPI、ArkTS 或 native module 代码。

社区仓库的标签和文档会记录具体鸿蒙化版本及其基础版本。例如仓库历史标签中曾出现基于 React Native 0.72.5 的鸿蒙化版本,这类信息只能作为项目依赖核对线索,不能推导出官方主线已经具备相同能力。OpenHarmony 社区仓库标签

三方库建议按照以下四类记录,而不是简单写成“已适配”:

  • ✅ 可直接复用:安装、调用、异常处理和 Release 构建都已验证;
  • ⚠️ 需要替换:接口名称相近,但底层能力或权限模型不同;
  • ❌ 必须重写:依赖 Android、iOS 专属实现,或依赖未提供的 native module;
  • ⏸ 暂不可用:没有稳定维护分支,或关键能力无法形成回归证据。

重点检查导航、手势、异步存储、网络、推送、图片、地图、文件、支付和埋点模块。每个存在风险的原生模块,都应保留一个最小复现工程或独立构建日志;否则主工程失败时,团队无法判断是业务代码、社区分支还是模块封装导致的问题。

提醒: 如果一个三方库只在 Debug 模式下能调用,或者必须手动修改生成目录后才能构建,它不应被标记为“可发布”,最多只能标记为“待灰度验证”。

测试负责人的核心链路回归

发布验收的执行方式

发布验收应围绕真实用户链路,而不是把页面逐个点一遍。建议至少覆盖:

  • 登录、退出和登录态恢复;
  • 首页首屏加载与接口失败;
  • 列表分页、下拉刷新和空数据;
  • 表单校验、提交失败和重复点击;
  • 文件选择、上传中断和重试;
  • 支付或业务关键动作;
  • 推送唤起、深链跳转和权限拒绝;
  • 后台切前台、锁屏恢复、进程重启。

RN 页面、ArkTS 页面和混合页面应分别验证路由进入、返回栈、状态恢复、权限申请、网络切换、后台恢复与进程重启。特别是混合页面,最容易出现 RN 状态仍然存在,但 ArkTS 页面已经重新创建,或者返回后重复请求、重复订阅和重复渲染。

每条失败用例都应绑定以下证据:

  • 设备型号与系统/API;
  • 构建产物名称和构建模式;
  • 分支、提交号或补丁版本;
  • 前置条件与完整复现步骤;
  • 截图、hilog、崩溃日志或 trace 位置;
  • 复现次数、回归结果和责任人。

原生模块与三方库核验

原生模块不能只验证“接口能返回数据”,还应覆盖权限拒绝、超时、进程重启、后台恢复、重复调用和异常回调。对于图片、地图、文件或推送模块,还要验证 Release 包中的资源、签名、权限声明和 native 依赖是否完整。

DevEco Studio 的工程结构、构建方式、签名和调试能力在 HarmonyOS 与 OpenHarmony 场景中存在差异,团队必须根据实际目标环境核对工程类型,不要把 OpenHarmony 文档中的默认行为直接套到 HarmonyOS NEXT 发布项目中。开发工具能力与工程差异说明

性能负责人的场景化验收

ArkTS 改造后,不能只拿一个 FPS 数字判断页面是否合格。首屏、页面切换、输入响应、图片加载、动画和长列表分别对应不同的用户感知问题,应分别建立基线和证据。

ArkTS 改造后的长列表检查

对于 ArkUI 的 List、Grid、Scroll、WaterFlow,需要明确页面使用的是 LazyForEach、NodeAdapter、组件复用方案,还是其他实现。验收记录至少要说明:

  • 数据更新时是否重复创建节点;
  • 离屏节点是否能够释放或复用;
  • 分页追加时是否出现跳动、白屏或重复数据;
  • 图片加载是否阻塞滚动;
  • 预加载和测量是否在快速滑动时形成连续耗时;
  • 空数据、错误重试和刷新状态是否破坏列表结构。

官方性能工具的滑动场景目前针对 ArkUI 的 List、Grid、Scroll、WaterFlow 等组件,并能够输出 FPS、响应时延、卡顿率、最大连续丢帧和 trace;但官方同时提示,这些指标与端到端用户感知并不完全等价,不能把某一个数字当成整页性能结论。SmartPerf 场景化采集说明

ArkUI 性能排障资料还把 LazyForEach predict、List predict、Preload FlowItem 和 H:ExecuteJS 等 trace 线索分别对应到预加载、测量布局和业务逻辑耗时。对于 RN 与 ArkTS 混合页面,尤其要确认 JS 执行、NAPI 回调、同步调用是否挤占渲染窗口。ArkUI 滑动卡顿定位说明

性能证据的合格形式

一次合格的性能验收应同时保留:

  • 固定数据量、图片规格和网络条件;
  • 首屏、切换、滑动、输入和动画的操作脚本;
  • 设备、系统/API、构建模式和提交号;
  • SmartPerf 或其他官方工具导出的结果;
  • trace 文件及关键耗时泳道;
  • 优化前后相同场景的对比;
  • 不能归因时的“暂不放行”结论。

如果团队使用 WaterFlow,不能因为组件名称变化就默认性能问题已经解决;具体效果仍取决于页面结构、数据更新方式和子组件复杂度。

运维与设备矩阵

设备覆盖不宜按“手上有什么设备”决定,而应按企业真实用户占比和风险场景决定。至少应区分主流目标设备、低资源设备、横竖屏差异、分辨率差异,以及权限和后台策略不同的环境;每次验收都要保留设备清单,不能只写“真机已测”。

发布材料还应逐项核对:

  • 签名文件、证书和包名;
  • 权限声明与运行时授权;
  • HAR、HSP、资源和 native 依赖;
  • 混淆、压缩和日志开关;
  • Release 构建产物与校验值;
  • 本地 IDE 和流水线的工具链;
  • 灰度范围、问题收集入口和版本追踪方式;
  • 回滚包、回滚条件与双轨入口。

签名并不是构建末尾的形式步骤。自动签名资料指出,系统时间、注册应用、设备信息和权限配置都可能影响签名结果;因此签名配置也应作为验收证据保存,而不是由个人电脑临时生成后直接交付。自动签名说明

一页式放行清单

下面的清单适合直接复制到项目验收单。每一项都应填写负责人、证据位置和结论,不能只勾选“已完成”。

工程与分支

  • [ ] 已写明本次是 RN 容器发布、局部 ArkTS 重写还是全量原生化。
  • [ ] 已锁定 DevEco Studio、SDK、API、命令行工具、Hvigor、ohpm 和 JDK。
  • [ ] 已记录 React Native 主线、React Native for OpenHarmony 分支和项目补丁。
  • [ ] 已通过 API Change Assistant 检查关键 API 行为变化,并保存导出结果。
  • [ ] Debug 与 Release 均完成构建、安装和启动验证。
  • [ ] 本地 IDE 与流水线使用同一套工具链,并保留构建日志。

功能与原生能力

  • [ ] 登录、首页、列表、表单、上传和关键业务动作均完成端到端回归。
  • [ ] RN、ArkTS、混合页面均验证路由返回、状态恢复和进程重启。
  • [ ] 权限拒绝、网络异常、后台切前台和重复操作均有用例。
  • [ ] 导航、手势、存储、网络、推送、图片、地图和文件库已分类标记。
  • [ ] 每个失败用例都绑定设备、API、产物、分支、日志和复现步骤。

性能与稳定性

  • [ ] 已建立首屏、页面切换、输入、动画、图片和长列表场景。
  • [ ] 已说明 List、Grid、WaterFlow 或其他列表实现及复用策略。
  • [ ] 已保存性能工具结果、trace 和关键耗时泳道。
  • [ ] 已检查重复创建、离屏释放、分页追加和图片加载阻塞。
  • [ ] 没有用单一 FPS 数字抵消输入延迟、切换卡顿或崩溃问题。

发布与回退

  • [ ] 已核对签名、权限、资源、HAR/HSP、混淆和日志开关。
  • [ ] 已完成主流、低资源、横竖屏或分辨率差异设备覆盖。
  • [ ] 已生成灰度包、回滚包和版本追踪记录。
  • [ ] 已明确阻断发布、核心体验问题、可接受缺陷和文档补齐四类问题。
  • [ ] 已形成“正式发布、灰度、继续双轨、暂停迁移”四选一结论。

用验收结论决定是否切换

验收结论不应按通过项数量计算,而应按关键链路和风险等级判断:

  • 正式发布:核心链路稳定回归,发布材料完整,设备和性能证据闭环。
  • 灰度发布:非核心缺陷已隔离,回滚条件明确,社区库或临时补丁仍有监控。
  • 继续双轨:RN 版本仍是稳定兜底,部分 ArkTS 页面或原生模块尚未形成可靠证据。
  • 暂停迁移:登录、支付、上传、推送、核心列表或启动稳定性存在无法回归的问题。

如果当前方案依赖一台难以复现的开发机、手工修改后的构建目录,或本地与流水线不一致的 DevEco Studio、SDK 环境,继续把问题留到正式发布阶段,通常比保留双轨更昂贵。对于需要稳定复现工具链、远程构建或临时扩充验证环境的团队,先查看 KuzCloud 帮助中心,再根据持续时间和设备协作方式参考 KuzCloud 的方案说明;租赁 Mac 体验更适合短期验收、灰度前复测和跨成员复现,不一定适合长期固定重负载或必须接入特定物理设备的团队。

上线验收前,先用 KuzCloud 补齐真实 Mac 测试环境

通过 KuzCloud 远程 Mac 快速完成编译、安装、启动与核心流程验证,减少本地环境差异带来的遗漏。

需要复现兼容性、性能或稳定性问题时,随时开通可远程操作的 Mac,测试资源不再受设备数量限制。