Electron でデスクトップ用ファイルマネージャーを構築する
サンドボックス化したレンダラー、preloadのIPCブリッジ、mainプロセスのハンドラーを使い、安全なElectronファイルマネージャーを構築。閲覧、起動、名前変更、ゴミ箱への移動を実装します。
Electron 製のファイルマネージャーでは、処理を 3 つのプロセスに分担させます。メインプロセスはファイルシステムとシェルの操作をすべて実行し、プリロードスクリプトは名前付きの関数をいくつか公開し、レンダラーは一覧の描画とそれらの関数の呼び出しだけを行います。
Electron 向けのファイルマネージャーのチュートリアルの多くは 2016 年から 2021 年ごろに書かれたものです。それらは nodeIntegration を有効にし、ページから require('fs') を呼び出し、remote を利用しています。こうしたコードは現行の Electron では動作しないか、セキュリティホールを残してしまいます。本ガイドでは、現在推奨されるモデルに沿って動作するファイルブラウザーを構築します。具体的には、サンドボックス化されたレンダラー、必要最小限のプリロードブリッジ、そして受け取ったパスをすべて検証するメインプロセスのハンドラーで構成します。Electron アプリを作ったことがない方は、先に Building Desktop Apps with Electron をお読みください。
重要なポイント
shellモジュールはサンドボックス化されたレンダラーでは動作しません。そのため、shell.openPathとshell.trashItemはipcMain.handleチャンネルを介してメインプロセスで実行する必要があります。shell.openPathは失敗しても reject しません。エラーメッセージを返して resolve し、空文字列が返された場合のみファイルが開けたことを意味します。- Node の
fs.renameは既存の移動先を上書きします。名前を変更する前に、変更後の名前が使われていないことを確認してください。 - プリロードの各関数は、IPC チャンネルを 1 つだけラップするようにします。汎用的な
invoke(channel, ...args)を公開すると、ページ内のどのスクリプトからでも登録済みのすべてのハンドラーを呼び出せてしまいます。 - レンダラーから送られてくるパスはすべて信頼できないものとして扱います。メインプロセスでパスを解決し、ユーザーが選択したフォルダーと比較して、そのフォルダー外を指すものはすべて拒否してください。
構築するもの: Electron 製ファイルマネージャー
このアプリが行うことは 5 つです。フォルダーの一覧表示、サブフォルダーやファイルを開く操作、各エントリのサイズと更新日時の表示、エントリの名前変更、そしてゴミ箱への移動です。各操作がどこで実行されるかを次の表に示します。
| 機能 | 実行場所 | 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 サポートは実験的(experimental)という位置づけです。より保守的な選択肢を望む場合は、--template=webpack を使用してください。
Electron のセキュリティチェックリストによると、Node integration は Electron 5 以降デフォルトで無効、コンテキストの分離は 12 以降デフォルトで有効、サンドボックスは 20 以降デフォルトで有効になっています。それでも、コードを読む人がデフォルト値を覚えておかなくて済むように、3 つすべてを明示的に設定しておきましょう。
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.cjs としてビルドします。生成された main.js で別のファイル名が使われている場合は、そのファイル名をそのまま使ってください。
コンテキストの分離を無効にすると、sandbox オプションの値にかかわらず、レンダラーのサンドボックスも無効になります。サンドボックス化されたプリロードで require できるのは electron(または electron/renderer / electron/common)のみです。Process Sandboxing により Node の組み込みモジュール、Buffer、ローカルファイルは利用できないため、プリロードは単一ファイルにするか、1 つのファイルにバンドルする必要があります。
メインプロセス: ファイルシステムとシェルのハンドラー
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を使うことで、壊れたシンボリックリンクが 1 つあっても一覧全体が失敗することはありません。 - プレーンなオブジェクトのみを返す: IPC は構造化複製アルゴリズム(Structured Clone algorithm)を使用しており、
fs.Statsインスタンスはプロセス間で受け渡される際にメソッドが失われてしまいます。そのため、各エントリをプレーンなデータに変換しています。 - 名前の変更: Node の
fs.renameは、newPathがすでに存在する場合、警告なしに置き換えます。ハンドラーで事前に確認しているのはこのためです。確認から名前変更までの間にわずかな時間差がありますが、デスクトップツールとしては許容範囲です。 - ファイルを開く:
shell.openPathは、開くのに失敗した場合はエラーメッセージを、成功した場合は空文字列を返して resolve します。ハンドラーでは、空でない文字列が返ってきたらエラーとして throw するように変換しています。 - ゴミ箱へ移動:
shell.trashItemは、項目を完全に削除するのではなく、プラットフォームのゴミ箱に移動します。指定した項目の削除中にエラーが発生した場合は reject します。shellのドキュメントではネイティブの区切り文字を使うことが求められているため、パスをpath.resolve()に通しています。
プリロード: 小さな名前付き API
プリロードスクリプトは、5 つの名前付き関数だけをレンダラーに公開し、それ以外は何も公開しません。古いチュートリアルでは次のように書かれていましたが、これは避けてください。
// 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),
});
プリロードの各関数では、IPC チャンネル名をハードコードしています。invoke: (...a) => ipcRenderer.invoke(...a) のような書き方は絶対にしないでください。登録したすべてのハンドラーにページからアクセスできるようになってしまいます。また、ipcMain.handle で登録したハンドラーが例外を throw した場合、レンダラーが受け取るのはエラーの message だけである点にも注意してください。ユーザーが読んで理解できるメッセージにしておきましょう。IPC 呼び出しが応答しなくなったり、原因不明のまま失敗したりする場合は、Debugging and Troubleshooting Common Electron Issues で、メインプロセス側の不具合とレンダラー側の不具合を見分ける方法を解説しています。
レンダラー: 一覧表示、開く、名前変更、ゴミ箱へ移動
レンダラーが触れるのは DOM と window.electronAPI だけです。ファイル名にはマークアップが含まれる可能性があるため、innerHTML ではなく必ず textContent で設定してください。
まず、ページに描画先となる要素を用意します。テンプレートの 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}/..`)));
フォルダーをダブルクリックすると、その中身が一覧表示されます。ファイルをダブルクリックすると、そのファイルが OS に渡されます。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 プロパティを指定することでディレクトリを選択できるようになります。第 1 引数にウィンドウを渡すと、そのウィンドウが親としてダイアログに紐付けられ、ダイアログはモーダルになります。ここでルートを一度 realpath に通しておきます。こうすることで、フォルダー内にある別の場所を指すシンボリックリンクはルート外のパスに解決され、insideRoot のチェックで弾かれます。
レンダラー側でフォルダー選択を接続します。
document.querySelector('#pick').addEventListener('click', () => run(async () => {
const dir = await api.pickFolder();
if (dir) await load(dir);
}));
セキュリティ強化: パス、送信元、CSP
この Electron 製ファイルブラウザーを安全に拡張していくための基盤となる対策は、次の 3 つです。
- パスの封じ込め: すべてのハンドラーは、レンダラーからの入力を
resolveInRootまたはresolveEntryに通します。どちらもシンボリックリンクを解決し、path.relativeを使ってルートの外に出るパスや Windows の別ドライブを指すパスを拒否します。 - 送信元の検証: IPC メッセージはどのフレームからでも送信できるため、セキュリティチェックリストでは IPC メッセージの送信元を検証するよう求めています。
assertSenderは、mainWindowのwebContentsからの呼び出しのみを受け付けます。 - Content Security Policy:
file://から読み込まれたページは CSP を HTTP ヘッダーとして受け取れないため、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 製ファイルマネージャーが完成しました。メインプロセスがファイルシステムとルートフォルダーを管理し、プリロードは固定された 5 つの関数を公開し、レンダラーは明示的に渡されたもの以外には一切アクセスできません。機能を拡張するときも、毎回同じ方法で行います。メインプロセスにハンドラーを 1 つ追加し、プリロードに関数を 1 つ追加し、それぞれに同じパスと送信元のチェックを適用します。配布の準備ができたら、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 のウィンドウにドロップされたファイルの実際のパスを取得するにはどうすればよいですか?
プリロードスクリプトで webUtils.getPathForFile(file) を呼び出し、contextBridge を通じて公開します。Electron 32 で Web の File オブジェクトから非標準の File.path プロパティが削除されたため、file.path を読み取るコードではパスを取得できなくなりました。返されたパスはメインプロセスのハンドラーに送り、ほかのレンダラーからの入力と同様にルートフォルダーのチェックを適用してください。
ディスク上のファイルが変更されたときに、ファイル一覧を自動で更新するにはどうすればよいですか?
メインプロセスで fs.watch を使って一覧表示中のフォルダーを監視し、mainWindow.webContents.send でページに通知を送ります。プリロードでは 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