CI/CD / DevOps

2026 HarmonyOS NEXT RN 遷移上線前怎麼驗收?

獲勝者:分層驗收,而不是以「能編譯、能開啟」作為完成標準。 適用於準備提測、灰度或正式發布的 HarmonyOS NEXT RN 遷移專案;只要核心鏈路仍無法穩定回歸,就應保留雙軌方案或延後全量切換。

發布負責人可用本文判斷專案是否具備放行條件;測試負責人可把 RN 頁面、原生能力與裝置差異轉成可執行用例;前端與客戶端負責人則可定位問題究竟來自社群分支、三方套件、ArkTS 改造,還是建置工具鏈。

最後更新於 2026 年 9 月 23 日;工具鏈、API 與社群分支狀態核實自官方升級適配指南、API 版本說明及OpenHarmony React Native 儲存庫標籤。

先由發布負責人鎖定交付邊界

HarmonyOS NEXT RN 遷移驗收首先要回答的不是「畫面是否出現」,而是本次交付究竟驗證哪一種完成狀態:

  • RN 容器可以建置並發布,但部分頁面仍維持現有實作。
  • RN 與 ArkTS 混合運作,只有指定頁面或原生模組完成改造。
  • 主要使用者流程已切換至原生 ArkTS,進入全量發布前驗證。
  • 專案仍處於技術驗證階段,只能交付測試包,不能宣稱具備正式發布資格。

這些狀態的風險不同,不能共用一個「驗收通過」標籤。發布文件應列出必須上線的登入、首頁、列表、表單、上傳、支付或其他業務核心流程,同時標記暫不遷移頁面、已知缺陷、責任人、回歸證據與放行條件。

工具鏈也必須先鎖定。HarmonyOS 官方升級文件要求同步核對開發工具、SDK、API 變化與 HAR/HSP 依賴;若本機 IDE 可以建置,但命令列或流水線使用另一套 SDK,這只能算「局部可建置」,不能算可交付。命令列工具應依照官方工具說明固定來源與呼叫方式。

前端負責人先分開三層程式碼與套件責任

React Native 官方主線、React Native for OpenHarmony 社群維護分支,以及專案自行維護的補丁,必須在分支、鎖檔與建置紀錄中明確分層。社群分支的能力不能直接當成官方 React Native 主線的預設能力;其版本、提交狀態與文件應以OpenHarmony 社群儲存庫標籤逐次核對。

對每個原生模組與三方套件,建議採用以下四種狀態:

  • 可直接重用:已有適配版本,並在 Release 建置與目標裝置完成回歸。
  • 需要替換:原套件無法使用,已換成另一個實作,且功能、權限與錯誤處理均有證據。
  • 必須重寫:導航、手勢、儲存、推送、圖片、地圖或檔案能力依賴原生介面,需由 ArkTS 或原生模組重新完成。
  • 暫不可用:存在阻斷缺陷,不能以手動操作或測試環境特例掩蓋。

每個非直接重用的模組都應保留最小重現專案或建置日誌,並同時檢查 Debug 與 Release。Debug 通過而 Release 失敗,常見原因可能出現在混淆、壓縮、簽章、資源打包或 HAR/HSP 依賴,不應被歸類為「測試環境偶發問題」。

測試負責人按真實鏈路完成 React Native for OpenHarmony 發布驗收

React Native for OpenHarmony 專案的發布驗收,不應只逐頁點擊,而應以使用者能否完成任務作為最小單位。每條核心鏈路至少要能從入口走到結果頁,並覆蓋成功、失敗、重試與中斷後恢復。

建議按以下順序執行:

  1. 固定測試包、分支提交、建置環境與裝置資料,先確認測試對象沒有漂移。
  2. 驗證登入、首頁載入、列表分頁、表單送出、檔案上傳及業務關鍵動作的完整流程。
  3. 分別測試 RN 頁面、ArkTS 頁面與混合頁面的路由進入、返回、狀態保存與重建。
  4. 在權限首次申請、拒絕後重新申請、網路中斷、背景切回前景及程序重啟後重做關鍵操作。
  5. 對每個失敗案例記錄裝置、系統與 API、構建產物、分支版本、重現步驟及日誌位置。
  6. 將修復後的結果重新放回同一條鏈路回歸,不能只截取單一畫面證明「問題已解決」。

「鴻蒙 RN 遷移如何驗證原生模組和三方庫」的答案,核心在於功能閉環與失敗可回歸,而不是套件清單上出現一個綠色標記。涉及裝置 API 與 HAP 相容性時,應對照官方相容性排障說明檢查環境差異。

提醒: 如果某個原生模組只能在 Debug 模式或單一測試裝置上運作,驗收結論應寫成「條件式通過」或「阻斷發布」,不能用已通過的頁面數量抵銷核心流程失敗。

ArkTS 改造後把長列表與交互效能拆成場景驗證

「ArkTS 改造後如何驗收長列表和頁面效能」,不能只看一個 FPS 數字。至少要將首屏、頁面切換、列表滑動、輸入回應、動畫、圖片載入與網路回應拆成不同場景,為每個場景定義操作步驟、觀察指標、裝置條件與可接受的證據類型。

