DevOps / CI/CD

2026 HarmonyOS PC: Wie lässt sich der lokale Dateizugriff von Electron migrieren?

2026 HarmonyOS PC: Wie lässt sich der lokale Dateizugriff von Electron migrieren?

Migrieren Sie lokale Dateizugriffe von Electron nicht durch einen Austausch von Pfaden oder IPC-Aufrufen. Teilen Sie die Funktionen zuerst in App-Speicher, nutzerautorisierte Verzeichnisse und bewusst ausgewählte Dateien auf; prüfen Sie gewöhnliche Dateioperationen anschließend mit den verfügbaren ArkTS-Schnittstellen. Node-API kommt erst infrage, wenn vorhandene C/C++-Logik erhalten werden soll und die konkrete HarmonyOS-PC-Umgebung den Einsatz bestätigt.

Dieser Beitrag richtet sich an Produktverantwortliche mit bestehenden Electron-Anwendungen, an plattformübergreifende Architekten und an C/C++-Teams, die den Umfang einer Dateimigration abschätzen müssen. Er behandelt lokale Dateioperationen, nicht die allgemeine Kompatibilität von Plugins oder die Migration von Kamerafunktionen.

Prüfstand: 21.10.2026. Die Aussagen zu Berechtigungen und Geräteformen stützen sich auf die verlinkte offizielle Dokumentation. Sie belegen nicht automatisch, dass eine bestimmte HarmonyOS-PC-Testversion, ein konkretes SDK oder ein bestimmtes Gerät dieselben Schnittstellen freigibt.

Vor der Migration: Zielumgebung statt Betriebssystemannahmen

Eine bestehende Electron-Anwendung kann Dateien an mehreren Stellen öffnen, schreiben oder weiterreichen. Das bedeutet jedoch nicht, dass ihre bisherige Pfadlogik auf HarmonyOS PC übertragbar ist. Auch wenn sich Betriebssysteme technische Grundlagen teilen, bestimmen Anwendungssandbox, Berechtigungen und Dateiauswahl den tatsächlichen Zugriff. Ein Linux-Kernel als technischer Ausgangspunkt wäre daher kein Beleg für identische Pfade oder Zugriffsrechte.

Klären Sie zunächst, welche Zielumgebung tatsächlich geprüft werden kann:

  • Geräteform: Ist das getestete Gerät ein für die jeweilige Dateifunktion unterstütztes Gerät?
  • SDK und API: Sind die benötigten Schnittstellen in der konkret verwendeten Umgebung verfügbar?
  • Berechtigungsablauf: Kann die Anwendung die nötige Fähigkeit anfordern und die Nutzerentscheidung zuverlässig verarbeiten?
  • Dateiziel: Geht es um private Anwendungsdaten, eine vom Nutzer gewählte Datei oder ein gemeinsam genutztes Verzeichnis?
  • Freigabestatus: Stammt die Aussage zur Unterstützung aus einer offiziellen Dokumentation oder aus einem reproduzierbaren Test auf dem Zielgerät?

Die öffentliche HarmonyOS-Dokumentation beschreibt Bedingungen für den Zugriff auf öffentliche Verzeichnisse und nennt eine Beschränkung auf 2-in-1-Geräte. Das ist ein belegter Hinweis zur dokumentierten Funktion, aber kein Nachweis dafür, dass eine bestimmte HarmonyOS-PC-Insider-Version oder ein bestimmtes SDK sie bereits unterstützt. Prüfen Sie dafür die Beschreibung zum Zugriff auf öffentliche Verzeichnisse und die dort verknüpften Voraussetzungen für die Zielumgebung.

Wichtig: Wenn das konkrete PC-Gerät oder SDK nicht zugänglich ist, dokumentieren Sie die Schnittstellen als Prüfpunkt. Präsentieren Sie keine allgemeine HarmonyOS-Anleitung als bestätigte HarmonyOS-PC-Unterstützung.

Bestandsaufnahme: Welche Electron-Funktionen sind wirklich nötig?

Beginnen Sie nicht mit der Übersetzung einzelner Aufrufe aus fs. Erfassen Sie zunächst, was das Produkt mit Dateien tatsächlich erledigt. Bei einer typischen Desktop-Anwendung können Nutzer etwa Dokumente importieren, Ergebnisse exportieren, eine zuletzt verwendete Datei erneut öffnen oder temporäre Inhalte erzeugen. Jede dieser Aufgaben hat andere Anforderungen an Auswahl, Speicherung und Berechtigungen.

