12k
All articles

Создаём десктопный файловый менеджер на Electron

Создайте безопасный файловый менеджер на Electron: изолированный рендерер, мост IPC в preload и обработчики main для просмотра, открытия, переименования и удаления файлов в корзину.

OpenReplay Team
OpenReplay Team
Создаём десктопный файловый менеджер на Electron

Файловый менеджер на Electron распределяет работу между тремя процессами. Главный процесс (main) выполняет все операции с файловой системой и оболочкой ОС, preload-скрипт предоставляет несколько именованных функций, а процесс рендеринга (renderer) только отрисовывает список и вызывает эти функции.

Большинство руководств по созданию файлового менеджера на Electron написаны в 2016–2021 годах. В них включают nodeIntegration, вызывают require('fs') прямо со страницы и используют remote. Такой код либо не работает в актуальных версиях Electron, либо оставляет открытую уязвимость. В этом руководстве мы создадим рабочий файловый браузер по современной модели: изолированный в песочнице рендерер, узкий preload-мост и обработчики в главном процессе, которые проверяют каждый полученный путь. Если вы ещё не создавали приложений на Electron, сначала прочитайте Building Desktop Apps with Electron.

Ключевые выводы

  • Модуль shell не работает в рендерере, запущенном в песочнице, поэтому shell.openPath и shell.trashItem должны выполняться в главном процессе за IPC-каналом ipcMain.handle.
  • shell.openPath не отклоняет промис при ошибке. Он разрешается с текстом ошибки, и только пустая строка означает, что файл открылся.
  • fs.rename в Node перезаписывает существующий целевой файл, поэтому перед переименованием проверяйте, что новое имя свободно.
  • Каждая функция в preload должна оборачивать ровно один IPC-канал. Универсальный invoke(channel, ...args) позволяет любому скрипту на странице вызвать любой зарегистрированный вами обработчик.
  • Считайте каждый путь, присланный рендерером, недоверенным. Разрешайте его в главном процессе, сравнивайте с папкой, выбранной пользователем, и отклоняйте всё, что находится за её пределами.

Что мы создадим: файловый менеджер на Electron

Приложение умеет пять вещей: показывать содержимое папки, открывать вложенные папки и файлы, отображать размер и дату изменения каждого элемента, переименовывать элементы и перемещать их в корзину. В таблице показано, где выполняется каждая операция.

ФункцияГде выполняетсяAPIIPC-канал
Выбор корневой папкиMaindialog.showOpenDialogdialog:pickFolder
Список содержимого папкиMainfs.readdir + fs.statfs:list
Открытие вложенной папкиRenderer → Mainснова fs:listfs:list
Открытие файлаMainshell.openPathshell:open
ПереименованиеMainfs.renamefs:rename
Перемещение в корзинуMainshell.trashItemshell:trash

Настройка проекта и безопасные webPreferences

Создайте каркас проекта с помощью шаблона Vite для Electron Forge:

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

Forge помечает поддержку Vite как экспериментальную. Если вам нужен более консервативный вариант, используйте --template=webpack.

Согласно чек-листу безопасности Electron, интеграция с Node отключена по умолчанию начиная с Electron 5, изоляция контекста включена с версии 12, а песочница — с версии 20. И всё же задайте все три параметра явно, чтобы читающему код не приходилось помнить значения по умолчанию:

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

Шаблон Vite в Forge 8 собирает preload-скрипт в файл preload.cjs. Если в сгенерированном main.js указано другое имя файла, оставьте то, что там уже есть.

Отключение изоляции контекста отключает и песочницу рендерера, независимо от значения параметра sandbox. Preload-скрипт в песочнице может вызывать require только для electron (или electron/renderer / electron/common). Согласно Process Sandboxing, встроенные модули Node, Buffer и локальные файлы недоступны, поэтому preload должен состоять из одного файла или собираться в один бандл.

Главный процесс: обработчики файловой системы и shell

В файловом менеджере на Electron вся привилегированная работа выполняется в главном процессе, в файле src/main.js. Модуль shell можно использовать в рендерере, но в песочнице он работать не будет. Поэтому открытие файлов и перемещение их в корзину тоже идут через 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));
});

Разберём, что делает каждая часть кода главного процесса:

  • Получение списка. fs.readdir с параметром withFileTypes возвращает объекты Dirent. fs.stat добавляет размер и время изменения. Promise.allSettled не даёт одной битой символической ссылке сорвать формирование всего списка.
  • Только простые объекты. Каждый элемент преобразуется в простые данные, потому что IPC использует алгоритм структурированного клонирования (Structured Clone), и экземпляр fs.Stats при передаче потерял бы свои методы.
  • Переименование. fs.rename в Node молча заменяет newPath, если он уже существует, поэтому обработчик сначала выполняет проверку. Между проверкой и переименованием остаётся небольшое временное окно, что вполне приемлемо для десктопной утилиты.
  • Открытие. shell.openPath разрешается с текстом ошибки, если открыть файл не удалось, и с пустой строкой в противном случае. Обработчик превращает непустую строку в выброшенное исключение.
  • Корзина. shell.trashItem перемещает элемент в корзину платформы, а не удаляет его безвозвратно. Промис отклоняется, если при удалении элемента произошла ошибка. Документация shell требует нативных разделителей пути, поэтому путь проходит через path.resolve().

