DevOps / CI/CD

2026 HarmonyOS PC:Electron 本機檔案存取如何遷移?

2026 HarmonyOS PC:Electron 本機檔案存取如何遷移?

勝出方案是先重畫檔案存取與授權邊界,再把一般讀寫交給已確認可用的 ArkTS 檔案介面;不要直接搬移 Electron 本機路徑或 IPC 檔案操作。只有在確有 C/C++ 邏輯需要共用,且目標 HarmonyOS PC 設備與 SDK 已實測通過時,才評估 Node-API。

本文適合正在估算 Electron 桌面軟體遷移範圍的技術負責人、希望建立平台無關檔案介面契約的跨端架構師,以及需要判斷底層 C/C++ 檔案庫能否保留的工程師。

最後更新於 2026 年 10 月 21 日;資料核對自華為公共目錄存取與權限文件、公共目錄權限列表及Electron IPC 文件。一般 HarmonyOS 文件不能單獨證明特定 PC 內測版本或 SDK 已開放相關能力。

HarmonyOS PC Electron 檔案存取遷移:先釐清能驗證到哪裡

這次遷移不是把 fs 呼叫逐行換成另一套 API。路徑背後的權限模型、操作發起方和檔案生命週期都可能不同。若目標設備或 SDK 尚未驗證,就先定義介面與待測項目;不要把通用 HarmonyOS 文件中的能力,寫成目標 PC 版本已經支援。

官方文件指出,公共目錄存取需要符合相應系統能力與使用者授權條件,並標示相關介面僅支援 2in1 設備。公共目錄介面說明並未因此證明某個 HarmonyOS PC 內測版本、SDK 或實際設備已開放該能力。開發團隊需要把設備形態、SDK、權限流程和實測結果一起核對。

Electron 的 fs 檔案讀寫應從哪裡開始遷移?
先盤點操作,不要先改程式碼。將讀取、寫入、遍歷、匯入匯出及暫存檔分開記錄;再標明每項操作的呼叫發起方、檔案存放位置、生命週期,以及失敗時產品應如何回應。這比按路徑字串做替換,更容易找出權限和行為差異。

第一步:盤點 Electron 檔案能力,而非照抄路徑

Electron IPC 是由開發者定義通道,讓不同程序之間傳遞請求;官方文件說明了主程序與渲染程序間的 IPC 用法。Electron IPC 文件因此,既有程式通常不只是直接呼叫 fs:部分操作可能先由渲染端送出請求,再由主程序執行。

逐項整理下列資訊:

  • 操作類型:讀取內容、建立或覆寫檔案、列出目錄、選取檔案、匯出結果、清除暫存資料。
  • 檔案範圍:應用私有資料、使用者主動選取的檔案,或公共目錄中的內容。
  • 責任邊界:由哪個程序發起;授權由誰取得;檔案錯誤要回傳給哪個畫面或業務流程。
  • 檔案狀態:操作完成後是否需保留、重開應用程式後是否仍需使用,以及取消或失敗時是否要清理暫存檔。
  • 錯誤語意:使用者取消、檔案不存在、權限不足、能力不可用,應分別回報,不能一律包裝成「讀取失敗」。

Electron 也有自己的程序與沙箱安全邊界;Electron 沙箱說明可作為檢視現有呼叫責任的依據。但即使來源端已限制渲染程序,也不能推論目標端能接受相同路徑或權限設計。

注意:公共目錄路徑可取得,不代表應用已獲得讀寫授權。路徑解析、權限狀態與實際讀寫結果要分開驗證。

第二步:把應用沙箱、公共目錄與使用者選取分開

應用沙箱內的私有資料、經授權後存取的公共目錄,以及由使用者明確選取的檔案,是三種不同的產品情境。不能因為某個目錄名稱或路徑看起來熟悉,就將它視為已授權範圍。

華為文件列出公共目錄存取涉及的權限與能力要求,應以公共目錄權限列表和應用檔案存取管理說明核實實際流程。把這些條件放進需求設計時,還要註明文件適用的設備形態與 SDK 範圍;如果目標環境未完成驗證,狀態就應標為「待確認」,不能標成「支援」。

HarmonyOS PC 應用能否直接存取使用者的桌面和文件目錄?
不能只憑目錄名稱或一般 HarmonyOS 文件判定。公共目錄存取受系統能力、使用者授權及設備支援範圍限制;桌面或文件目錄是否可用,要在目標設備和 SDK 上實際確認。沒有授權時,產品應提供選取檔案、改存私有空間或取消操作等清楚選項。

權限也不該藏在無法辨識的底層錯誤裡。至少要處理授權成功、使用者取消、目標能力不可用、權限不足及檔案不存在等狀態。這些狀態會決定介面能否重試、是否提示重新選取,以及是否保留尚未提交的工作。

第三步:用有限的檔案契約取代任意路徑 API

把 Electron 主程序提供的檔案能力抽象成業務操作,而非向渲染層開放任意路徑或完整檔案系統介面。契約可先涵蓋「選取檔案」、「讀取內容」、「儲存結果」和「匯出檔案」;每項操作都要定義輸入、輸出、授權狀態與錯誤類型。

