【Node.js】fsモジュールでのファイル操作方法まとめ

fsモジュールでよく使用される各操作をまとめたTips。
本サービスでも活用しているため、頻出のものをリファレンス用にまとめました。
本記事はNode.js v18以降、ES Moduleを対象。

事前知識

モジュールimport

同期・非同期どちらも使う場合は下記のように書く。

import fs from 'node:fs'

※node:なんとかといった指定方法についてはここがわかりやすい。

__dirname/__filenameが使えない

CommonJsで定番だった__dirnameと__filenameはES Moduleでは用意されていない。
代わりに下記を使用。

// __dirname 実行ファイルが含まれるディレクトリのフルパス取得
import.meta.dirname

// __filename 実行ファイルのフルパス取得
import.meta.filename

オプションの指定方法（省略可能）

読み取りと書き込みでは実行関数の引数としてオプションを指定できる。
大まかに分けると、エンコーディングを文字列で指定する方法と、複数のオプションをオブジェクトで指定する方法とで2種類あるので、使用例として読み込みでは文字列で指定、書き込みではオブジェクトで指定する形で後述。

ちなみにエンコーディングはオブジェクトでも指定できるので、よく定義ファイルへジャンプする方はオブジェクトにしておく方がいいかもしれない。

本記事ではオプションの中から特に使用頻度の高いencodingとflagを紹介。
それぞれに指定できる値もかなり抜粋したので、もっと知りたい方は公式へGO。

encoding	使いどころ
utf-8	下記以外のファイルはだいたいこれ
binary	主に画像・動画などのメディアファイル 他にはExcelなどの特定のソフトでのみ使うファイルとかも多分これ
base64	Base64形式で扱いたいファイル

flag	どっちで使いがち？	挙動
r	読み取り	指定ファイルがない場合はエラー（読み取りのデフォルト）
w	書き込み	書き込み先に同一名のファイルがない場合は新規作成 ある場合は上書き
wx	書き込み	書き込み先に同一名のファイルがない場合は新規作成 ある場合はエラー
a	書き込み	書き込み先に同一名のファイルがない場合は新規作成 ある場合そのファイルの末尾に追記

読み取り

オプションは第2引数で指定。

readFile（非同期）

コールバック関数が引数になるので、その中で例外処理などを行う。
オプションを省略する場合はコールバック関数が第2引数になる。

処理が成功した場合はdata: ファイルの内容,error: nullとなり、
失敗した場合はdata: undefined, error: エラーの内容とそれぞれ値が入る。

fs.readFile('./読み取りファイル名.txt', 'utf-8', (error, data) => {
  if (error) {
    // 失敗した場合
    return
  }
  // 成功した場合
})

readFileSync（同期）

非同期とは異なりシンプルな書き方ができるが、例外処理が必須であれば実際にはtry ~ catchとセットで使うことになる。

try {
  const data = fs.readFileSync('./読み取りファイル名.txt', 'utf-8')
  // 成功した場合
} catch (error) {
  // 失敗した場合
}

書き込み

前述の通りオプションはオブジェクトで指定。
指定位置は第2引数。

{
  encoding: 'utf-8',
  flag: 'w'
}

書き込む内容は文字列かバイナリを渡せばOK。

writeFile（非同期）

書き方はreadFileとほぼ同じで、違いとしてはコールバック関数の引数にdataが不要ということぐらい。
オプションを省略する場合はコールバック関数が第3引数になる。

fs.writeFile('./書き込みファイル名.txt', 書き込む内容, { encoding: 'utf-8', flag: 'w' }, error => {
  if (error) {
    // 失敗した場合
    return
  }
  // 成功した場合
})

writeFileSync（同期）

こちらもreadFileSyncと同様。

try {
  fs.writeFileSync('./書き込みファイル名.txt', 書き込む内容, { encoding: 'utf-8', flag: 'w' })
  // 成功した場合
} catch (error) {
  // 失敗した場合
}

コピー

読み取り・書き込みでflagオプションを前述したが、コピーでも同じような指定ができる。
ただし指定方法が少し異なり、wやrではなく数値での指定となり、デフォルトは0となっている。
別の値を指定する場合はマジックナンバー化防止のため、fsで定義された定数を使うのが👍。
指定位置は第2引数。

0（未指定の場合）	コピー先に同一名のファイルがある場合、上書き
import fs from ‘node:fs’ fs.constants.COPYFILE_EXCL	コピー先に同一名のファイルがある場合、コピー操作は失敗

他の指定値：公式

copyFile（非同期）

オプションを省略する場合はコールバック関数が第3引数になる。

fs.copyFile('./コピー元ファイル名.txt', './コピー先ファイル名.txt', fs.constants.COPYFILE_EXCL, error => {
  if (error) {
    // 失敗した場合
    return
  }
  // 成功した場合
})

copyFileSync（同期）

try {
  fs.copyFileSync('./コピー元ファイル名.txt', './コピー先ファイル名.txt', fs.constants.COPYFILE_EXCL)
  // 成功した場合
} catch (error) {
  // 失敗した場合
}

削除

unlink（非同期）

fs.unlink('./削除ファイル名.txt', error => {
  if (error) {
    // 失敗した場合
    return
  }
  // 成功した場合
})

unlinkSync（同期）

try {
  fs.unlinkSync('./削除ファイル名.txt')
  // 成功した場合
} catch (error) {
  // 失敗した場合
}