12k
All articles

Einen Desktop-Dateimanager mit Electron erstellen

Erstellen Sie einen sicheren Electron-Dateimanager mit isoliertem Renderer, IPC-Preload-Brücke und Main-Prozess-Handlern zum Durchsuchen, Öffnen, Umbenennen und Löschen von Dateien.

OpenReplay Team
OpenReplay Team
Einen Desktop-Dateimanager mit Electron erstellen

Ein Electron-Dateimanager verteilt die Arbeit auf drei Prozesse. Der Main-Prozess führt sämtliche Dateisystem- und Shell-Operationen aus, das Preload-Skript stellt einige wenige benannte Funktionen bereit, und der Renderer zeichnet lediglich die Liste und ruft diese Funktionen auf.

Die meisten Dateimanager-Tutorials für Electron stammen aus den Jahren 2016 bis 2021. Sie aktivieren nodeIntegration, rufen require('fs') direkt aus der Seite auf und greifen auf remote zurück. So geschriebener Code funktioniert mit aktuellen Electron-Versionen entweder nicht mehr oder hinterlässt eine Sicherheitslücke. Diese Anleitung baut einen funktionsfähigen Dateibrowser nach dem aktuellen Modell: ein Renderer in der Sandbox, eine schmale Preload-Bridge und Handler im Main-Prozess, die jeden übergebenen Pfad prüfen. Falls Sie noch keine Electron-App gebaut haben, lesen Sie zuerst Building Desktop Apps with Electron.

Das Wichtigste in Kürze

  • Das shell-Modul funktioniert nicht in einem Renderer mit Sandbox. shell.openPath und shell.trashItem müssen daher im Main-Prozess hinter einem ipcMain.handle-Channel laufen.
  • shell.openPath wird bei einem Fehler nicht abgelehnt (reject). Das Promise wird mit einer Fehlermeldung aufgelöst, und nur ein leerer String bedeutet, dass die Datei geöffnet wurde.
  • Nodes fs.rename überschreibt ein bereits vorhandenes Ziel. Prüfen Sie daher vor dem Umbenennen, ob der Zielname noch frei ist.
  • Jede Preload-Funktion sollte genau einen IPC-Channel kapseln. Ein generisches invoke(channel, ...args) erlaubt jedem Skript auf der Seite, jeden registrierten Handler aufzurufen.
  • Behandeln Sie jeden Pfad, den der Renderer sendet, als nicht vertrauenswürdig. Lösen Sie ihn im Main-Prozess auf, vergleichen Sie ihn mit dem vom Benutzer gewählten Ordner und weisen Sie alles außerhalb dieses Ordners zurück.

Was Sie bauen: einen Electron-Dateimanager

Die App erledigt fünf Aufgaben: Sie listet einen Ordner auf, öffnet Unterordner und Dateien, zeigt Größe und Änderungsdatum jedes Eintrags an, benennt Einträge um und verschiebt sie in den Papierkorb. Die Tabelle zeigt, wo jede Operation ausgeführt wird.

FunktionLäuft inAPIIPC-Channel
Stammordner auswählenMaindialog.showOpenDialogdialog:pickFolder
Ordner auflistenMainfs.readdir + fs.statfs:list
Unterordner öffnenRenderer → Mainerneut fs:listfs:list
Datei öffnenMainshell.openPathshell:open
UmbenennenMainfs.renamefs:rename
In den Papierkorb verschiebenMainshell.trashItemshell:trash

Projekt-Setup und sichere webPreferences

Erstellen Sie das Projektgerüst mit dem Vite-Template von Electron Forge:

npx create-electron-app@latest my-app --template=vite

Forge kennzeichnet seine Vite-Unterstützung als experimentell. Wenn Sie die konservativere Variante bevorzugen, verwenden Sie --template=webpack.

Laut der Electron-Sicherheitscheckliste ist die Node-Integration seit Electron 5 standardmäßig deaktiviert, die Kontextisolierung seit Version 12 aktiviert und die Sandbox seit Version 20 aktiv. Setzen Sie trotzdem alle drei Optionen explizit, damit sich niemand, der den Code liest, an die Standardwerte erinnern muss:

