2026 HarmonyOS NEXT RN 이전 출시 전 어떻게 검수할까?
빌드는 끝났지만 출시 빌드에서 로그인과 파일 업로드가 다시 실패하고, 긴 목록 화면은 실제 기기에서만 끊깁니다.
가장 빠른 해결책은 “실행 가능”을 합격으로 보지 않는 것입니다. HarmonyOS NEXT RN 이전 검수는 빌드, 핵심 흐름, 네이티브 기능, ArkTS 화면 성능, 기기 호환성, 출시 자료를 나누어 진행해야 하며, 핵심 흐름을 재현하지 못하면 이중 운영을 유지하거나 전체 전환을 미뤄야 합니다.
이 글은 출시 조건을 판단해야 하는 배포 책임자, 테스트 책임자, 프런트엔드와 클라이언트 책임자를 위한 안내입니다. React Native for OpenHarmony 분기와 팀 자체 수정 코드 때문에 실패 원인을 분리하기 어려운 경우에도 적용할 수 있습니다.
마지막 확인일은 2026년 9월 23일입니다. 도구와 에이피아이 관련 내용은 하모니오스 공식 이전 적응 안내, 개발 도구 버전 안내, 에이피아이 변경 안내를 기준으로 확인해야 합니다.
출시 범위와 도구 환경
출시 책임자는 검수 전에 완료의 의미를 한 문장으로 고정해야 합니다. RN 컨테이너를 배포하는 단계인지, 일부 화면만 ArkTS로 다시 작성하는 단계인지, 전체 원생화를 끝내는 단계인지 섞으면 보고서의 합격 판정이 무의미해집니다.
다음 항목은 회의에서 말로 합의하지 말고 문서에 남겨야 합니다.
- [ ] 이번 배포에 포함되는 RN 화면과 ArkTS 화면을 분리해 적습니다.
- [ ] 아직 이전하지 않는 화면과 그 사유를 적습니다.
- [ ] 로그인, 첫 화면, 목록 조회, 제출, 업로드처럼 반드시 성공해야 하는 흐름을 지정합니다.
- [ ] 각 흐름에 책임자, 테스트 증거, 허용되는 결함을 연결합니다.
- [ ] 하모니오스 넥스트, 대상 에이피아이, 데베코 스튜디오, 명령줄 도구, RN 커뮤니티 분기의 조합을 고정합니다.
- [ ] 디버그와 출시 빌드가 같은 의존성 및 설정을 쓰는지 확인합니다.
공식 안내는 개발 도구와 에스디케이, 에이피아이 변화, 하알과 에이치에스피 의존성을 함께 점검하도록 안내합니다. 명령줄 도구도 별도 설치 상태가 아니라 고정된 개발 환경의 일부로 관리해야 합니다. 관련 도구 사용 조건은 공식 명령줄 도구 안내에서 다시 확인할 수 있습니다.
프런트엔드 의존성과 네이티브 경계
React Native 공식 주 코드, React Native for OpenHarmony 커뮤니티 분기, 프로젝트 자체 패치는 서로 다른 책임으로 기록해야 합니다. OpenHarmony 커뮤니티 저장소의 태그와 문서는 공식 React Native 주 코드의 기본 기능을 보증하는 자료가 아니므로, 분기 상태는 커뮤니티 저장소 태그 목록에서 검수 시점에 확인해야 합니다.
특히 다음 기능은 화면이 열린다는 이유만으로 재사용 가능하다고 판단하면 안 됩니다.
- 라우팅과 뒤로 가기 처리
- 제스처와 애니메이션
- 보안 저장소와 일반 저장소
- 네트워크, 알림, 파일 접근
- 이미지 선택과 카메라
- 지도와 결제 같은 네이티브 모듈
- 권한 요청과 백그라운드 복귀
각 라이브러리는 그대로 사용, 대체 라이브러리 적용, 직접 수정, 출시 보류로 나누어야 합니다. 직접 수정한 모듈은 작은 재현 프로젝트나 빌드 로그를 남겨야 합니다. 그래야 커뮤니티 분기 업데이트 뒤에 같은 문제가 다시 발생했을 때 원인을 추적할 수 있습니다.
주의: 커뮤니티 분기의 동작을 공식 React Native의 기본 지원으로 소개하면 인수 이후 책임 범위가 흐려집니다. 보고서에는 사용한 분기, 커밋, 패치, 의존성 파일을 함께 보관해야 합니다.
테스트 흐름과 실패 증거
테스트 책임자는 페이지 단위가 아니라 실제 사용 흐름 단위로 사례를 구성해야 합니다. 로그인 화면이 열리는 것보다 로그인 뒤 토큰이 유지되는지, 첫 화면의 데이터가 표시되는지, 다음 페이지가 중복 없이 추가되는지가 더 중요한 검수 기준입니다.
RN 화면, ArkTS 화면, 혼합 화면은 각각 다음 상태를 확인해야 합니다.
- 앱을 처음 실행했을 때의 권한 요청
- 화면 이동과 뒤로 가기
- 백그라운드 전환 후 상태 복구
- 네트워크 차단과 재연결
- 앱 강제 종료 뒤 재실행
- 세션 만료와 재로그인
- 업로드 중 화면 이탈
- 화면 회전이나 해상도 차이
- 프로세스가 종료된 뒤 임시 데이터의 처리
실패 기록에는 기기 이름만 적어서는 안 됩니다. 시스템과 에이피아이 조합, 빌드 산출물, 사용한 분기와 커밋, 재현 절차, 로그 위치, 예상 결과와 실제 결과를 함께 적어야 합니다. 기기 에이피아이와 하알 호환 문제는 공식 기기 호환 문제 안내를 기준으로 분류할 수 있습니다.
ArkTS 화면과 체감 성능
ArkTS로 바꾼 뒤에는 단일 프레임 수치 하나로 품질을 판정하면 안 됩니다. 첫 화면 표시, 화면 전환, 긴 목록 이동, 입력 반응, 애니메이션, 이미지 표시를 각각 장면으로 만들고 동일한 데이터 조건에서 비교해야 합니다.
List, Grid, WaterFlow를 사용했다면 다음 구현 정보가 필요합니다.
- 반복 렌더링에 어떤 지연 생성 방식을 사용했는지
- 데이터 변경 때 항목 식별자가 안정적인지
- 화면 밖 노드가 해제되는지
- 동일 항목이 반복 생성되는지
- 페이지 추가 중 스크롤 위치가 변하지 않는지
- 빈 상태와 오류 상태가 목록 갱신 뒤에도 유지되는지
- 큰 이미지가 목록의 주 스레드 작업을 막지 않는지
LazyForEach, 노드 어댑터 또는 다른 방식은 사용 조건이 다르므로 코드 이름만 적어서는 부족합니다. 공식 성능 안내도 슬라이딩, 프레임 손실, trace 수집, 지원 컴포넌트의 범위를 나누어 설명합니다. 따라서 스마트퍼프 장면 수집 안내와 아크유아이 끊김 진단 안내를 근거로 장면별 trace를 저장해야 합니다.
성능 검수의 합격 조건은 “빠르다”가 아니라 재현 가능해야 합니다. 같은 데이터, 같은 네트워크 조건, 같은 빌드 산출물로 다시 실행했을 때 동일한 현상이 나타나는지 확인하고, 도구의 측정값과 실제 입력 지연을 별도 항목으로 기록해야 합니다.
기기와 출시 자료
운영 책임자는 기업 사용자의 실제 분포를 기준으로 기기를 선택해야 합니다. 특정 기기 하나에서 통과했다는 결과로 전체 출시를 승인할 수 없습니다. 주력 기기와 자원이 제한된 기기, 화면 비율이나 방향이 다른 조건을 포함하고, 매 회차의 환경 목록을 보존해야 합니다.
| 검수 영역 | 확인할 증거 | 보류 조건 |
|---|---|---|
| 기기 조합 | 기기, 시스템, 에이피아이, 화면 방향 기록 | 핵심 사용자 비중이 큰 조합을 재현하지 못함 |
| 산출물 | 디버그와 출시 산출물의 해시 및 생성 로그 | 출시 빌드에서만 기능이 달라짐 |
| 의존성 | 하알, 에이치에스피, 네이티브 모듈 목록 | 출처와 버전이 잠기지 않음 |
| 서명과 권한 | 서명 설정, 권한 선언, 설치 로그 | 수동 설정에 의존함 |
| 자동화 | 로컬과 파이프라인의 도구 환경 | 서로 다른 에스디케이 또는 명령줄 도구 사용 |
| 운영 준비 | 회색 배포, 회수, 문제 접수, 버전 추적 문서 | 실패 시 이전 버전으로 돌아갈 경로가 없음 |
서명은 개발자의 로컬 상태에 의존하지 않아야 합니다. 자동 서명과 관련된 조건은 공식 자동 서명 안내에서 확인하고, 파이프라인에서도 같은 설정이 재현되는지 점검해야 합니다.
증거 기반 출시 판정
검수 결과는 통과 항목의 개수가 아니라 결함의 성격으로 판정해야 합니다. 핵심 로그인이나 결제 흐름이 재현되지 않는데 문서 보완 항목이 많이 끝났다는 이유로 출시할 수는 없습니다.
| 판정 | 적용 조건 | 다음 조치 |
|---|---|---|
| 출시 | 핵심 흐름과 출시 빌드가 재현되고, 남은 결함이 운영에 영향을 주지 않음 | 정식 배포 자료를 잠그고 버전을 추적합니다 |
| 회색 배포 | 핵심 흐름은 통과했지만 특정 기기나 커뮤니티 모듈에 제한이 있음 | 대상 범위, 중단 조건, 회수 절차를 문서화합니다 |
| 이중 운영 | 일부 화면이나 네이티브 기능의 회귀 검수가 불완전함 | RN 경로와 HarmonyOS 경로를 함께 유지합니다 |
| 이전 중단 | 핵심 흐름 실패, 서명 문제, 복구 경로 부재가 남아 있음 | 원인을 고친 뒤 검수 회차를 새로 시작합니다 |
하모니오스 넥스트 RN 이전 검수 기록에는 최소한 범위, 분기, 도구 환경, 기기 조합, 실패 로그, 성능 trace, 출시 산출물을 연결해야 합니다. 팀이 원격에서 같은 개발 환경을 재현해야 한다면 KuzCloud 원격 개발 환경도 비교 대상으로 검토할 수 있습니다. 다만 물리 장비 연결이나 장기간 고정 부하가 필요한 팀은 별도 장비 운영이 더 적합할 수 있습니다.
한 페이지 검수 체크리스트
- [ ] 출시 범위가 RN 컨테이너, 일부 ArkTS, 전체 원생화 중 하나로 고정되어 있습니다.
- [ ] 공식 주 코드, OpenHarmony 커뮤니티 분기, 자체 패치가 분리되어 있습니다.
- [ ] 데베코 스튜디오, 에스디케이, 에이피아이, 명령줄 도구의 조합이 잠겨 있습니다.
- [ ] 디버그와 출시 빌드에서 같은 핵심 흐름을 회귀했습니다.
- [ ] 네이티브 모듈과 서드 파티 라이브러리마다 사용 방식과 보류 사유가 있습니다.
- [ ] RN, ArkTS, 혼합 화면의 복귀와 상태 보존을 확인했습니다.
- [ ] 긴 목록, 입력, 애니메이션, 이미지 표시를 장면별로 측정했습니다.
- [ ] List, Grid, WaterFlow의 데이터 갱신과 지연 생성 동작을 기록했습니다.
- [ ] 주력 기기와 자원 제한 기기, 화면 차이 조건을 포함했습니다.
- [ ] 서명, 권한, 하알과 에이치에스피, 압축 설정, 로그 설정을 확인했습니다.
- [ ] 로컬 빌드와 파이프라인 빌드의 도구 환경이 같습니다.
- [ ] 회색 배포, 회수, 문제 접수, 버전 추적 절차가 있습니다.
- [ ] 핵심 흐름 실패를 다른 통과 항목으로 상쇄하지 않았습니다.
- [ ] 출시, 회색 배포, 이중 운영, 중단 중 하나의 결론과 근거가 있습니다.
결국 현재 방식이 로컬 데베코 스튜디오 환경과 개인별 패치에 묶여 있으면 재현성이 낮고, 출시 빌드 검증이 늦어지며, 팀이 같은 기기와 도구 조합을 맞추는 운영 부담도 커집니다. 반면 안정적인 원격 개발 환경을 임시로 확보하면 검수 기간에 필요한 도구와 빌드 흐름을 고정하기 쉬워집니다. 다만 장기 고정형 대규모 작업이나 물리 장비가 필요한 경우에는 직접 장비를 보유하는 편이 나을 수 있습니다. 출시 전 반복 검수나 단기 원격 빌드가 목적이라면 KuzCloud 환경 확인에서 필요한 운영 조건을 먼저 대조하는 편이 합리적입니다.
출시 전 검수에 필요한 맥 환경을 KuzCloud에서 준비하세요
원격 맥 환경에서 앱 빌드와 실행을 진행하며 출시 전 검수에 필요한 조건을 확인할 수 있습니다.
별도 장비를 준비하지 않아도 필요한 맥 환경에 원격으로 접속해 개발과 테스트를 이어갈 수 있습니다.