CI/CD

2026 HarmonyOS PC: Electron 네이티브 플러그인 이전 전 확인 사항

먼저 내릴 결론: 재사용할 것은 업무 로직입니다

Electron IPC는 공식 문서에서 메인 프로세스와 렌더러 프로세스 사이의 통신으로 설명됩니다. 이 경계를 그대로 옮길 수는 없습니다. Electron IPC 안내가 다루는 두 프로세스 구조와 HarmonyOS PC의 앱 구조는 별개이므로, HarmonyOS PC Electron 마이그레이션의 우선순위는 IPC와 업무 로직을 분리하고, 시스템 기능을 공식 API와 목표 개발 환경에서 하나씩 검증하는 것입니다. HarmonyOS PC 앱 개발 안내가 제공되더라도, 해당 안내에 없는 SDK 기능이나 하드웨어 지원까지 추정해서는 안 됩니다.

Electron 아키텍트는 기존 네이티브 플러그인의 이전 범위와 교체 비용을 산정할 때 참고할 수 있습니다.
크로스 플랫폼 개발팀은 다른 데스크톱 운영체제나 Node.js에서 통했던 동작을 새 플랫폼의 지원 사실로 간주하지 않도록 점검할 수 있습니다.
기술 책임자는 검증 결과에 따라 진행할 기능과 보류할 기능을 구분할 수 있습니다.

마지막 확인: 2026년 10월 15일. 확인 자료는 HarmonyOS PC 개발 안내, ArkTS Runtime 개요, Node-API 객체 연결 안내입니다. 출시 일정이나 이주 도구의 제공 여부는 이 문서들만으로 확정하지 않습니다.

이전 전: 플러그인 이름보다 호출 계약을 기록합니다

Electron 네이티브 플러그인은 파일 이름만 훑어서는 이전 규모를 알기 어렵습니다. 같은 플러그인도 IPC 호출자가 누구인지, 어떤 값을 주고받는지, 운영체제 기능에 직접 의존하는지에 따라 분리 방법이 달라집니다. Electron 안내는 네이티브 모듈이 대상 Electron 환경에 맞도록 다시 빌드해야 할 수 있음을 설명합니다. 따라서 기존 바이너리가 다른 플랫폼에서 작동했다는 사실은 HarmonyOS PC에서 쓸 수 있다는 근거가 아닙니다. Electron 네이티브 모듈 안내를 기준으로 Electron 버전과 빌드 대상 플랫폼, 아키텍처 의존성을 기록한 뒤 새 플랫폼의 SDK 지원 여부를 별도로 확인합니다.

선택지 남길 수 있는 부분 이전 전에 확인할 조건 판단
공유 업무 계층 플랫폼 API를 호출하지 않는 규칙과 데이터 처리 Node.js 또는 Electron 전용 기능에 묶여 있지 않은지 의존성을 분리해 재사용 검토
플랫폼 어댑터로 교체 IPC 진입점과 파일·카메라 같은 시스템 기능 연결 HarmonyOS PC용 공식 API와 권한 흐름이 문서화되어 있는지 대상 SDK에서 확인한 뒤 구현
검증 대기 DLL·SO, 기기 접근, 비공개 API에 기대는 기능 대응 인터페이스와 디버깅 환경을 실제로 쓸 수 있는지 확인 전까지 미지원으로 기록

목록에는 기능별로 호출 주체, 입력과 반환값, 오류 유형, 비동기 여부, 스레드 동작, 운영체제 호출과 자원 해제 방식을 적습니다. 파일 접근, 시스템 정보 조회, 카메라는 이름만 보고 지원 여부를 표시하지 않습니다. HarmonyOS PC의 파일 권한과 하드웨어 API는 목표 버전 공식 문서에서 확인해야 합니다. 다른 데스크톱 운영체제의 권한 모델을 적용해 추론하지 않습니다.

Electron의 Node.js 네이티브 플러그인을 그대로 사용할 수 있나요?
그렇게 전제하면 안 됩니다. Electron용 플러그인이 기대하는 Node.js 런타임, ABI, 운영체제 인터페이스가 목표 환경에 그대로 존재한다고 볼 근거가 없습니다. 코드 일부를 공유할 수 있는지는 기능 단위로 판단하고, 각 플랫폼 호출은 별도 어댑터 뒤에 둡니다.