長列表要特別記錄實際採用的 ArkUI 元件與資料方式,例如 List、Grid 或 WaterFlow 是否搭配 LazyForEach、NodeAdapter 或其他方案,以及以下邊界:

  • 資料更新時是否重複建立節點;
  • 快速翻頁或重新整理時是否出現順序錯亂;
  • 離屏節點是否按預期釋放或重用;
  • 圖片載入、空資料、錯誤重試是否造成頁面阻塞;
  • RN 與 ArkTS 之間傳遞大量資料時,是否讓 JS 執行緒與 UI 執行緒互相等待。

效能證據應使用官方診斷工具匯出的 trace,而不是只拍攝螢幕或人工描述「滑起來很順」。SmartPerf 官方指南說明了場景化採集方式;ArkUI 滑動卡頓排查文件則可用來核對元件支援與指標定義。端到端感知延遲、單一元件指標與整頁滑動結果,必須在報告中分開呈現。

交付與運維負責人以裝置、簽章和回滾證據放行

裝置矩陣不應追求形式上的數量,而應反映企業實際使用者組成與高風險差異。至少要納入主流目標裝置、資源較受限的裝置、不同螢幕方向與解析度情境,並在每次驗收保存系統、API、裝置、測試包與結果。

發布材料需逐項核對:

  • 簽章、權限、配置檔與資源是否來自正式建置設定;
  • HAR/HSP 依賴是否被正確打包,沒有只存在於本機快取;
  • 混淆、壓縮、日誌開關與錯誤上報設定是否符合發布要求;
  • 本機 IDE 建置與流水線建置是否使用同一套工具鏈;
  • 最終 HAP 或其他產物是否能依雜湊或版本資訊追溯;
  • 灰度範圍、問題收集、回滾條件與版本追蹤文件是否已準備。

簽章不能只依賴某位開發者的本機狀態;可參考官方自動簽章說明,再確認流水線是否能以可追蹤方式產生發布產物。若仍依賴未穩定的社群套件或臨時補丁,文件中必須明確標記,不應藏在「已驗收」結論後面。

用一頁式清單決定發布、灰度或雙軌

以下清單可直接複製到專案驗收文件;每一項都應附上負責人與證據位置,而不是只勾選完成狀態。

  • [ ] 已寫明本次是 RN 容器發布、混合頁面交付,還是全量原生化。
  • [ ] 已列出必須上線流程、暫不遷移頁面、已知問題與回退條件。
  • [ ] HarmonyOS NEXT、目標 API、DevEco Studio、命令列工具與 RN 社群分支已鎖定。
  • [ ] React Native 主線、React Native for OpenHarmony 與專案補丁已分開記錄。
  • [ ] 導航、手勢、儲存、網路、推送、圖片、地圖等套件已有適配分類。
  • [ ] 所有核心鏈路已完成成功、失敗、重試、背景切換與程序重啟回歸。
  • [ ] RN、ArkTS 與混合頁面均已驗證路由、權限及狀態恢復。
  • [ ] 長列表、輸入、動畫、圖片與頁面切換已有場景化效能證據。
  • [ ] WaterFlow、List 或 Grid 的資料更新與離屏節點行為已有紀錄。
  • [ ] Debug 與 Release 均已建置,並保存產物、日誌與提交版本。
  • [ ] 目標裝置矩陣、簽章、權限、HAR/HSP、壓縮與流水線產物均已核對。
  • [ ] 已完成灰度、回滾、問題收集與版本追蹤方案。
  • [ ] 每個缺陷已分類為阻斷發布、影響核心體驗、可接受缺陷或文件補齊。
  • [ ] 每一個放行結論都有可重做的證據,而不是只有測試人員口頭確認。

放行頁面最後只保留四種結論:發布、灰度、繼續雙軌、暫停遷移。阻斷核心登入、資料提交、支付或主要業務動作的缺陷,不得用其他通過項目抵銷;只有文件缺漏或不影響核心體驗的問題,才可在明確期限與責任人下帶缺陷發布。

現有本機工作站或臨時遠端桌面若存在工具版本不一致、SDK 快取各自獨立、流水線無法重現、連線不穩定或裝置借用受限等問題,驗收報告就可能把環境差異誤判成程式缺陷;相比之下,當團隊需要反覆重建 DevEco Studio、SDK 與流水線環境時,KuzCloud 的雲端 Mac 租用方案更適合用作可控的遠端驗證節點,但前提是目標工具鏈已確認可在該環境運作,且專案並非必須長期持有實體裝置或進行高負載常駐工作。

需要準備驗收環境的團隊,可先把本文清單另存為「遷移驗收欄位模板」,再透過 KuzCloud 使用說明確認遠端環境管理方式;若要查看可用的執行與管理入口,可使用 KuzCloud 控制台。升級 DevEco Studio 或 API 後,應以同一份裝置矩陣、建置紀錄與效能 trace 重新驗證,而不是直接沿用上一輪的「已通過」結論。

用 KuzCloud 遠端 Mac,完成 HarmonyOS NEXT RN 上線前驗收

透過 KuzCloud 雲端 Mac 建立穩定的測試環境,逐項驗證建置、功能及原生模組整合。

讓發布、測試與前端團隊可彈性連線,協作進行回歸測試、問題重現及版本確認。