mainWindow = new BrowserWindow({
  width: 960,
  height: 640,
  webPreferences: {
    preload: path.join(__dirname, 'preload.cjs'),
    contextIsolation: true, // preload and page get separate JS worlds
    nodeIntegration: false, // no require() in the page
    sandbox: true,          // renderer runs under Chromium's sandbox
  },
});
// keep the template's existing loadURL / loadFile lines below this

Das Vite-Template von Forge 8 baut das Preload-Skript als preload.cjs. Falls Ihre generierte main.js einen anderen Dateinamen verwendet, behalten Sie den vorhandenen bei.

Wird die Kontextisolierung deaktiviert, ist automatisch auch die Renderer-Sandbox deaktiviert – unabhängig davon, was in der Option sandbox steht. Ein Preload-Skript in der Sandbox kann ausschließlich require('electron') (bzw. electron/renderer / electron/common) laden. Process Sandboxing schließt Node-Built-ins, Buffer und lokale Dateien aus. Das Preload-Skript muss daher aus einer einzigen Datei bestehen oder zu einer gebündelt werden.

Main-Prozess: Dateisystem- und Shell-Handler

In einem Electron-Dateimanager findet die gesamte privilegierte Arbeit im Main-Prozess statt, also in src/main.js. Das shell-Modul lässt sich zwar in einem Renderer verwenden, funktioniert aber nicht in einem Renderer mit Sandbox. Deshalb laufen auch das Öffnen von Dateien und das Verschieben in den Papierkorb über IPC.

const { app, BrowserWindow, ipcMain, dialog, shell } = require('electron');
const path = require('node:path');
const fs = require('node:fs/promises');

let mainWindow = null;
let rootDir = null; // set only by the folder picker

function assertSender(event) {
  if (BrowserWindow.fromWebContents(event.sender) !== mainWindow) {
    throw new Error('Untrusted sender');
  }
}

function insideRoot(target) {
  const rel = path.relative(rootDir, target);
  return rel === '' ||
    (rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel));
}

async function resolveInRoot(p) {
  if (!rootDir) throw new Error('Pick a folder first');
  const abs = await fs.realpath(path.resolve(String(p)));
  if (!insideRoot(abs)) throw new Error('Path is outside the chosen folder');
  return abs;
}

// Realpath the parent only, so rename/trash act on a symlink, not its target
async function resolveEntry(p) {
  const abs = path.resolve(String(p));
  const parent = await resolveInRoot(path.dirname(abs));
  return path.join(parent, path.basename(abs));
}

function handle(channel, fn) {
  ipcMain.handle(channel, async (event, ...args) => {
    assertSender(event);
    return fn(...args);
  });
}

handle('fs:list', async (dir) => {
  const abs = await resolveInRoot(dir ?? rootDir);
  const dirents = await fs.readdir(abs, { withFileTypes: true });
  const settled = await Promise.allSettled(dirents.map(async (d) => {
    const full = path.join(abs, d.name);
    const st = await fs.stat(full);
    return { name: d.name, path: full, isDir: st.isDirectory(),
             isLink: d.isSymbolicLink(), size: st.size, mtimeMs: st.mtimeMs };
  }));
  const entries = settled.filter((r) => r.status === 'fulfilled').map((r) => r.value)
    .sort((a, b) => (b.isDir - a.isDir) || a.name.localeCompare(b.name));
  return { dir: abs, entries };
});

handle('fs:rename', async (target, newName) => {
  const name = String(newName).trim();
  if (!name || name === '.' || name === '..' || name.includes('/') || name.includes(path.sep)) {
    throw new Error('Invalid file name');
  }
  const src = await resolveEntry(target);
  const dest = path.join(path.dirname(src), name);
  if (!insideRoot(dest)) throw new Error('Path is outside the chosen folder');
  const taken = await fs.access(dest).then(() => true, () => false);
  if (taken) throw new Error(`"${name}" already exists`);
  await fs.rename(src, dest);
});

handle('shell:open', async (target) => {
  const err = await shell.openPath(await resolveInRoot(target));
  if (err) throw new Error(err);
});