例如,儲存結果的介面不必接受任意路徑。它可以表達要儲存的內容、預期的檔案名稱,以及由平台層完成的選址或授權流程。ArkTS 端只把這個契約映射到已核實支援的檔案介面。若某種操作在目標設備上尚未確認,介面仍可先保留,但必須回傳明確的「能力未確認」狀態,而不是假裝讀寫成功。

選項 適用情境 權限與路徑邊界 遷移判斷
應用私有資料 設定檔、工作中間資料 限定在已確認的應用資料範圍 先確認目標端對應的檔案介面與重啟後狀態
公共目錄 使用者需要在應用外管理的文件 需核對系統能力、使用者授權及設備支援 未確認授權流程前,不承諾直接存取
使用者選取檔案 匯入或匯出個別文件 以使用者選取及平台回傳結果為界 適合作為任意路徑依賴的替代設計
Node-API 橋接 確有 C/C++ 邏輯需重用 不會取代平台權限,也不代表原生擴充套件可直接載入 只有建置與目標環境驗證通過才採用

Electron IPC 檔案操作改成 ArkTS 介面時,權限應放在哪一層?

把授權與平台檔案存取放在 ArkTS 平台介面層處理;業務層提出有限操作需求,渲染介面呈現結果並依狀態引導使用者。這樣能避免每個畫面各自拼接路徑、重複處理權限,亦能讓不同平台共用同一組操作語意。

Electron 原有的 IPC 通道可作為盤點參照,但不應成為新契約的形狀。請避免把 read(path) 或 write(path, data) 這類任意路徑能力直接暴露給業務端。更可控的介面會表達「讀取使用者選取的文件」或「匯出目前結果」,由平台層決定實際如何取得授權與完成檔案操作。

第四步:先驗證 ArkTS File Kit,再決定是否需要 Node-API

一般檔案操作應先對照 ArkTS File Kit 與目標 SDK 的實際能力。確認操作涵蓋範圍、授權狀態如何回報,以及設備是否支援後,再決定是否需要其他橋接。文件名稱相似,不等於 Electron 原生擴充套件或 Node.js C++ 程式碼能直接重用。

HarmonyOS PC 檔案存取需要 Node-API 嗎?
多數一般讀寫需求不應先假設需要。先驗證 ArkTS 檔案介面能否滿足讀取、儲存、選取與匯出;只有既有 C/C++ 檔案處理邏輯具有實際重用價值,才評估橋接成本。華為的Node-API 使用指引與Node.js Node-API 文件可供理解介面概念,但不能據此推定目標 SDK 的建置產物、載入方式或 Electron 原生模組相容性。

Node-API 也不是繞過應用權限的通道。橋接前,團隊仍要分別確認目標 SDK、建置流程、C/C++ 依賴、檔案授權責任和錯誤回傳方式。若這些項目未在目標設備驗證,遷移方案就應把它們列為風險,而非宣稱已可使用。

提醒:只因既有擴充套件使用 Node-API,不足以證明它能在目標 HarmonyOS PC 環境直接使用。相容性結論要以實際建置和設備測試為準。

第五步:以端到端驗收封住遷移風險

不要只用一次成功讀取作為驗收。測試應涵蓋沙箱內讀寫、授權目錄讀寫、使用者取消、目標檔案不存在、重複操作,以及應用程式重啟後的檔案狀態。每項測試都記錄目標設備、SDK、授權步驟、操作結果和可重現方式。

如何驗證遷移後的讀寫、授權取消與例外處理?
先在目標設備完成授權目錄成功案例,再撤銷或取消授權,確認介面不會繼續使用過期狀態;接著測試不存在的檔案、重複讀寫和重啟後狀態。每個失敗案例都要確認錯誤能回到正確的產品流程,而不是只留在原生層日誌。

交付紀錄至少應包含:

  • 目標設備形態與 SDK 識別資訊。
  • 使用的檔案範圍及授權步驟。
  • 操作前後的檔案狀態。
  • 使用者取消或越權時的預期結果與實際結果。
  • 可供其他工程師重現的操作順序。

HarmonyOS PC 的 SDK、設備或內測能力尚未確認時怎麼處理?
保留平台無關契約,將未驗證介面標為待確認,並以目標環境的實測補足。不要用一般 HarmonyOS 文件替代 PC 端驗證,也不要在沒有實測時貼出看似可執行的遷移程式碼。後續若官方更新設備限制、權限文件或開發工具狀態,再逐項更新支援結論。

若現有方式只是把 Electron 路徑寫死在各個畫面,後續會持續承擔權限分散、跨平台分支難維護、取消與失敗狀態不一致等成本。若團隊考慮改用遠端 Mac 作為建置或一般開發環境,也要看清它不能代替 HarmonyOS PC 目標設備、不能證明 ArkTS 介面已支援,更不能取代實機授權驗收。需要額外 Mac 工作環境時,可依團隊工作負載查看 ProxyMac 的方案資訊;若開發環境連線或使用方式仍需釐清,可參考 ProxyMac 使用說明。將 Mac 作為補充資源評估,不要把它當成已驗證的 HarmonyOS PC 測試環境。

為跨平台遷移,備妥專屬雲端 Mac

ProxyMac 提供獨享 Mac mini M4,讓團隊在調整檔案存取架構期間,仍可使用完整 macOS 環境進行建置與驗證。
透過 SSH、VNC 或瀏覽器遠端連線,無論身在何處,都能彈性管理開發與測試工作。