Für jede Operation sollten Sie mindestens festhalten:

  • Aktion: Lesen, Schreiben, Auflisten, Importieren, Exportieren oder temporär speichern.
  • Aufrufer: Renderer, Hauptprozess oder ein nativer Bestandteil.
  • Dateiherkunft: App-eigene Daten, Nutzerwahl oder ein gemeinsam genutztes Verzeichnis.
  • Lebenszyklus: Bleibt die Datei dauerhaft erhalten, wird sie nach einer Sitzung gelöscht oder muss sie nach einem Neustart verfügbar sein?
  • Fehlerverhalten: Was geschieht bei Abbruch, fehlender Datei, verweigertem Zugriff oder einem Schreibfehler?
  • Datenklasse: Enthält die Datei personenbezogene oder vertrauliche Informationen?

Diese Erfassung deckt häufig versteckte Kopplungen auf. Ein Renderer kann beispielsweise einen absoluten Pfad speichern, den der Hauptprozess später ungeprüft wiederverwendet. Eine andere Stelle kann einen Dialog zur Dateiauswahl öffnen, aber nach einem Abbruch mit einem leeren Ergebnis weiterarbeiten. Wird nur der Pfadaufruf ersetzt, bleiben solche Annahmen bestehen.

Wo beginnen Sie mit der Migration von fs-Lese- und Schreibzugriffen?

Beginnen Sie bei den sichtbaren Geschäftsaktionen: „Datei öffnen“, „Ergebnis sichern“ oder „Dokument exportieren“. Verknüpfen Sie jede Aktion mit dem bestehenden IPC-Kanal, dem jeweiligen fs-Aufruf und dem erwarteten Ergebnis. Damit wird aus einer unübersichtlichen Liste technischer Zugriffe eine Menge überprüfbarer Produktfunktionen.

Electron übermittelt Nachrichten über von der Anwendung definierte IPC-Kanäle zwischen Prozessen. Die Electron-Dokumentation zur IPC-Kommunikation beschreibt dieses Nachrichtenmodell. Für die Migration ist entscheidend: Ein IPC-Kanal ist nicht selbst die Berechtigung, eine beliebige Nutzerdatei zu öffnen. Er ist ein Transportweg innerhalb der bisherigen Architektur.

Prüfen Sie außerdem die Sicherheitsgrenzen des bestehenden Electron-Aufbaus. Die Electron-Dokumentation zur Prozesssandbox erläutert, wie die Sandbox die Möglichkeiten eines Renderer-Prozesses begrenzt. Das hilft, alte Zuständigkeiten sauber zuzuordnen: Welche Operation muss im privilegierten Prozess liegen, und welche Informationen darf die Oberfläche überhaupt erhalten?

Berechtigungsmodell: App-Sandbox oder nutzerfreigegebene Datei?

Der zentrale Architekturwechsel besteht darin, drei Zugriffsarten nicht mehr als bloße Varianten eines Dateipfads zu behandeln:

  • Privater App-Speicher: Dateien gehören zum internen Datenbereich der Anwendung. Sie sind kein Ersatz für einen frei zugänglichen Nutzerordner.
  • Nutzergewähltes Dokument: Der Nutzer wählt gezielt eine Datei oder ein Ziel aus. Die Anwendung verarbeitet die zurückgegebene Auswahl gemäß dem bestätigten Schnittstellenvertrag.
  • Öffentliches Verzeichnis: Zugriff kann von Systemfähigkeit, Nutzerautorisierung und der unterstützten Geräteform abhängen.

Die offizielle Dokumentation zum Dateizugriffsmanagement von Anwendungen und die Übersicht der Berechtigungen für den Zugriff auf öffentliche Verzeichnisse sind die maßgeblichen Ausgangspunkte für diese Unterscheidung. Ein Verzeichnispfad oder ein erfolgreicher Aufruf zur Ermittlung eines Speicherorts belegt nicht automatisch, dass die Anwendung dort lesen und schreiben darf.

Kann die Anwendung Desktop- und Dokumentenordner direkt verwenden?

Das lässt sich nicht pauschal zusagen. Die dokumentierten Bedingungen für öffentliche Verzeichnisse verlangen die passende Systemfähigkeit und eine Nutzerautorisierung; die Dokumentation weist zudem auf die Unterstützung von 2-in-1-Geräten hin. Ob ein bestimmtes HarmonyOS-PC-Gerät, ein bestimmter Build oder ein bestimmter SDK-Stand diese Funktion bereitstellt, muss separat geprüft werden.