handle('shell:trash', async (target) => {
  const abs = await resolveEntry(target);
  if (abs === rootDir) throw new Error('Cannot trash the root folder');
  await shell.trashItem(path.resolve(abs));
});

Die einzelnen Teile des Main-Prozess-Codes haben folgende Aufgaben:

  • Auflisten. fs.readdir mit withFileTypes liefert Dirent-Objekte. fs.stat ergänzt Größe und Änderungszeitpunkt. Promise.allSettled verhindert, dass ein einzelner defekter Symlink die gesamte Auflistung scheitern lässt.
  • Nur einfache Objekte. Jeder Eintrag wird auf einfache Daten abgebildet, da IPC den Structured-Clone-Algorithmus verwendet und eine fs.Stats-Instanz bei der Übertragung ihre Methoden verlieren würde.
  • Umbenennen. Nodes fs.rename ersetzt newPath stillschweigend, falls dieser bereits existiert. Deshalb prüft der Handler das vorher. Zwischen Prüfung und Umbenennung bleibt ein kleines Zeitfenster, das für ein Desktop-Tool jedoch vertretbar ist.
  • Öffnen. shell.openPath wird mit der Fehlermeldung aufgelöst, wenn das Öffnen fehlgeschlagen ist, andernfalls mit einem leeren String. Der Handler wandelt einen nicht leeren String in einen geworfenen Fehler um.
  • Papierkorb. shell.trashItem verschiebt das Element in den Papierkorb der jeweiligen Plattform, statt es endgültig zu löschen. Das Promise wird abgelehnt, wenn beim Löschen des angeforderten Elements ein Fehler auftritt. Laut der shell-Dokumentation sind native Pfadtrennzeichen erforderlich, weshalb der Pfad durch path.resolve() geleitet wird.

Preload: eine kleine, benannte API

Das Preload-Skript stellt dem Renderer fünf benannte Funktionen bereit und sonst nichts. Ältere Tutorials haben das so gelöst – bitte nicht nachmachen:

// Outdated pattern. Never ship this.
webPreferences: { nodeIntegration: true, contextIsolation: false }
const fs = require('fs'); // in the page

So sieht das aktuelle Muster in src/preload.js aus:

const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
  listDir: (dir) => ipcRenderer.invoke('fs:list', dir),
  pickFolder: () => ipcRenderer.invoke('dialog:pickFolder'),
  openPath: (p) => ipcRenderer.invoke('shell:open', p),
  rename: (p, newName) => ipcRenderer.invoke('fs:rename', p, newName),
  trash: (p) => ipcRenderer.invoke('shell:trash', p),
});

In jeder Preload-Funktion ist der Name des IPC-Channels fest codiert. Schreiben Sie niemals invoke: (...a) => ipcRenderer.invoke(...a), denn damit erhält die Seite Zugriff auf jeden Handler, den Sie registrieren. Beachten Sie außerdem: Wenn ein mit ipcMain.handle registrierter Handler einen Fehler wirft, erhält der Renderer nur die message des Fehlers. Formulieren Sie Fehlermeldungen also so, dass Benutzer sie verstehen. Falls ein IPC-Aufruf hängt oder ohne Erklärung fehlschlägt, erläutert Debugging and Troubleshooting Common Electron Issues, wie Sie Fehler im Main-Prozess von Fehlern im Renderer unterscheiden.

Renderer: Auflisten, Öffnen, Umbenennen, Papierkorb

Der Renderer greift ausschließlich auf das DOM und window.electronAPI zu. Dateinamen können Markup enthalten. Setzen Sie sie daher mit textContent und niemals mit innerHTML.

Geben Sie der Seite zunächst einen Bereich, in den gerendert werden kann. Ersetzen Sie den <body> der index.html aus dem Template durch das folgende Markup und behalten Sie dabei das <script>-Tag des Templates für src/renderer.js bei:

<body>
  <header>
    <button id="pick">Choose folder</button>
    <button id="up">Up</button>
    <span id="status" role="status"></span>
  </header>
  <ul id="list"></ul>
  <dialog id="rename-dialog">
    <form method="dialog">
      <label>New name <input id="rename-input" required></label>
      <button value="cancel" formnovalidate>Cancel</button>
      <button value="ok">Rename</button>
    </form>
  </dialog>
  <script type="module" src="/src/renderer.js"></script>
