2026 HarmonyOS PC: Electron 로컬 파일 접근은 어떻게 마이그레이션할까?

HarmonyOS PC의 Electron 로컬 파일 접근은 경로와 IPC 코드를 그대로 옮기지 말고, 앱 샌드박스·사용자가 승인한 공용 디렉터리·사용자가 직접 고른 파일로 나눠 다시 설계하는 편이 안전합니다. 해당 대상 환경에서 지원이 확인된 경우에는 일반 파일 작업에 ArkTS 파일 인터페이스를 우선 검토하고, 재사용할 C/C++ 코드가 있을 때만 Node-API 연결을 평가합니다.
이 글은 Electron 앱의 파일 기능을 이전할지 판단하는 제품 기술 책임자, 파일 접근 계약을 플랫폼에 독립적으로 정리하려는 크로스 플랫폼 설계자, 기존 C/C++ 파일 라이브러리의 재사용을 검토하는 엔지니어를 위한 안내입니다.
마지막 업데이트: 2026년 10월 21일. 공용 디렉터리의 권한 조건과 대상 기기 범위는 공용 디렉터리 접근 안내 및 공용 디렉터리 권한 목록을 기준으로 확인했습니다. 문서에 적힌 일반적인 지원 설명만으로 특정 HarmonyOS PC 시험판이나 SDK에서 기능이 제공된다고 단정할 수는 없습니다.
HarmonyOS PC 파일 접근 마이그레이션의 출발점
Electron의 fs 호출을 찾아 경로 문자열만 바꾸는 방식은 파일 권한 모델과 앱 구조의 차이를 놓칩니다. Electron에서는 렌더러와 메인 프로세스가 개발자가 정한 IPC 채널로 통신할 수 있습니다. 그러나 이 구조 자체가 새 플랫폼에서 같은 파일 접근 권한을 보장하지는 않습니다. Electron IPC 문서는 프로세스 간 메시지 전달 방식을 설명하고, Electron 샌드박스 안내는 프로세스 격리의 맥락을 설명합니다.
먼저 현재 앱에서 파일 작업을 다음 항목으로 나눠 목록화합니다.
- 읽기와 쓰기: 설정, 작업 결과, 사용자 문서 등 데이터의 목적과 저장 기간을 기록합니다.
- 목록 조회와 탐색: 폴더 내용을 읽는지, 하위 폴더까지 순회하는지 구분합니다.
- 가져오기와 내보내기: 사용자가 파일을 선택하는지, 앱이 지정한 위치에 결과를 저장하는지 확인합니다.
- 임시 파일: 생성 위치, 삭제 시점, 앱 종료나 재시작 뒤 필요한 상태를 적습니다.
- 호출 흐름과 오류: 요청을 보내는 화면, IPC 채널, 호출하는 메인 프로세스 기능, 반환되는 오류를 연결합니다.
이 목록에는 경로뿐 아니라 호출자, 파일의 소유 주체, 데이터 수명, 실패 시 화면에 보여줄 동작도 포함해야 합니다. 경로 문자열만 기록하면 사용자 취소와 권한 거부를 같은 실패로 처리하거나, 앱 전용 데이터와 사용자가 고른 파일을 뒤섞기 쉽습니다.
Electron fs 작업은 어디서부터 옮겨야 하나요?
업무 동작부터 분리합니다. 예를 들어 다운로드 결과를 저장하는 기능은 “임의 경로에 쓰기”가 아니라 “사용자가 선택한 위치에 결과 저장”으로 정의할 수 있습니다. 사용자가 고른 파일을 여는 기능도 전체 파일 시스템을 탐색하는 권한과는 다릅니다. 이 구분이 완료된 뒤 각 동작을 대상 SDK에서 확인된 인터페이스와 연결합니다.
경로와 권한을 나누는 기준
HarmonyOS 문서는 앱이 관리하는 파일과 공용 디렉터리 접근을 구분해 안내합니다. 공용 디렉터리의 경로를 얻을 수 있다는 사실만으로 그 안의 파일에 읽기·쓰기 권한이 생기는 것은 아닙니다. 관련 문서는 공용 디렉터리 접근에 필요한 시스템 권한과 사용자 승인 절차를 설명하며, 해당 인터페이스의 적용 범위를 2in1 기기로 제한해 안내합니다. 따라서 특정 HarmonyOS PC 기기, SDK 또는 시험판에서의 지원 여부는 별도로 확인해야 합니다. 자세한 조건은 앱 파일 접근 및 관리 문서를 참고하되, 대상 환경에서 검증되기 전까지 지원 확정으로 취급해서는 안 됩니다.
HarmonyOS PC 앱에서 바탕 화면과 문서 폴더를 바로 읽을 수 있나요?
기존 Electron 앱에서 가능했던 경로 접근을 전제로 해서는 안 됩니다. 공용 디렉터리 접근은 해당 시스템 기능과 사용자 승인 조건에 따라 달라집니다. 앱이 파일 선택을 요청하는 흐름과 미리 정의한 디렉터리에 접근하는 흐름도 같지 않습니다. 대상 기기에서 기능이 제공되지 않거나 승인이 거부되는 경우를 제품 흐름에 포함해야 합니다.
| 파일 범위 | 먼저 확인할 조건 | 설계상 처리 |
|---|---|---|
| 앱 전용 데이터 | 대상 환경의 앱 파일 인터페이스 지원 여부 | 앱 데이터 저장·읽기 동작으로 제한합니다 |
| 사용자가 선택한 파일 | 선택 기능과 반환 데이터의 대상 SDK 지원 여부 | 선택 결과를 받아 필요한 작업만 수행합니다 |
| 공용 디렉터리 | 시스템 권한, 사용자 승인, 기기 형태 및 SDK 지원 | 승인 결과와 접근 실패를 별도 상태로 처리합니다 |
| 임의 경로 접근 | 대상 환경의 정책과 API가 이를 허용하는지 여부 | 확인 전에는 구현 가능하다고 가정하지 않습니다 |
플랫폼 공통 파일 계약과 ArkTS 연결
Electron 메인 프로세스에서 제공하던 파일 기능은 플랫폼 중립적인 업무 계약으로 바꾸는 편이 좋습니다. 렌더러에 임의 경로나 전체 파일 시스템 API를 노출하는 대신, 파일 선택, 내용 읽기, 결과 저장, 파일 내보내기처럼 제한된 작업으로 나눕니다. 입력과 출력, 취소 여부, 권한 상태, 오류 종류를 함께 정의해야 합니다.
| 계약 항목 | 계약에 담을 내용 | 실패 상태의 예 |
|---|---|---|
| 요청 | 업무 동작, 필요한 파일 정보, 사용자 동의가 필요한지 여부 | 필수 입력 누락 |
| 응답 | 성공 여부와 결과 데이터 또는 선택 결과 | 지원되지 않는 기능 |
| 권한 | 승인 상태와 필요한 사용자 조치 | 승인 거부 또는 취소 |
| 오류 | 앱이 처리할 수 있는 오류 유형과 복구 안내 | 파일 없음, 쓰기 실패 |
| 비동기 처리 | 대기 중·완료·취소 상태의 전달 방식 | 중복 요청 또는 작업 중단 |
Electron IPC 파일 작업을 ArkTS 인터페이스로 옮길 때 권한은 어디서 처리하나요?
렌더러와 파일 기능 사이의 업무 경계에서 권한 요청과 결과 상태를 관리합니다. 화면은 사용자에게 필요한 동작을 요청하고, 플랫폼별 어댑터가 지원되는 ArkTS 파일 인터페이스와 승인 절차를 연결하도록 구성할 수 있습니다. 구체적인 API 이름이나 실행 코드는 목표 HarmonyOS PC의 SDK와 기기에서 확인한 뒤 확정해야 합니다. 이 검증 전에는 일반 HarmonyOS 문서의 예시를 PC 환경에서 바로 실행되는 코드처럼 제시하지 않습니다.
ArkTS File Kit을 검토할 때도 마찬가지입니다. 실제 사용 사례에 필요한 선택·읽기·쓰기 동작이 대상 환경에서 제공되는지, 권한 거부와 사용자의 선택 취소가 구별되는지 확인합니다. 권한이 필요한 동작을 단순한 경로 변환으로 대체할 수는 없습니다.
Node-API 적용 여부와 검증 시점
HarmonyOS PC 파일 접근에 Node-API가 꼭 필요한가요?
일반적인 파일 작업이라면 우선 ArkTS 파일 인터페이스가 요구사항을 충족하는지 확인합니다. Node-API는 앱 권한을 우회하는 통로가 아닙니다. 기존 C/C++ 파일 처리 로직을 재사용해야 하는 이유가 분명하고, 목표 SDK의 구성 요소와 빌드 산출물까지 검증할 수 있을 때에만 브리지 도입을 평가합니다.
HarmonyOS Node-API 사용 안내는 대상 플랫폼에서의 사용 절차를 확인하는 자료입니다. Node.js Node-API 문서는 Node-API 자체의 인터페이스를 설명하지만, 문서에서 이름이 비슷하다는 이유만으로 Electron 네이티브 확장이나 기존 Node.js 모듈이 그대로 호환된다고 결론 내릴 수는 없습니다. 빌드, 로딩, 권한, 오류 전달을 실제 대상 환경에서 각각 확인해야 합니다.
장점은 검증된 C/C++ 파일 처리 로직을 유지할 가능성이 있다는 점입니다. 반면 브리지와 빌드 산출물 관리가 추가되고, API 호환성과 권한 경계를 별도로 시험해야 합니다. 기존 코드 재사용이 불필요하다면 ArkTS 인터페이스만으로 계약을 구현하는 구성이 단순합니다.
단말 검증과 배포 전 판정
검증은 기능 성공만으로 끝내지 않습니다. 승인 취소, 파일 부재, 반복 요청, 앱 재시작 후 데이터 상태까지 확인해야 합니다.
- 대상 환경을 고정합니다. 실제 시험 기기와 SDK를 기록하고, 필요한 파일 API가 그 조합에서 제공되는지 확인합니다.
- 앱 전용 저장을 시험합니다. 저장과 재읽기, 앱 재시작 뒤 데이터 유지 여부를 확인합니다.
- 승인된 위치 접근을 시험합니다. 권한 요청부터 사용자 승인, 읽기·쓰기 결과까지 순서대로 기록합니다.
- 사용자 취소를 시험합니다. 선택 창이나 권한 요청을 취소했을 때 앱이 성공으로 오인하거나 멈추지 않는지 확인합니다.
- 예외 경로를 시험합니다. 대상 파일이 없거나 접근할 수 없는 경우, 쓰기 실패와 중복 동작이 각각 구분되는지 확인합니다.
- 재시작 뒤 상태를 점검합니다. 임시 파일과 저장 결과가 제품에서 정한 수명과 일치하는지 검증합니다.
마이그레이션 뒤 파일 동작과 취소 처리는 어떻게 확인하나요?
기능별로 기기·SDK·권한 상태·재현 절차·기대 결과·실제 결과를 한 기록에 남깁니다. 시험판이나 SDK가 바뀌면 지원 여부를 다시 점검해야 합니다. 특히 공용 디렉터리 접근의 기기 제한이나 권한 절차가 공식 문서에서 변경되면 관련 설계와 안내를 함께 갱신합니다.
| 시험 시나리오 | 확인할 결과 | 실패 시 점검 |
|---|---|---|
| 앱 전용 파일 읽기·쓰기 | 저장 후 다시 읽을 수 있는지 | 앱 파일 경계와 반환 오류 |
| 승인된 디렉터리 접근 | 승인 후 요청한 업무만 가능한지 | 대상 기기, SDK, 권한 상태 |
| 사용자 취소 | 취소가 오류나 성공과 구분되는지 | 응답 계약과 화면 상태 |
| 없는 파일과 반복 작업 | 앱이 멈추지 않고 복구 가능한지 | 파일 없음·중복 요청 처리 |
| 앱 재시작 | 데이터와 임시 파일이 의도한 상태인지 | 파일 수명과 정리 규칙 |
이 기록이 없으면 “개발 환경에서 한 번 읽혔다”는 결과만으로 배포 가능성을 판단하기 어렵습니다. 지원 범위가 확인되지 않은 환경에서는 코드 이식보다 인터페이스 계약과 검증 계획을 먼저 준비하고, 실기기 확인 뒤에 구현 범위를 확정하는 편이 안전합니다.
Electron의 임의 경로 접근을 유지하는 방식은 권한 경계를 다시 설계하기 어렵고, IPC 안에 파일 시스템 세부 사항이 남으며, 새 SDK에서의 지원 여부도 보장하지 못합니다. 반대로 HarmonyOS PC 실기기 검증 없이 원격 개발 환경만 갖추면 대상 기기의 권한 동작을 확인할 수 없습니다. 임시 macOS 빌드나 개발 자원이 필요한 팀은 ProxyMac 요금 안내에서 사용 기간에 따른 비용을 검토한 뒤, ProxyMac 콘솔을 별도 작업 환경으로 살펴볼 수 있습니다. 다만 원격 Mac은 HarmonyOS PC 단말도, 검증된 HarmonyOS 빌드 환경도 아닙니다. 대상 장치 시험은 실제 지원이 확인된 환경에서 진행하고, 지속적인 고정 부하나 물리 연결이 필요한 업무는 장비 보유와 현지 검증 환경을 우선 고려해야 합니다.