Behandeln Sie deshalb einen Nutzerabbruch nicht als technischen Ausnahmefall, den die Anwendung stillschweigend übergeht. Bieten Sie eine verständliche Rückkehr zur Oberfläche an. Bei fehlender Unterstützung sollte die Funktion eine klare Alternative nennen, etwa die bewusste Auswahl eines Dokuments, sofern diese Option in der Zielumgebung verfügbar und bestätigt ist.

Zugriffsszenario Bisherige Electron-Annahme Zielmodell für die Migration Zentrale Prüfung
App-interne Einstellungen Beliebiger Pfad im Anwendungsprozess Separater Vertrag für private App-Daten Sind Speicherort und Wiederherstellung auf dem Zielgerät bestätigt?
Nutzer öffnet ein Dokument Pfad wird per IPC an den Hauptprozess übergeben Auswahl- und Leseaktion mit explizitem Ergebnis Werden Abbruch und fehlender Zugriff unterscheidbar behandelt?
Export in ein öffentliches Verzeichnis Schreibzugriff auf einen bekannten Ordner Nutzerfreigabe und geprüfte öffentliche Verzeichnisfunktion Sind Fähigkeit, Autorisierung und Geräteform erfüllt?
Temporäre Arbeitsdatei Datei wird nach Bedarf im Dateisystem angelegt Begrenzter Lebenszyklus und definierter Bereinigungsfall Bleibt die Datei nach Neustart fälschlich erhalten?

Auf welcher Ebene sollten IPC-Dateioperationen Berechtigungen behandeln?

Die Plattformgrenze gehört in den Dateiadapter, nicht in die fachliche Benutzeroberfläche. Die Oberfläche löst eine Geschäftsaktion aus, zum Beispiel „Export speichern“. Der Adapter prüft, welche Auswahl oder Autorisierung erforderlich ist, ruft die bestätigte Plattformfunktion auf und liefert ein typisiertes Ergebnis zurück. Dadurch muss die UI keine frei verwendbaren absoluten Pfade kennen.

Legen Sie mindestens diese Ergebniszustände fest: erfolgreich, vom Nutzer abgebrochen, nicht unterstützt, nicht autorisiert und fehlgeschlagen. So kann die Oberfläche auf eine verweigerte Berechtigung anders reagieren als auf einen fehlenden Datenträger oder einen ungültigen Dateinamen. Das ist auch für Datenschutz und DSGVO relevant: Die Anwendung sollte nicht mehr Dateiinhalte oder Pfadinformationen protokollieren, als zur Fehlerdiagnose nötig sind. Für die Prüfung der eigenen Informations- und Supportprozesse können die Datenschutzhinweise von ProxyMac als interne Orientierung dienen; sie ersetzen keine projektspezifische Datenschutzprüfung.

Schnittstellenvertrag: Geschäftsaktionen statt beliebiger Pfade

Wenn die Bestandsaufnahme abgeschlossen ist, definieren Sie eine plattformneutrale Schnittstelle. Sie sollte konkrete Geschäftsaktionen anbieten, keine vollständige Dateisystem-API. Geeignete Operationen sind beispielsweise:

  • eine Datei zur Verarbeitung auswählen;
  • den Inhalt einer ausgewählten Datei lesen;
  • ein Ergebnis speichern lassen;
  • eine Datei in ein freigegebenes Ziel exportieren.

Jede Operation benötigt ein klares Eingabe- und Ausgabemodell. Ein Lesevorgang kann beispielsweise eine Auswahlreferenz und den angeforderten Verarbeitungsmodus entgegennehmen. Das Ergebnis sollte Inhalt oder einen kontrollierten Verweis sowie einen verständlichen Status enthalten. Der Vertrag sollte nicht voraussetzen, dass eine Plattform stets einen dauerhaften, frei nutzbaren Pfad liefert.

Halten Sie die Fehlerarten im Vertrag fest. Eine Nutzerentscheidung, die den Dialog schließt, ist kein Programmfehler. Eine nicht verfügbare Schnittstelle ist etwas anderes als eine verweigerte Autorisierung. Und ein Dateiformatfehler gehört in eine andere Behandlung als ein Systemfehler beim Schreiben. Diese Trennung erleichtert Tests und verhindert, dass jede Plattformabweichung zu einem unspezifischen „Datei konnte nicht geöffnet werden“ wird.