</body>

Electron implementiert window.prompt() nicht, deshalb ist das Umbenennungsfeld als <dialog> umgesetzt. Ersetzen Sie anschließend den Inhalt von src/renderer.js:

const api = window.electronAPI;
const list = document.querySelector('#list');
const status = document.querySelector('#status');
const renameDialog = document.querySelector('#rename-dialog');
const renameInput = document.querySelector('#rename-input');
let cwd = null;

function askName(current) {
  renameInput.value = current;
  renameDialog.returnValue = '';
  renameDialog.showModal();
  return new Promise((resolve) => {
    renameDialog.addEventListener('close', () =>
      resolve(renameDialog.returnValue === 'ok' ? renameInput.value : null), { once: true });
  });
}

const fmtSize = (n) => {
  const u = ['B', 'KB', 'MB', 'GB', 'TB']; let i = 0;
  while (n >= 1024 && i < u.length - 1) { n /= 1024; i++; }
  return `${n.toFixed(i ? 1 : 0)} ${u[i]}`;
};

async function run(fn) {
  try { status.textContent = ''; await fn(); }
  catch (err) { status.textContent = err.message; }
}

async function load(dir) {
  const res = await api.listDir(dir);
  cwd = res.dir;
  list.replaceChildren(...res.entries.map(row));
}

function button(label, onClick) {
  const b = document.createElement('button');
  b.textContent = label;
  b.addEventListener('click', (e) => { e.stopPropagation(); run(onClick); });
  return b;
}

function row(entry) {
  const li = document.createElement('li');
  const cells = [entry.isDir ? `${entry.name}/` : entry.name,
    entry.isDir ? '' : fmtSize(entry.size),
    new Date(entry.mtimeMs).toLocaleString()];
  for (const text of cells) {
    const span = document.createElement('span');
    span.textContent = text;
    li.append(span);
  }
  li.append(
    button('Rename', async () => {
      const name = await askName(entry.name);
      if (name && name !== entry.name) { await api.rename(entry.path, name); await load(cwd); }
    }),
    button('Trash', async () => {
      if (confirm(`Move "${entry.name}" to the trash?`)) { await api.trash(entry.path); await load(cwd); }
    }),
  );
  li.addEventListener('dblclick', () =>
    run(() => (entry.isDir ? load(entry.path) : api.openPath(entry.path))));
  return li;
}

document.querySelector('#up').addEventListener('click', () => run(() => load(`${cwd}/..`)));

Ein Doppelklick auf einen Ordner listet dessen Inhalt auf. Ein Doppelklick auf eine Datei übergibt sie an das Betriebssystem. Die Schaltfläche Up sendet cwd/... Sobald der Stammordner erreicht ist, lehnt der Main-Prozess die Anfrage ab, und die Statuszeile zeigt den Fehler an.

Ordnerauswahl mit dialog.showOpenDialog

Der Stammordner stammt ausschließlich aus einem nativen Dialog im Main-Prozess und wird auch nur dort gespeichert. Der Renderer sendet niemals einen Stammordner. Er sendet Pfade, und der Main-Prozess prüft sie gegen den Stammordner, den er bereits kennt. Fügen Sie diesen Handler in main.js ein:

handle('dialog:pickFolder', async () => {
  const { canceled, filePaths } = await dialog.showOpenDialog(mainWindow, {
    properties: ['openDirectory'],
  });
  if (canceled) return null;
  rootDir = await fs.realpath(filePaths[0]);
  return rootDir;
});

In der dialog-API sorgt die Eigenschaft openDirectory dafür, dass Verzeichnisse ausgewählt werden können. Wird das Fenster als erstes Argument übergeben, wird es dem Dialog als übergeordnetes Fenster zugewiesen, wodurch der Dialog modal wird. Der Stammordner wird hier einmalig durch realpath geleitet. So wird ein Symlink innerhalb des Ordners, der auf ein anderes Ziel verweist, auf einen Pfad außerhalb des Stammordners aufgelöst und scheitert an insideRoot.

Binden Sie die Ordnerauswahl im Renderer an:

