Node.jsにおいて、ローカルファイルへの書き込みはサーバーサイド開発の基本となる操作の一つです。
システムログの保存、ユーザー設定の書き出し、あるいは大量のデータのエクスポートなど、その用途は非常に多岐にわたります。
2026年現在のNode.js環境では、非同期処理をベースとしたAPIが標準となっており、アプリケーションのパフォーマンスを最大限に引き出す手法が確立されています。
特に、小規模なデータに適したfs.promisesと、大規模なデータ処理に必須となるStreamの使い分けを理解することは非常に重要です。
本記事では、現代的なNode.js開発におけるファイル書き込みの最適解を整理して解説します。
Node.jsにおけるファイル書き込みの基本手法
Node.jsでファイルを操作する場合、標準モジュールであるfs(File System)を使用します。
かつてはコールバック形式のメソッドが主流でしたが、現在はPromiseベースのAPIを利用することが推奨されています。
同期処理と非同期処理の選択
Node.jsのファイル操作には、同期(Sync)版と非同期版の2種類が存在します。
同期版のメソッドは実行が完了するまでメインスレッドをブロックするため、サーバーアプリケーションでの利用は避けるべきです。
一方で、スクリプトの初期化処理など、パフォーマンスが最優先されない場面ではコードが簡潔になるメリットもあります。
しかし、現代のWebアプリケーション開発においては、イベントループを止めない非同期処理の採用が不可欠です。
fsモジュールのインポート方法
最新のNode.js環境では、ES Modules(ESM)形式での記述が一般的です。
fs/promisesを直接インポートすることで、async/await構文をスムーズに利用できます。
// ES Modulesにおけるインポート例
import { writeFile, appendFile } from 'node:fs/promises';
import { Buffer } from 'node:buffer';fs.promisesを使用したモダンな書き込み
fs.promisesは、Promiseを返すように設計されたAPI群です。
async/awaitと組み合わせることで、同期処理のような直感的な記述で非同期処理を実装できます。
writeFileによるファイルの新規作成と上書き
もっとも頻繁に利用されるのがwriteFileメソッドです。
このメソッドは、指定したパスにファイルが存在しない場合は新規作成し、既に存在する場合は内容をすべて上書きします。
import { writeFile } from 'node:fs/promises';
async function writeExample() {
try {
const data = 'こんにちは、Node.jsの世界へ。';
// ファイル名、データ、オプションの順に指定
await writeFile('example.txt', data, 'utf8');
console.log('ファイルの書き込みが完了しました。');
} catch (err) {
console.error('エラーが発生しました:', err.message);
}
}
writeExample();ファイルの書き込みが完了しました。appendFileによるデータの追記
既存のファイルの内容を残したまま、末尾にデータを追加したい場合にはappendFileを使用します。
ログファイルの更新など、逐次データを蓄積していく用途に最適です。
import { appendFile } from 'node:fs/promises';
async function appendExample() {
const logMessage = `ログ記録時間: ${new Date().toISOString()}\n`;
await appendFile('server.log', logMessage);
}
appendExample();writeFileやappendFileは、データを一度メモリ上に展開してから書き込むため、ファイルサイズが小さい場合に適しています。
大容量データを扱うためのStream（ストリーム）
数百MBや数GBを超える巨大なファイルを扱う場合、fs.promisesではメモリ不足(Out of Memory)を引き起こすリスクがあります。
このようなケースでは、データを細切れにして少しずつ処理するStreamを利用します。
createWriteStreamによるストリーム生成
fs.createWriteStreamを使用すると、書き込み専用のストリームを作成できます。
これにより、巨大なバッファを確保することなく、データの断片を連続して書き込むことが可能になります。
import { createWriteStream } from 'node:fs';
const writer = createWriteStream('large_data.txt');
// データを分割して書き込み
writer.write('最初のデータブロック\n');
writer.write('次のデータブロック\n');
// 書き込み終了を宣言
writer.end('最後のデータブロックで終了');
writer.on('finish', () => {
console.log('すべての書き込みが正常に完了しました。');
});
writer.on('error', (err) => {
console.error('書き込み中にエラーが発生しました:', err);
});バックプレッシャ（Backpressure）の制御
ストリームを利用する際、書き込み速度がデータの供給速度に追いつかなくなる現象が発生することがあります。
これを「バックプレッシャ」と呼び、メモリの肥大化を防ぐために適切に制御する必要があります。
writer.write()がfalseを返した場合、一度書き込みを停止し、drainイベントが発生するのを待機するのが正しい実装です。
しかし、2026年現在の開発では、より高度な抽象化であるpipelineメソッドを使用することが一般的です。
fs.promisesとStreamの使い分け基準
開発者は、扱うデータの性質に応じて最適な手法を選択する必要があります。
以下の表は、各手法の特徴と推奨される利用シーンをまとめたものです。
| 手法 | 適したファイルサイズ | 主なメリット | デメリット |
|---|---|---|---|
| fs.promises (writeFile) | 数KB 〜 数MB程度 | コードが非常に簡潔で読みやすい | 巨大なファイルではメモリを大量消費する |
| fs.createWriteStream | 100MB以上、または不明 | メモリ使用量が一定で安定している | イベントハンドリングなど記述が複雑 |
| fs.writeFileSync | 極小 (設定ファイル等) | 非同期処理を意識せず実装できる | 実行中に他の処理を止めてしまう |
基本的には「迷ったら fs.promises 、パフォーマンスが懸念されるなら Stream」という方針で問題ありません。
ファイル書き込み時のエラーハンドリングと注意点
ファイルシステムへのアクセスは、権限不足やディスク容量不足など、多くの実行時エラーの可能性があります。
堅牢なアプリケーションを構築するためには、エラー処理を疎かにしてはいけません。
try-catchによる例外捕捉
fs.promisesを使用する場合、必ずtry-catchブロックで囲むようにしてください。
特にディレクトリが存在しないパスを指定した場合、実行時に例外がスローされます。
try {
await writeFile('./invalid_dir/test.txt', 'data');
} catch (error) {
if (error.code === 'ENOENT') {
console.error('指定されたディレクトリが見つかりません。');
} else {
console.error('予期しないエラー:', error);
}
}ディレクトリの自動生成
ファイルを書き込む前に、保存先のディレクトリが存在するか確認し、存在しない場合は作成する必要があります。
mkdirメソッドのrecursive: trueオプションを使用すると、深い階層のディレクトリも一括で作成でき、非常に便利です。
import { mkdir, writeFile } from 'node:fs/promises';
import { dirname } from 'node:path';
async function safeWrite(path, data) {
// 書き込み先ディレクトリのパスを取得
const dir = dirname(path);
// ディレクトリを再帰的に作成
await mkdir(dir, { recursive: true });
// ファイルを書き込み
await writeFile(path, data);
}最新のNode.js環境におけるベストプラクティス
2026年のNode.js開発では、より安全で効率的な書き込み手法が重視されています。
一つのポイントは、一時ファイルを使用したアトミックな書き込みです。
書き込み途中でクラッシュした場合にファイルが破損するのを防ぐため、一度別名で保存し、完了後にrenameする手法が推奨されます。
また、データの整合性を担保するために、書き込み後にfsyncを実行して物理ディスクへの同期を強制するケースもあります。
さらに、AbortSignalを利用することで、タイムアウトやユーザー操作による処理のキャンセルをエレガントに実装できるようになりました。
const controller = new AbortController();
const { signal } = controller;
// 100ms以内に完了しない場合はキャンセル
setTimeout(() => controller.abort(), 100);
try {
await writeFile('timeout_test.txt', '大量のデータ...', { signal });
} catch (err) {
if (err.name === 'AbortError') {
console.error('書き込みがタイムアウトしました。');
}
}まとめ
Node.jsでのファイル書き込みは、APIの進化により非常に直感的かつ強力なものとなりました。
日常的な開発では、可読性に優れたfs.promisesを活用し、簡潔なコードを維持することが望ましいでしょう。
一方で、大量のデータを扱うバッチ処理や高トラフィックな環境では、Streamを適切に制御することでシステムの安定性を確保できます。
それぞれの特性を正しく理解し、用途に応じた最適なメソッドを選択することが、プロフェッショナルなNode.jsエンジニアへの第一歩です。
本記事で紹介したエラーハンドリングや最新のオプションを活用し、安全で効率的なファイル操作を実装してください。