Das reduziert auch die Menge an Informationen, die zwischen UI und Plattformadapter fließt. Statt beliebige Pfadangaben entgegenzunehmen, akzeptiert der Adapter nur die vom Produkt benötigten Aktionen und Parameter. Das begrenzt unbeabsichtigte Zugriffe und macht die Architektur besser prüfbar.

Implementierungsentscheidung: Reicht ArkTS File Kit oder braucht es Node-API?

Für gewöhnliche Dateioperationen sollte zuerst geprüft werden, ob die verfügbaren ArkTS-Dateischnittstellen den fachlichen Vertrag abdecken. Die Bezeichnung ArkTS File Kit kann als Such- und Planungsterm dienen; sie ist jedoch keine Zusage, dass jede erwartete Funktion in jeder HarmonyOS-PC-Zielumgebung verfügbar ist. Dokumentation, SDK-Stand und Gerät müssen zusammen betrachtet werden.

Node-API ist nicht der Umweg, um eine fehlende Berechtigung zu umgehen. Die HarmonyOS-Anleitung zur Verwendung von Node-API beschreibt die Verwendung der Schnittstelle im jeweiligen Entwicklungsrahmen. Die Node.js-Referenz zu Node-API dokumentiert das Node-API-Modell. Daraus folgt nicht, dass ein bestehendes Electron-Add-on, ein Node.js-Binärmodul oder dessen Build-Artefakt ohne Änderungen auf der Zielplattform läuft.

Option Wann sie passt Vorteile Risiken und Prüfaufwand
ArkTS-Dateischnittstelle Die benötigten Aktionen sind in der Zielumgebung verfügbar und decken den Vertrag ab Plattformnahe Berechtigungs- und Dateibehandlung; weniger native Kopplung Verfügbarkeit, Rückgabewerte und Gerätebeschränkungen müssen geprüft werden
Node-API-Brücke Vorhandene C/C++-Logik lässt sich sinnvoll wiederverwenden Kann bestehende Fachlogik kapseln und den Neuschreibaufwand begrenzen Build, ABI, SDK, Übergabe von Daten und Berechtigungsgrenzen müssen separat validiert werden
Vollständige Neuentwicklung der Dateilogik Der alte Code setzt nicht verfügbare APIs oder Pfadmodelle voraus Klare Zielarchitektur ohne Kompatibilitätsannahmen Aufwand für Neuimplementierung und umfassende Regressionstests

Braucht der HarmonyOS-PC-Dateizugriff eine Node-API-Brücke?

Nicht automatisch. Wenn es um Auswahl, Lesen und Speichern gewöhnlicher Nutzerdokumente geht, prüfen Sie zuerst die bestätigten ArkTS-Funktionen. Eine Brücke lohnt sich eher, wenn eine bestehende C/C++-Bibliothek komplexe Dateiformate verarbeitet oder fachliche Logik enthält, die nicht sinnvoll neu geschrieben werden kann. Auch dann muss der Zugriff auf Nutzerdateien über die für die Zielplattform bestätigte Berechtigungs- und Auswahlarchitektur laufen.

Vor einer Umsetzung sollten Sie für die Brücke festhalten:

  • welche C/C++-Funktion tatsächlich wiederverwendet wird;
  • welche Daten über die Schnittstellengrenze übergeben werden;
  • wie Fehler und Abbruch zurückgemeldet werden;
  • welches Ziel-SDK und welches Gerät den Build und Laufzeittest bestehen;
  • ob das vorhandene Electron- beziehungsweise Node.js-Modul Quellcode, Build-Anpassungen oder Ersatzkomponenten benötigt.

Die Bezeichnung Node-API allein beweist keine Binärkompatibilität. Behandeln Sie Wiederverwendung daher als technische Hypothese, bis Build, Laden und Funktion auf dem konkreten Zielgerät überprüft sind.

Abnahme: Dateizugriff Ende zu Ende prüfen

Ein erfolgreicher Kompiliervorgang reicht nicht aus. Der Test muss die Nutzerentscheidung, das Ergebnis der Operation und den Zustand nach einem Neustart einbeziehen. Legen Sie für jeden Testfall Zielgerät, SDK-Stand, Berechtigungsstatus, ausgeführte Aktion und beobachtetes Ergebnis fest. Wenn eine Schnittstelle in der verwendeten Testumgebung nicht verfügbar ist, dokumentieren Sie das als blockierenden Befund statt als vorübergehenden UI-Fehler.