Preload: компактный API с именованными функциями

Preload-скрипт предоставляет рендереру пять именованных функций — и ничего больше. В старых руководствах это делали так. Не повторяйте:

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

А вот современный подход, в файле src/preload.js:

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),
});

В каждой функции preload имя IPC-канала жёстко задано в коде. Никогда не пишите invoke: (...a) => ipcRenderer.invoke(...a): это даёт странице доступ ко всем зарегистрированным обработчикам. Также учтите, что когда обработчик, зарегистрированный через ipcMain.handle, выбрасывает исключение, рендерер получает только message ошибки. Пишите сообщения, понятные пользователю. Если IPC-вызов зависает или завершается ошибкой без объяснений, в статье Debugging and Troubleshooting Common Electron Issues описано, как отличить сбои главного процесса от сбоев рендерера.

Рендерер: список, открытие, переименование, корзина

Рендерер работает только с DOM и window.electronAPI. Имена файлов могут содержать разметку, поэтому задавайте их через textContent и никогда — через innerHTML.

Сначала подготовьте на странице место для отрисовки. Замените <body> в index.html из шаблона следующей разметкой, сохранив тег <script> шаблона для src/renderer.js:

<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 не реализует window.prompt(), поэтому окно переименования сделано на основе <dialog>. Затем замените содержимое 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}/..`)));

Двойной щелчок по папке выводит её содержимое. Двойной щелчок по файлу передаёт его операционной системе. Кнопка Up отправляет cwd/... Когда вы дойдёте до корневой папки, главный процесс отклонит запрос, а в строке состояния появится сообщение об ошибке.

Выбор папки через dialog.showOpenDialog

Корневая папка задаётся только через нативный диалог в главном процессе и хранится только там. Рендерер никогда не отправляет корневую папку. Он отправляет пути, а главный процесс сверяет их с уже известной ему корневой папкой. Добавьте этот обработчик в main.js:

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;
});

В API dialog именно свойство openDirectory позволяет выбирать каталоги. Передача окна первым аргументом делает его родительским для диалога, благодаря чему диалог становится модальным. Корневая папка однократно пропускается через realpath здесь же. Благодаря этому символическая ссылка внутри папки, указывающая куда-то ещё, разрешается в путь за пределами корневой папки и не проходит проверку insideRoot.

Подключите выбор папки в рендерере:

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

Усиление защиты: пути, отправители и CSP

Три механизма делают этот файловый браузер на Electron надёжной основой для дальнейшей разработки:

  1. Ограничение путей. Каждый обработчик пропускает входные данные от рендерера через resolveInRoot или resolveEntry. Обе функции разрешают символические ссылки и с помощью path.relative отклоняют всё, что выходит за пределы корневой папки или указывает на другой диск в Windows.
  2. Проверка отправителя. Чек-лист безопасности предписывает проверять отправителя IPC-сообщений, поскольку отправить их может любой фрейм. assertSender принимает вызовы только от webContents окна mainWindow.
  3. Content Security Policy. Страница, загруженная через file://, не может получить CSP в виде HTTP-заголовка, поэтому добавьте meta-тег в index.html:
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">

Дополнительно можно запретить в главном процессе навигацию и открытие новых окон:

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

Заключение

Теперь у вас есть безопасный файловый менеджер на Electron. Главный процесс владеет файловой системой и корневой папкой, preload предоставляет пять фиксированных функций, а рендерер не может получить доступ ни к чему, что вы ему явно не передали. Расширяйте приложение всегда одинаково: один новый обработчик в главном процессе, одна новая функция в preload и те же проверки пути и отправителя для каждого из них. Когда будете готовы к релизу, воспользуйтесь руководством Packaging and Distributing Electron Apps. Если для подобного инструмента вас смущает ресурсоёмкость Electron, прочитайте Comparing Electron and Tauri for Desktop Applications.

Часто задаваемые вопросы

Почему prompt() выбрасывает ошибку в рендерере Electron?

Electron не реализует window.prompt(), поэтому её вызов выбрасывает ошибку вместо открытия диалога. Функции alert() и confirm() в Electron работают. Чтобы запросить новое имя файла, используйте текстовое поле на странице или HTML-элемент dialog. Также можно открыть из главного процесса небольшое модальное окно BrowserWindow и вернуть введённое значение через IPC.

Как получить реальный путь к файлу, перетащенному в окно Electron?

Вызовите webUtils.getPathForFile(file) в preload-скрипте и предоставьте эту функцию через contextBridge. В Electron 32 было удалено нестандартное свойство File.path у веб-объекта File, поэтому код, читающий file.path, больше не получает путь. Отправьте полученный путь обработчику в главном процессе и примените к нему ту же проверку корневой папки, что и к любым другим входным данным от рендерера.

Как автоматически обновлять список файлов при изменениях на диске?

Отслеживайте отображаемую папку с помощью fs.watch в главном процессе и отправляйте уведомление странице через mainWindow.webContents.send. В preload оберните ipcRenderer.on так, чтобы колбэк рендерера вызывался без объекта события: передача события открывает странице доступ к ipcRenderer. Воспринимайте каждое событие лишь как сигнал заново выполнить fs:list. Node сообщает только о событиях 'rename' и 'change', а имя файла может быть null.

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.