document.querySelector('#pick').addEventListener('click', () => run(async () => {
  const dir = await api.pickFolder();
  if (dir) await load(dir);
}));

Härtung: Pfade, Absender und CSP

Drei Schutzmaßnahmen machen diesen Electron-Dateibrowser zu einer sicheren Grundlage für Erweiterungen:

  1. Pfadbegrenzung. Jeder Handler leitet Eingaben aus dem Renderer durch resolveInRoot oder resolveEntry. Beide lösen Symlinks auf und verwenden path.relative, um alles zurückzuweisen, was aus dem Stammordner herausführt oder auf einem anderen Windows-Laufwerk landet.
  2. Absendervalidierung. Die Sicherheitscheckliste empfiehlt, den Absender von IPC-Nachrichten zu validieren, da jeder Frame solche Nachrichten senden kann. assertSender akzeptiert nur Aufrufe von den webContents des mainWindow.
  3. Content Security Policy. Eine über file:// geladene Seite kann die CSP nicht als HTTP-Header empfangen. Fügen Sie daher ein Meta-Tag in die index.html ein:
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">

Optional können Sie Navigation und neue Fenster im Main-Prozess blockieren:

mainWindow.webContents.on('will-navigate', (e) => e.preventDefault());
mainWindow.webContents.setWindowOpenHandler(() => ({ action: 'deny' }));

Fazit

Sie verfügen nun über einen sicheren Electron-Dateimanager. Der Main-Prozess verwaltet das Dateisystem und den Stammordner, das Preload-Skript stellt fünf feste Funktionen bereit, und der Renderer hat auf nichts Zugriff, was Sie ihm nicht ausdrücklich übergeben haben. Erweitern Sie die App stets nach demselben Muster: ein neuer Handler im Main-Prozess, eine neue Funktion im Preload-Skript und bei jedem Handler dieselben Pfad- und Absenderprüfungen. Wenn Sie bereit für die Auslieferung sind, folgen Sie Packaging and Distributing Electron Apps. Falls der Ressourcenbedarf von Electron für ein solches Tool ein Problem darstellt, lesen Sie Comparing Electron and Tauri for Desktop Applications.

Häufig gestellte Fragen

Warum wirft prompt() in einem Electron-Renderer einen Fehler?

Electron implementiert window.prompt() nicht, daher wirft ein Aufruf einen Fehler, statt einen Dialog zu öffnen. Die Funktionen alert() und confirm() funktionieren in Electron hingegen. Um einen neuen Dateinamen abzufragen, verwenden Sie ein Texteingabefeld auf der Seite oder ein HTML-dialog-Element. Alternativ können Sie aus dem Main-Prozess ein kleines modales BrowserWindow öffnen und den eingegebenen Wert per IPC zurücksenden.

Wie erhalte ich den tatsächlichen Pfad einer Datei, die auf ein Electron-Fenster gezogen wurde?

Rufen Sie im Preload-Skript webUtils.getPathForFile(file) auf und stellen Sie die Funktion über contextBridge bereit. Electron 32 hat die nicht standardisierte Eigenschaft File.path aus dem Web-File-Objekt entfernt, sodass Code, der file.path ausliest, keinen Pfad mehr erhält. Senden Sie den zurückgegebenen Pfad an einen Handler im Main-Prozess und unterziehen Sie ihn derselben Stammordnerprüfung wie jede andere Eingabe aus dem Renderer.

Wie kann sich die Dateiliste automatisch aktualisieren, wenn sich Dateien auf der Festplatte ändern?

Überwachen Sie den aufgelisteten Ordner im Main-Prozess mit fs.watch und senden Sie mit mainWindow.webContents.send eine Benachrichtigung an die Seite. Kapseln Sie im Preload-Skript ipcRenderer.on so, dass der Callback des Renderers ohne das Event-Objekt aufgerufen wird, denn die Weitergabe des Events würde ipcRenderer für die Seite zugänglich machen. Behandeln Sie jedes Event lediglich als Signal, fs:list erneut auszuführen. Node meldet nur 'rename' und 'change', und der Dateiname kann null sein.

DevTools for the frontend

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers.

Star on GitHub12k

We use cookies to improve your experience. By using our site, you accept cookies.