Wie lassen sich Lesen, Abbruch und Fehler nach der Migration prüfen?

Verwenden Sie eine Abnahmereihe, die sowohl den Normalfall als auch die Kontrollpfade enthält:

  1. Private App-Daten: Eine Datei innerhalb des bestätigten privaten Speicherbereichs schreiben, erneut lesen und den Inhalt vergleichen.
  2. Autorisierter Zugriff: Den dokumentierten Ablauf für ein öffentliches Verzeichnis durchlaufen und anschließend Lese- und Schreiboperation getrennt prüfen.
  3. Abbruch: Die Auswahl oder Autorisierung schließen, ohne eine Datei freizugeben. Die Oberfläche muss kontrolliert zurückkehren und darf keinen Erfolg melden.
  4. Fehlendes Ziel: Eine erwartete Datei entfernen oder ein nicht verfügbares Ziel verwenden. Die Anwendung muss den Zustand verständlich behandeln, statt einen erfolgreichen Zugriff zu simulieren.
  5. Wiederholte Operation: Dieselbe Aktion erneut ausführen. Prüfen Sie, ob doppelte Dateien, veraltete Zustände oder hängen gebliebene Freigaben entstehen.
  6. Neustart: Die Anwendung schließen und erneut öffnen. Kontrollieren Sie, welche Daten erhalten bleiben und ob gespeicherte Referenzen weiterhin gültig sind.

Diese Reihenfolge ist ein Vorschlag für die Testabdeckung, keine Behauptung über unterstützte APIs. Veröffentlichen Sie konkrete Aussagen zur Geräteunterstützung erst, wenn die Testumgebung samt SDK und Berechtigungsablauf dokumentiert ist. Ein reproduzierbares Protokoll sollte außerdem die erwartete und die tatsächliche Fehlermeldung enthalten.

Abnahmehinweis: Ein erfolgreicher Export beweist nicht, dass alle anderen Zugriffsszenarien freigegeben sind. Prüfen Sie private App-Daten, ausgewählte Dateien und öffentliche Verzeichnisse als getrennte Fälle.

Der sinnvolle nächste Schritt

Wenn Electron derzeit die einzige Entwicklungsumgebung ist, kann sie für Bestandsaufnahme, Schnittstellenentwurf und Teile der C/C++-Arbeit weiterhin genügen. Ihre Nachteile liegen bei der Zielverifikation: Sie belegt keine HarmonyOS-PC-Berechtigung, keinen erfolgreichen Build für ein bestimmtes SDK und kein korrektes Verhalten auf dem Zielgerät. Auch eine Node-API-Brücke behebt diese Lücke nicht von selbst.

Für plattformübergreifende Teams ist deshalb eine klare Trennung sinnvoll: Entwicklungsumgebung, Build-Umgebung und Zielgerät erfüllen unterschiedliche Aufgaben. Prüfen Sie zuerst den ProxyMac-Hilfebereich, wenn Sie verfügbare Arbeitsabläufe für eine entfernte Mac-Umgebung einordnen möchten. Ein gemieteter Mac kann für vorübergehende Entwicklungs- oder Testaufgaben sinnvoll sein; er ist jedoch weder ein HarmonyOS-PC-Zielgerät noch ein Nachweis für eine verifizierte HarmonyOS-Buildumgebung. Wenn ein Mac zu Ihrem tatsächlichen Arbeitsablauf passt, können Sie die Mietoptionen von ProxyMac anhand des eigenen Workloads prüfen. Für dauerhaft hohe Auslastung oder erforderliche physische Schnittstellen kann ein selbst verwaltetes Gerät die passendere Wahl sein.

Für die Migration selbst bleibt der belastbare Weg unverändert: Grenzen des Dateizugriffs neu ziehen, den Vertrag auf Geschäftsaktionen beschränken und jede Aussage zur Unterstützung auf dem konkreten HarmonyOS-PC-Gerät verifizieren.

Testen Sie Dateizugriffe auf einem dedizierten Cloud-Mac

Mit ProxyMac nutzen Sie einen dedizierten Mac mini M4 per SSH, VNC oder Browser für Entwicklung und Tests.
Prüfen Sie Dateioperationen in einer vollständigen macOS-Umgebung mit nativen Entwicklungstools.