用 Electron 构建桌面文件管理器
使用沙盒化渲染进程、preload IPC 桥接和 main 进程处理程序,构建安全的 Electron 文件管理器,实现浏览、打开、重命名和移入回收站。
Electron 文件管理器将工作分摊到三个进程中:主进程执行所有文件系统和 shell 操作,preload 脚本暴露少数几个具名函数,而渲染进程只负责绘制列表并调用这些函数。
你能找到的大多数 Electron 文件管理器教程都写于 2016 年至 2021 年间。它们会开启 nodeIntegration,在页面中调用 require('fs'),还会用到 remote。以这种方式编写的代码要么在当前版本的 Electron 上无法运行,要么会留下安全漏洞。本指南采用当前的推荐模型构建一个可用的文件浏览器:沙箱化的渲染进程、精简的 preload 桥接层,以及会校验每个传入路径的主进程处理函数。如果你之前没有构建过 Electron 应用,请先阅读 Building Desktop Apps with Electron。
核心要点
shell模块在沙箱化的渲染进程中无法工作,因此shell.openPath和shell.trashItem必须在主进程中运行,并通过ipcMain.handle通道调用。shell.openPath失败时不会 reject,而是 resolve 一条错误信息,只有返回空字符串才表示文件已成功打开。- Node 的
fs.rename会覆盖已存在的目标文件,因此在重命名前要先确认目标名称未被占用。 - 每个 preload 函数应只封装一个 IPC 通道。通用的
invoke(channel, ...args)会让页面中的任何脚本都能调用你注册的所有处理函数。 - 将渲染进程发送的每个路径都视为不可信输入。在主进程中解析路径,将其与用户选定的文件夹进行比对,并拒绝该文件夹之外的任何路径。
你将构建什么:一个 Electron 文件管理器
这个应用实现五项功能:列出文件夹内容、打开子文件夹和文件、显示每个条目的大小和修改日期、重命名条目,以及将条目移至回收站。下表列出了每项操作的运行位置。
| 功能 | 运行位置 | API | IPC 通道 |
|---|---|---|---|
| 选择根文件夹 | 主进程 | dialog.showOpenDialog | dialog:pickFolder |
| 列出文件夹内容 | 主进程 | fs.readdir + fs.stat | fs:list |
| 打开子文件夹 | 渲染进程 → 主进程 | 再次调用 fs:list | fs:list |
| 打开文件 | 主进程 | shell.openPath | shell:open |
| 重命名 | 主进程 | fs.rename | fs:rename |
| 移至回收站 | 主进程 | shell.trashItem | shell:trash |
项目初始化与安全的 webPreferences 配置
使用 Electron Forge 的 Vite 模板搭建项目脚手架:
npx create-electron-app@latest my-app --template=vite
Forge 将其 Vite 支持标记为实验性功能。如果你想要更稳妥的选择,可以使用 --template=webpack。
根据 Electron 安全检查清单,Node 集成从 Electron 5 起默认关闭,上下文隔离从 Electron 12 起默认开启,沙箱从 Electron 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
Forge 8 的 Vite 模板会将 preload 脚本构建为 preload.cjs。如果你生成的 main.js 使用了不同的文件名,请保留原有的文件名。
关闭上下文隔离也会同时关闭渲染进程沙箱,无论 sandbox 选项如何设置。沙箱化的 preload 只能 require('electron')(或 electron/renderer / electron/common)。进程沙箱化禁止使用 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));
});
以下是主进程代码各部分的作用:
- 列出内容。 带
withFileTypes选项的fs.readdir返回Dirent对象,fs.stat则补充文件大小和修改时间。Promise.allSettled可以避免单个损坏的符号链接导致整个列表加载失败。 - 只传递普通对象。 每个条目都被映射为普通数据,因为 IPC 使用结构化克隆算法,
fs.Stats实例在跨进程传递时会丢失其方法。 - 重命名。 如果
newPath已存在,Node 的fs.rename会静默替换它,因此处理函数会先进行检查。检查与重命名之间存在一个很小的时间窗口,对于桌面工具来说这是可以接受的。 - 打开。 如果打开失败,
shell.openPath会 resolve 错误信息,否则 resolve 空字符串。处理函数会将非空字符串转换为抛出的错误。 - 移至回收站。
shell.trashItem会将条目移至系统回收站,而不是永久删除。如果删除目标条目时出错,它会 reject。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。
首先,为页面提供渲染容器。将模板 index.html 中的 <body> 替换为以下标记,并保留模板中加载 src/renderer.js 的 <script> 标签:
<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;
});
在 dialog API 中,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 消息的发送方,因为任何 frame 都可以发送 IPC 消息。
assertSender只接受来自mainWindow的webContents的调用。 - 内容安全策略(CSP)。 通过
file://加载的页面无法以 HTTP 头的形式接收 CSP,因此需要在index.html中添加 meta 标签:
<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。
常见问题
为什么在 Electron 渲染进程中调用 prompt() 会抛出错误?
Electron 没有实现 window.prompt(),因此调用它会抛出错误,而不会打开对话框。alert() 和 confirm() 函数在 Electron 中可以正常使用。如需让用户输入新文件名,可以使用页面内的文本输入框或 HTML dialog 元素。你也可以从主进程打开一个小型模态 BrowserWindow,再通过 IPC 将输入的值传回。
如何获取拖放到 Electron 窗口上的文件的真实路径?
在 preload 脚本中调用 webUtils.getPathForFile(file),并通过 contextBridge 将其暴露出去。Electron 32 移除了 Web File 对象上非标准的 File.path 属性,因此读取 file.path 的代码将无法再获得路径。将返回的路径发送给主进程处理函数,并像对待其他渲染进程输入一样,对其执行相同的根文件夹校验。
如何在磁盘上的文件发生变化时自动刷新文件列表?
在主进程中使用 fs.watch 监听当前列出的文件夹,并通过 mainWindow.webContents.send 向页面推送通知。在 preload 中封装 ipcRenderer.on,使其调用渲染进程的回调时不传递 event 对象,因为传递 event 会将 ipcRenderer 暴露给页面。将每个事件仅视为重新执行 fs:list 的信号。Node 只会报告 'rename' 和 'change' 两种事件,且 filename 可能为 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