Создаём десктопный файловый менеджер на Electron
Создайте безопасный файловый менеджер на Electron: изолированный рендерер, мост IPC в preload и обработчики main для просмотра, открытия, переименования и удаления файлов в корзину.
Файловый менеджер на 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
Приложение умеет пять вещей: показывать содержимое папки, открывать вложенные папки и файлы, отображать размер и дату изменения каждого элемента, переименовывать элементы и перемещать их в корзину. В таблице показано, где выполняется каждая операция.
| Функция | Где выполняется | API | IPC-канал |
|---|---|---|---|
| Выбор корневой папки | Main | dialog.showOpenDialog | dialog:pickFolder |
| Список содержимого папки | Main | fs.readdir + fs.stat | fs:list |
| Открытие вложенной папки | Renderer → Main | снова fs:list | fs:list |
| Открытие файла | Main | shell.openPath | shell:open |
| Переименование | Main | fs.rename | fs:rename |
| Перемещение в корзину | Main | shell.trashItem | shell: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 надёжной основой для дальнейшей разработки:
- Ограничение путей. Каждый обработчик пропускает входные данные от рендерера через
resolveInRootилиresolveEntry. Обе функции разрешают символические ссылки и с помощьюpath.relativeотклоняют всё, что выходит за пределы корневой папки или указывает на другой диск в Windows. - Проверка отправителя. Чек-лист безопасности предписывает проверять отправителя IPC-сообщений, поскольку отправить их может любой фрейм.
assertSenderпринимает вызовы только отwebContentsокнаmainWindow. - 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.
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