인터페이스 분리: IPC 이름보다 입력과 실패 상태를 먼저 고정합니다

읽을 파일을 선택하는 기능을 예로 들면, 업무 계층은 “사용자가 선택한 파일을 읽는다”는 계약만 알도록 설계합니다. 계약에는 요청에 필요한 정보, 성공 시 반환할 데이터, 취소·권한 거부·읽기 실패의 구분, 결과를 받는 비동기 방식이 포함되어야 합니다. 실제 파일 선택 화면이나 경로 접근은 플랫폼 어댑터의 책임으로 둡니다.

이 구조에서는 기존 Electron 구현을 유지하면서 새 플랫폼 구현을 별도로 추가할 수 있습니다. 렌더러와 메인 프로세스가 나뉘어 있다는 이유만으로 HarmonyOS PC의 컴포넌트 경계를 같은 모양으로 복제하지 않습니다. 플랫폼의 앱 구조와 공식 시스템 API를 확인하기 전까지는 업무 계약을 안정된 층으로 삼습니다.

Electron IPC를 ArkTS로 옮기기 전에 무엇을 분리해야 하나요?
IPC 호출 자체, 업무 규칙, 파일 선택 등 운영체제 기능을 구분합니다. 호출자가 화면 코드에 흩어져 있다면 계약을 한곳에 모으고, 입력·반환값·오류·취소 처리까지 명시합니다. 그다음 기존 Electron 어댑터와 신규 플랫폼 어댑터가 같은 업무 계약을 구현하도록 구성합니다.

연결 단계: 확인된 C/C++ 기능만 Node-API로 감쌉니다

ArkTS Node-API를 검토할 때는 ArkTS 런타임, Node-API, 시스템 API를 같은 것으로 취급하지 않아야 합니다. ArkTS Runtime 개요는 런타임과 언어 환경을 설명하고, Node-API 객체 연결 예제는 C/C++ 객체를 연결하는 방법을 보여 줍니다. 이 문서를 토대로 대상 SDK의 모듈 등록 방식, 인수와 반환값 변환, 오류 전달, 객체와 네이티브 자원의 수명을 확인합니다.

구현 검토는 다음 순서로 진행합니다.

  • 대상 SDK에서 해당 Node-API 기능과 모듈 등록 절차가 지원되는지 확인합니다.
  • C/C++ 함수의 입력값 검증과 반환값 변환 규칙을 정합니다.
  • 네이티브 오류를 호출 계층이 처리할 수 있는 오류로 변환하고, 취소와 비동기 결과도 계약에 반영합니다.
  • 객체를 보관하는 경우 생성·사용·해제 시점을 정하고 반복 호출과 오류 경로에서 누수가 없는지 점검합니다.
  • 목표 개발 환경에서 빌드하고, 설치 후 실제 장치나 공식 지원 디버깅 환경에서 호출을 확인합니다.

이 절차는 개념 설계를 위한 것이며, 특정 SDK에서 그대로 실행되는 코드 예제가 아닙니다. 대상 SDK와 빌드 환경에서 확인하지 않은 코드를 완성된 구현으로 제시하면 안 됩니다. Node-API는 임의의 Node.js 확장이나 시스템 DLL·SO를 자동 변환해 HarmonyOS PC에서 작동시키는 도구가 아닙니다.

플랫폼 확인: 파일과 카메라는 서로 다른 권한 경로로 시험합니다

파일 선택은 파일 경로를 직접 읽는 방식과 시스템 선택기를 이용하는 방식이 같은 권한 동작을 한다고 가정하지 않습니다. 시스템 Picker 안내에서 대상 환경의 선택기와 접근 방식을 확인하고, 사용자가 선택한 항목만 읽는 경우의 권한 범위도 해당 문서로 검증합니다. 취소, 권한 거부, 읽기 실패를 각각 시험해 업무 계층에 올바른 결과가 전달되는지 확인합니다.

