Node.js の fs.readFile、ストリーム、FileHandle でファイルを読む
小さなファイルの内容全体が必要な場合は、readFile() を
node:fs/promises から利用します。大きなファイルは、ストリームのチャンクを順に処理します。以下の例では、同じ入力をテキストとして読み込み、バイト数を数え、先頭の十バイトを調べます。ファイルの内容は変更しません。
サンプルファイルの準備
これらの例は macOS 上の Node.js v26.8.2 でテストしています。準備には Bash を使用し、パッケージのインストールは不要です。JavaScript の例は、示されている .mjs のファイル名で保存してください。これにより、CommonJS プロジェクト内でも Node.js が
ES モジュールとして読み込みます。
デモを作成するディレクトリで、次を実行してください。
mkdir node-read-demo &&
cd node-read-demo &&
printf 'Hello, 🌍!\n' > example.txt
この準備処理は、既存の node-read-demo ディレクトリがある場合には実行を拒否します。mkdir または cd が失敗すると、&& の連鎖は example.txt を書き込む前に停止します。失敗した場合は作業を止め、新しい場所を選んでください。成功したら、node-read-demo にとどまり、各スクリプトをそこに保存してください。スクリプトは結果をターミナルに表示するだけなので、再実行しても入力は変わりません。
小さな UTF-8 ファイルの読み込み
次を read-text.mjs として保存してください。
import { readFile } from 'node:fs/promises'
async function main() {
const path = process.argv[2] ?? 'example.txt'
const text = await readFile(path, 'utf8')
process.stdout.write(text)
}
main().catch((error) => {
console.error(`Read failed: ${error.code ?? 'UNKNOWN'}`)
process.exitCode = 1
})
デモのディレクトリから実行してください。
node read-text.mjs example.txt
ファイルに保存されているとおりに、Hello, 🌍! に続いて改行が出力されます。省略可能な引数のデフォルト値は example.txt です。相対入力パスは、スクリプトのディレクトリではなく、ターミナルの現在の作業ディレクトリを基準に解決されます。
'utf8' 引数を指定すると、readFile() は文字列を返します。画像やアーカイブなど、元のバイト列を格納した Buffer が必要な場合は、この引数を省略してください。UTF-8 デコードはテキスト用であり、任意のバイナリデータ用ではありません。
大きなファイルを蓄積せずに処理
readFile() は非同期ですが、結果全体をメモリに読み込みます。同時読み込みも含めて、アプリケーションのメモリ予算に収まる場合に使用してください。上限のないファイルリストに Promise.all() を使うと、多数の完全な結果を同時に保持することがあります。
ストリームなら、チャンクを処理してから破棄できます。実際に読み込んだバイト数を数えるには、次を count-bytes.mjs として保存してください。
import { createReadStream } from 'node:fs'
async function main() {
const path = process.argv[2] ?? 'example.txt'
let total = 0
for await (const chunk of createReadStream(path)) {
total += chunk.length
}
console.log(`Read ${total} bytes.`)
}
main().catch((error) => {
console.error(`Read failed: ${error.code ?? 'UNKNOWN'}`)
process.exitCode = 1
})
node count-bytes.mjs example.txt
実行すると Read 13 bytes. と表示されます。地球の文字は UTF-8 で四バイトを占めるため、文字数を数えると結果は異なります。ストリームにはエンコーディングを設定していないので、各チャンクは生のバイト列の
Buffer です。空のファイルでは Read 0 bytes. と表示されます。
for await...of ループはストリームを消費し、読み込みの失敗を catch に伝播します。ファイルストリームは、デフォルトで完了時またはエラー時にファイル記述子を閉じます。この例では、すべてのチャンクではなくカウンターを保持します。すべてのチャンクを配列や文字列に追加すると、このメモリ上の利点は失われます。
ループを逐次処理に応用するには、その内部で処理を行い、非同期処理は
await してから次に進んでください。チャンクが完全な行、JSON オブジェクト、CSV レコードになっているとは限りません。こうしたレコードが必要な場合は、境界を扱えるパーサーを使用してください。ファイルが報告するサイズだけが必要なら、stat() を使うと、内容をまったく読み込まずに済みます。
先頭の十バイトだけを読み込む
バイナリヘッダーを調べるには、FileHandle を開き、長さを限定して先頭部分を読み込みます。次を read-prefix.mjs として保存してください。
import { open } from 'node:fs/promises'
async function main() {
const path = process.argv[2] ?? 'example.txt'
const handle = await open(path, 'r')
try {
const buffer = Buffer.alloc(10)
let total = 0
while (total < buffer.length) {
const { bytesRead } = await handle.read(buffer, total, buffer.length - total, total)
if (bytesRead === 0) break
total += bytesRead
}
console.log(`Read ${total} bytes: ${buffer.subarray(0, total).toString('hex')}`)
} finally {
await handle.close()
}
}
main().catch((error) => {
console.error(`Read failed: ${error.code ?? 'UNKNOWN'}`)
process.exitCode = 1
})
node read-prefix.mjs example.txt
実行すると Read 10 bytes: 48656c6c6f2c20f09f8c と表示されます。handle.read() の最後の引数はファイル内の位置で、ここではゼロから進みます。読み込みで返されるバイト数は要求より少ない場合があるため、十バイトが埋まるか、EOF(bytesRead === 0)に達するまでループを続けます。finally は、読み込みに失敗してもハンドルを閉じます。
subarray() は、出力を実際に読み込んだバイトに限定し、短いファイルや空のファイルで使われなかった領域を除外します。また、十六進数で出力することで、不完全な UTF-8 文字のデコードを避けます。この十バイトの先頭部分は、地球の文字の途中で終わっています。
読み込み失敗の診断
存在しないファイル名を試してください。
node read-text.mjs missing.txt
標準エラー出力に Read failed: ENOENT と表示され、ステータス 1 で終了します。三つのスクリプトはいずれも、この方法で読み込みの失敗を報告します。process.exitCode を設定すると、保留中の出力を完了させながら失敗を示せます。
ENOENT の場合は、入力パスと作業ディレクトリを確認してください。EACCES は権限の問題を示します。プロセスが親ディレクトリをたどり、ファイルを読み込めることを確認してください。先に access() で確認するのではなく、直接読み込みを試みてください。Node.js のドキュメントには、確認とオープンの間の競合について記載があります。
既存コードに合わせた API の選択
fs.readFile() のコールバック形式も、引き続きサポートされています。コールバックベースのコードでは、データを使う前に最初の error 引数を調べてください。読み込みのためだけに、周囲のコードを Promise に変換する必要はありません。
fs.readFileSync() は、完了するまで JavaScript の実行をブロックします。短いコマンドラインスクリプトや、起動時の設定読み込みには適している場合があります。ディスク I/O の待機中も他のクライアントに応答する必要があるリクエストハンドラーでは、ブロッキング読み込みを使わないでください。