카메라는 파일 읽기와 별도 기능으로 다뤄야 합니다. 카메라 입력을 위한 C/C++ 안내를 참고하되, HarmonyOS PC에서 사용할 수 있는 인터페이스인지, 필요한 권한과 초기화·종료 절차가 무엇인지는 목표 버전 자료와 실제 개발 환경에서 확인합니다. Electron 카메라 플러그인을 Node-API 호출로 이름만 바꾸는 방식은 검증이 아닙니다.

권한 이름이나 카메라 인터페이스가 목표 버전 문서에서 확인되지 않으면 추측해 구현하지 않습니다. 해당 기능은 “미확인”으로 남기고, 출시 판단에서 별도의 보류 항목으로 관리합니다.

HarmonyOS PC 앱에서 카메라와 로컬 파일을 어떻게 검증하나요?
파일 선택, 취소, 권한 거부, 읽기 실패를 각각 실행하고 결과가 업무 계약에 맞게 전달되는지 기록합니다. 카메라는 공식 인터페이스와 권한 신청 경로를 먼저 확인한 다음, 초기화 실패와 자원 해제까지 시험합니다. 두 기능을 하나의 일반적인 파일 시스템 접근으로 묶지 않습니다.

승인 단계: 재현 가능한 결과가 없으면 기능을 보류합니다

최종 판단은 동작 여부만으로 내리지 않습니다. 빌드 재현성, 인터페이스 사용 가능성, 권한 동작, 안정성을 각각 기록하고, 실행한 SDK와 빌드 대상도 함께 남깁니다. 같은 작업을 다른 개발자가 다시 실행할 수 없는 상태라면 이전 완료로 처리하지 않습니다.

  • [ ] 목표 개발 환경에서 앱을 빌드하고 설치할 수 있습니다.
  • [ ] 정상 요청과 취소, 권한 거부, 읽기 또는 초기화 실패가 구분됩니다.
  • [ ] 반복 호출 뒤에도 콜백 순서와 네이티브 자원 해제가 정상입니다.
  • [ ] 파일과 카메라의 권한 동작이 목표 버전 공식 자료 및 실제 검증 기록과 일치합니다.
  • [ ] 확인하지 못한 SDK 기능이나 하드웨어 지원은 미지원 또는 미확인으로 남아 있습니다.

핵심 하드웨어 기능이나 SDK 인터페이스가 공개되지 않았거나 실제 환경에서 검증되지 않았다면, 어댑터 경계를 유지하고 그 기능의 이주를 미루는 편이 안전합니다. 개발자 내실 일정이나 이주 도구에 관한 미확인 소식만으로 준비 완료를 선언하지 마세요.

Mac 유지보수 환경은 HarmonyOS PC 검증과 분리해 선택합니다

현재 Windows·Linux 데스크톱이나 Node.js 빌드 환경에만 의존하면 플랫폼별 네이티브 바이너리를 다시 준비해야 하고, IPC 구조를 그대로 전제할 수 없으며, 목표 플랫폼의 권한과 하드웨어 동작을 대신 검증하지 못합니다. 반대로 Mac 환경을 추가해도 HarmonyOS PC용 SDK나 도구가 실행된다는 뜻은 아닙니다. Mac은 이 플랫폼의 검증 대체품이 아니라, 별도로 유지하는 macOS 앱의 빌드와 테스트에 필요한 환경으로 판단해야 합니다.

프로젝트에 macOS 버전도 있고, 장비를 상시 구매하기 전에 임시 테스트 환경이 필요한 경우에는 KuzCloud의 Mac 환경과 이용 안내를 확인할 수 있습니다. 물리 장치 접근이 필수이거나 장기간 지속적인 고부하 작업이 중심이라면 임대보다 자체 장비가 더 적합할 수 있습니다. 먼저 기능 목록에서 재사용·교체·미확인 항목을 나누고, HarmonyOS PC 기능 검증과 Mac 유지보수 작업을 별개의 계획으로 잡는 것이 좋습니다.

하모니오에스 피시 이전 검증, 쿠즈클라우드 원격 맥으로 시작하세요

애플 실리콘 맥 미니 한 대를 단독으로 사용하며 네이티브 플러그인 이전에 필요한 빌드와 점검 환경을 마련할 수 있습니다.

원격 화면 접속과 명령줄 접속으로 익숙한 개발 도구와 업무 흐름을 이어갈 수 있습니다.