ファイルシステム

[Stable: 2 - 安定版]

Stable: 2 安定版: 2 - 安定版

ソースコード: lib/fs.js

node:fs モジュールは、標準の POSIX 関数をモデルとした方法でファイルシステムと対話することを可能にします。

Promise ベースの API を使用するには：

ESM

import * as fs from 'node:fs/promises'

CJS

const fs = require('node:fs/promises')

コールバックと同期 API を使用するには：

ESM

import * as fs from 'node:fs'

CJS

const fs = require('node:fs')

すべてのファイルシステム操作には、同期、コールバック、および Promise ベースの形式があり、CommonJS 構文と ES6 モジュール (ESM) の両方を使用してアクセスできます。

Promise の例

Promise ベースの操作は、非同期操作が完了したときに解決される Promise を返します。

ESM

import { unlink } from 'node:fs/promises'

try {
  await unlink('/tmp/hello')
  console.log('successfully deleted /tmp/hello')
} catch (error) {
  console.error('there was an error:', error.message)
}

CJS

const { unlink } = require('node:fs/promises')

;(async function (path) {
  try {
    await unlink(path)
    console.log(`successfully deleted ${path}`)
  } catch (error) {
    console.error('there was an error:', error.message)
  }
})('/tmp/hello')

コールバックの例

コールバック形式は、最後の引数として完了コールバック関数を取り、非同期的に操作を呼び出します。完了コールバックに渡される引数はメソッドによって異なりますが、最初の引数は常に例外用に予約されています。操作が正常に完了した場合、最初の引数は null または undefined になります。

ESM

import { unlink } from 'node:fs'

unlink('/tmp/hello', err => {
  if (err) throw err
  console.log('successfully deleted /tmp/hello')
})

CJS

const { unlink } = require('node:fs')

unlink('/tmp/hello', err => {
  if (err) throw err
  console.log('successfully deleted /tmp/hello')
})

node:fs モジュール API のコールバックベースのバージョンは、実行時間とメモリ割り当ての両方の点で最大のパフォーマンスが必要な場合に、Promise API の使用よりも優先されます。

同期的な例

同期的な API は、操作が完了するまで Node.js のイベントループとそれ以降の JavaScript の実行をブロックします。例外は即座にスローされ、try...catch を使用して処理するか、バブルアップさせることができます。

ESM

import { unlinkSync } from 'node:fs'

try {
  unlinkSync('/tmp/hello')
  console.log('successfully deleted /tmp/hello')
} catch (err) {
  // エラーを処理する
}

CJS

const { unlinkSync } = require('node:fs')

try {
  unlinkSync('/tmp/hello')
  console.log('successfully deleted /tmp/hello')
} catch (err) {
  // エラーを処理する
}

Promises API

[履歴]

バージョン	変更点
v14.0.0	require('fs/promises') として公開されました。
v11.14.0, v10.17.0	この API は実験的ではなくなりました。
v10.1.0	この API は require('fs').promises でのみアクセス可能です。
v10.0.0	v10.0.0 で追加されました。

fs/promises API は、Promise を返す非同期ファイルシステムメソッドを提供します。

Promise API は、基盤となる Node.js スレッドプールを使用して、イベントループスレッドの外でファイルシステム操作を実行します。これらの操作は同期化されておらず、スレッドセーフでもありません。同じファイルに対して複数の同時変更を行う場合は注意が必要です。そうしないと、データが破損する可能性があります。

クラス: FileHandle

追加: v10.0.0

<FileHandle> オブジェクトは、数値ファイル記述子のオブジェクトラッパーです。

<FileHandle> オブジェクトのインスタンスは、fsPromises.open() メソッドによって作成されます。

すべての<FileHandle> オブジェクトは、<EventEmitter>です。

filehandle.close() メソッドを使用して <FileHandle> が閉じられない場合、ファイル記述子を自動的に閉じようとし、メモリリークを防ぐためにプロセスの警告を発生させます。これは信頼できない可能性があり、ファイルが閉じられない場合もあるため、この動作に依存しないでください。代わりに、常に明示的に<FileHandle>を閉じてください。Node.js は将来この動作を変更する可能性があります。

イベント: 'close'

追加: v15.4.0

'close' イベントは、<FileHandle> が閉じられ、もはや使用できなくなったときに発生します。

filehandle.appendFile(data[, options])

[履歴]

バージョン	変更点
v21.1.0, v20.10.0	flush オプションがサポートされるようになりました。
v15.14.0, v14.18.0	data 引数が AsyncIterable、Iterable、および Stream をサポートするようになりました。
v14.0.0	data パラメーターは、サポートされていない入力を文字列に強制変換しなくなりました。
v10.0.0	追加: v10.0.0

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> デフォルト: 'utf8'
  • flush <boolean> true の場合、基になるファイル記述子が閉じられる前にフラッシュされます。 デフォルト: false。

• 戻り値: <Promise> 成功時に undefined で解決されます。

filehandle.writeFile() のエイリアスです。

ファイルハンドルを操作する場合、モードは fsPromises.open() で設定されたものから変更できません。したがって、これは filehandle.writeFile() と同等です。

filehandle.chmod(mode)

Added in: v10.0.0

• mode <integer> ファイルモードのビットマスク。
• 戻り値: <Promise> 成功時に undefined で解決します。

ファイルの権限を変更します。chmod(2)を参照してください。

filehandle.chown(uid, gid)

Added in: v10.0.0

• uid <integer> ファイルの新しい所有者のユーザー ID。
• gid <integer> ファイルの新しいグループのグループ ID。
• 戻り値: <Promise> 成功時に undefined で解決します。

ファイルの所有権を変更します。chown(2)のラッパーです。

filehandle.close()

Added in: v10.0.0

• 戻り値: <Promise> 成功時に undefined で解決します。

ハンドルでの保留中の操作が完了するのを待ってから、ファイルハンドルを閉じます。

import { open } from 'node:fs/promises'

let filehandle
try {
  filehandle = await open('thefile.txt', 'r')
} finally {
  await filehandle?.close()
}

filehandle.createReadStream([options])

Added in: v16.11.0

• options <Object>

  • encoding <string> デフォルト: null
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • end <integer> デフォルト: Infinity
  • highWaterMark <integer> デフォルト: 64 * 1024
  • signal <AbortSignal> | <undefined> デフォルト: undefined

• 戻り値: <fs.ReadStream>

options には、ファイル全体ではなく、ファイルのバイト範囲を読み込むための start および end の値を含めることができます。 start と end は両方とも包括的で、0 から数え始め、許可される値は [0, Number.MAX_SAFE_INTEGER] の範囲です。start が省略または undefined の場合、filehandle.createReadStream() は現在のファイル位置から順番に読み取ります。encoding は、<Buffer> で受け入れられるいずれかのエンコーディングを使用できます。

FileHandle が、キーボードやサウンドカードなど、ブロッキング読み取りのみをサポートするキャラクタデバイスを指している場合、読み取り操作はデータが利用可能になるまで完了しません。これにより、プロセスが終了したり、ストリームが自然に閉じたりするのを妨げる可能性があります。

デフォルトでは、ストリームは破棄された後に 'close' イベントを発行します。この動作を変更するには、emitClose オプションを false に設定します。

import { open } from 'node:fs/promises'

const fd = await open('/dev/input/event0')
// いくつかのキャラクタデバイスからストリームを作成します。
const stream = fd.createReadStream()
setTimeout(() => {
  stream.close() // これでストリームが閉じられない可能性があります。
  // 基になるリソースがファイル終端を自身で示したかのように、
  // 人為的にストリームの終端をマークすることで、ストリームを閉じることができます。
  // これは保留中の読み取り操作をキャンセルするものではなく、そのような操作がある場合、
  // プロセスはそれが完了するまで正常に終了できない可能性があります。
  stream.push(null)
  stream.read(0)
}, 100)

autoClose が false の場合、エラーが発生した場合でも、ファイル記述子は閉じられません。ファイル記述子のリークがないことを確認し、閉じるのはアプリケーションの責任です。 autoClose が true (デフォルトの動作) に設定されている場合、'error' または 'end' でファイル記述子は自動的に閉じられます。

100 バイトのファイルの最後の 10 バイトを読み取る例:

import { open } from 'node:fs/promises'

const fd = await open('sample.txt')
fd.createReadStream({ start: 90, end: 99 })

filehandle.createWriteStream([options])

[履歴]

バージョン	変更点
v21.0.0, v20.10.0	flushオプションがサポートされるようになりました。
v16.11.0	v16.11.0 で追加

• options <Object>

  • encoding <string> デフォルト: 'utf8'
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • highWaterMark <number> デフォルト: 16384
  • flush <boolean> trueの場合、基になるファイル記述子は閉じられる前にフラッシュされます。 デフォルト: false。

• 戻り値: <fs.WriteStream>

optionsには、ファイルの先頭以降の特定の場所にデータを書き込むためのstartオプションを含めることもできます。許可される値は[0, Number.MAX_SAFE_INTEGER]の範囲内です。ファイルを置き換えるのではなく変更するには、デフォルトのrではなくflags openオプションをr+に設定する必要がある場合があります。encodingは、<Buffer>で受け入れられるもののいずれかです。

autoCloseが true（デフォルトの動作）に設定されている場合、'error'または'finish'でファイル記述子が自動的に閉じられます。autoCloseが false の場合、エラーが発生した場合でもファイル記述子は閉じられません。ファイル記述子のリークがないことを確認し、閉じるのはアプリケーションの責任です。

デフォルトでは、ストリームは破棄された後、'close'イベントを発行します。この動作を変更するには、emitCloseオプションをfalseに設定します。

filehandle.datasync()

追加: v10.0.0

• 返り値: <Promise> 成功時に undefined で履行されます。

ファイルに関連付けられている現在キューに入れられているすべての I/O 操作を、オペレーティング システムの同期 I/O 完了状態に強制的に移します。詳細については、POSIX fdatasync(2) ドキュメントを参照してください。

filehandle.sync とは異なり、このメソッドは変更されたメタデータをフラッシュしません。

filehandle.fd

追加: v10.0.0

• <number> <FileHandle> オブジェクトによって管理される数値ファイル記述子。

filehandle.read(buffer, offset, length, position)

[履歴]

バージョン	変更
v21.0.0	position に bigint 値を受け入れるようになりました。
v10.0.0	追加: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView> 読み取られたファイルデータで埋められるバッファー。
• offset <integer> バッファーのどこから埋め始めるかを示す位置。デフォルト: 0
• length <integer> 読み取るバイト数。デフォルト: buffer.byteLength - offset
• position <integer> | <bigint> | <null> ファイルからデータの読み取りを開始する場所。null または -1 の場合、データは現在のファイル位置から読み取られ、位置が更新されます。position が非負の整数の場合、現在のファイル位置は変更されません。デフォルト: null
• 返り値: <Promise> 成功時に次の 2 つのプロパティを持つオブジェクトで履行されます。
  • bytesRead <integer> 読み取られたバイト数
  • buffer <Buffer> | <TypedArray> | <DataView> 渡された buffer 引数への参照。

ファイルからデータを読み取り、指定されたバッファーに格納します。

ファイルが同時に変更されていない場合、読み取られたバイト数が 0 になるとファイルの終わりに到達します。

filehandle.read([options])

[履歴]

バージョン	変更点
v21.0.0	position として bigint 値を受け入れる。
v13.11.0, v12.17.0	追加: v13.11.0, v12.17.0

• options <Object>

  • buffer <Buffer> | <TypedArray> | <DataView> 読み込まれたファイルデータで満たされるバッファー。デフォルト: Buffer.alloc(16384)
  • offset <integer> バッファーへの書き込みを開始する位置。デフォルト: 0
  • length <integer> 読み込むバイト数。デフォルト: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> ファイルからデータの読み取りを開始する場所。null または -1 の場合、データは現在のファイル位置から読み取られ、位置が更新されます。position が非負の整数の場合、現在のファイル位置は変更されません。デフォルト: null

• 戻り値: <Promise> 成功時に、2 つのプロパティを持つオブジェクトで解決します。

  • bytesRead <integer> 読み込まれたバイト数
  • buffer <Buffer> | <TypedArray> | <DataView> 渡された buffer 引数への参照。

ファイルからデータを読み取り、それを指定されたバッファーに格納します。

ファイルが同時に変更されない場合、読み込まれたバイト数がゼロになったときにファイルの終わりに達します。

filehandle.read(buffer[, options])

[履歴]

バージョン	変更点
v21.0.0	position として bigint 値を受け入れるようになりました。
v18.2.0, v16.17.0	追加: v18.2.0, v16.17.0

• buffer <Buffer> | <TypedArray> | <DataView> 読み込まれたファイルデータで埋められるバッファー。
• options <Object>
  • offset <integer> バッファーへの書き込みを開始する位置。 デフォルト: 0
  • length <integer> 読み込むバイト数。 デフォルト: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> ファイルからデータを読み込み始める位置。 null または -1 の場合、データは現在のファイル位置から読み込まれ、位置が更新されます。 position が非負の整数の場合、現在のファイル位置は変更されません。 デフォルト:: null
• 戻り値: <Promise> 成功時に次の 2 つのプロパティを持つオブジェクトで解決されます:
  • bytesRead <integer> 読み込まれたバイト数
  • buffer <Buffer> | <TypedArray> | <DataView> 渡された buffer 引数への参照。

ファイルからデータを読み込み、指定されたバッファーに格納します。

ファイルが同時に変更されない場合、読み込まれたバイト数がゼロになったときにファイルの終わりに達します。

filehandle.readableWebStream([options])

[履歴]

バージョン	変更点
v20.0.0, v18.17.0	'bytes'ストリームを作成するオプションが追加されました。
v17.0.0	v17.0.0 で追加されました。

[安定版: 1 - 試験的]

安定版: 1 安定版: 1 - 試験的

• options <Object>

  • type <string> | <undefined> 通常のストリームまたは'bytes'ストリームを開くかどうか。デフォルト: undefined

• 戻り値: <ReadableStream>

ファイルのデータを読み取るために使用できる ReadableStream を返します。

このメソッドが複数回呼び出された場合、または FileHandle が閉じられた後、または閉じている間に呼び出された場合は、エラーがスローされます。

ESM

import { open } from 'node:fs/promises'

const file = await open('./some/file/to/read')

for await (const chunk of file.readableWebStream()) console.log(chunk)

await file.close()

CJS

const { open } = require('node:fs/promises')

;(async () => {
  const file = await open('./some/file/to/read')

  for await (const chunk of file.readableWebStream()) console.log(chunk)

  await file.close()
})()

ReadableStream はファイルを最後まで読み取りますが、FileHandle を自動的に閉じることはありません。ユーザーコードは fileHandle.close() メソッドを呼び出す必要があります。

filehandle.readFile(options)

追加: v10.0.0

• options <Object> | <string>

  • encoding <string> | <null> デフォルト: null
  • signal <AbortSignal> 進行中の readFile を中止できます。

• 戻り値: <Promise> ファイルの内容を正常に読み込んだときに完了します。エンコーディングが指定されていない場合 (options.encoding を使用)、データは<Buffer>オブジェクトとして返されます。それ以外の場合、データは文字列になります。

ファイルのすべての内容を非同期的に読み取ります。

options が文字列の場合、encoding を指定します。

<FileHandle> は読み取りをサポートする必要があります。

ファイルハンドルに対して 1 つ以上の filehandle.read() 呼び出しが行われた後、filehandle.readFile() 呼び出しが行われた場合、データはファイルの現在位置からファイルの最後まで読み取られます。常にファイルの先頭から読み取るわけではありません。

filehandle.readLines([options])

追加: v18.11.0

• options <Object>

  • encoding <string> デフォルト: null
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • end <integer> デフォルト: Infinity
  • highWaterMark <integer> デフォルト: 64 * 1024

• 戻り値: <readline.InterfaceConstructor>

readlineインターフェースを作成し、ファイル上にストリームするための便利なメソッドです。オプションについては、filehandle.createReadStream()を参照してください。

ESM

import { open } from 'node:fs/promises'

const file = await open('./some/file/to/read')

for await (const line of file.readLines()) {
  console.log(line)
}

CJS

const { open } = require('node:fs/promises')

;(async () => {
  const file = await open('./some/file/to/read')

  for await (const line of file.readLines()) {
    console.log(line)
  }
})()

filehandle.readv(buffers[, position])

追加: v13.13.0, v12.17.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> データの読み込みを開始するファイルの先頭からのオフセット。positionがnumberでない場合、データは現在の位置から読み込まれます。 デフォルト: null
• 戻り値: <Promise> 成功時に、以下の 2 つのプロパティを含むオブジェクトで履行されます。
  • bytesRead <integer> 読み込まれたバイト数
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> buffers入力への参照を含むプロパティ。

ファイルから読み込み、<ArrayBufferView>の配列に書き込みます。

filehandle.stat([options])

[History]

Version	Changes
v10.5.0	返される数値が bigint であるべきかどうかを指定するための追加の options オブジェクトを受け入れます。
v10.0.0	v10.0.0 で追加されました。

• options <Object>

  • bigint <boolean> 返される<fs.Stats> オブジェクトの数値が bigint であるべきかどうか。デフォルト: false。

• 戻り値: <Promise> ファイルの<fs.Stats>で解決します。

filehandle.sync()

追加: v10.0.0

• 戻り値: <Promise> 成功時に undefined で解決します。

オープンなファイル記述子のすべてのデータをストレージデバイスにフラッシュするように要求します。具体的な実装は、オペレーティングシステムおよびデバイスに固有です。詳細については、POSIX fsync(2) のドキュメントを参照してください。

filehandle.truncate(len)

追加: v10.0.0

• len <integer> デフォルト: 0
• 戻り値: <Promise> 成功時に undefined で解決します。

ファイルを切り詰めます。

ファイルが len バイトよりも大きい場合は、ファイルの最初の len バイトのみが保持されます。

次の例では、ファイルの最初の 4 バイトのみを保持しています。

import { open } from 'node:fs/promises'

let filehandle = null
try {
  filehandle = await open('temp.txt', 'r+')
  await filehandle.truncate(4)
} finally {
  await filehandle?.close()
}

ファイルが以前に len バイトよりも短かった場合は、拡張され、拡張された部分は null バイト ('\0') で埋められます。

len が負の場合は、0 が使用されます。

filehandle.utimes(atime, mtime)

追加: v10.0.0

• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 戻り値: <Promise>

<FileHandle>で参照されるオブジェクトのファイルシステムのタイムスタンプを変更し、成功時に引数なしで Promise を解決します。

filehandle.write(buffer, offset[, length[, position]])

[履歴]

バージョン	変更点
v14.0.0	buffer パラメーターは、サポートされていない入力を強制的にバッファーに変換しなくなりました。
v10.0.0	追加: v10.0.0

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> 書き込むデータの開始位置（buffer 内）。
• length <integer> 書き込むbufferからのバイト数。デフォルト: buffer.byteLength - offset
• position <integer> | <null> buffer からのデータを書き込むファイルの先頭からのオフセット。position が number でない場合、データは現在の位置に書き込まれます。詳細については、POSIX pwrite(2) のドキュメントを参照してください。 デフォルト: null
• 戻り値: <Promise>

buffer をファイルに書き込みます。

Promise は、次の 2 つのプロパティを含むオブジェクトで解決されます。

• bytesWritten <integer> 書き込まれたバイト数
• buffer <Buffer> | <TypedArray> | <DataView> 書き込まれた buffer への参照。

Promise が解決（または拒否）されるのを待たずに、同じファイルに対して filehandle.write() を複数回使用することは安全ではありません。このシナリオでは、filehandle.createWriteStream() を使用してください。

Linux では、ファイルが追加モードで開かれている場合、位置指定書き込みは機能しません。カーネルは position 引数を無視し、常にデータの末尾に追加します。

filehandle.write(buffer[, options])

追加: v18.3.0, v16.17.0

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> デフォルト: 0
  • length <integer> デフォルト: buffer.byteLength - offset
  • position <integer> デフォルト: null

• 戻り値: <Promise>

bufferをファイルに書き込みます。

上記の filehandle.write 関数と同様に、このバージョンではオプションの options オブジェクトを受け取ります。options オブジェクトが指定されていない場合は、上記のデフォルト値が使用されます。

filehandle.write(string[, position[, encoding]])

[履歴]

バージョン	変更
v14.0.0	string パラメーターはサポートされていない入力を文字列に強制変換しなくなりました。
v10.0.0	追加: v10.0.0

• string <string>
• position <integer> | <null> string からのデータを書き込むファイルの先頭からのオフセット。position が number ではない場合、データは現在の位置に書き込まれます。詳細については、POSIX の pwrite(2) ドキュメントを参照してください。 デフォルト: null
• encoding <string> 予想される文字列エンコーディング。 デフォルト: 'utf8'
• 戻り値: <Promise>

string をファイルに書き込みます。string が文字列でない場合、Promise はエラーで拒否されます。

Promise は、2 つのプロパティを含むオブジェクトで履行されます。

• bytesWritten <integer> 書き込まれたバイト数
• buffer <string> 書き込まれた string への参照。

Promise が履行 (または拒否) されるのを待たずに、同じファイルで filehandle.write() を複数回使用することは安全ではありません。このシナリオでは、filehandle.createWriteStream() を使用してください。

Linux では、ファイルが追加モードで開かれている場合、位置書き込みは機能しません。カーネルは position 引数を無視し、常にデータの最後にデータを追加します。

filehandle.writeFile(data, options)

[履歴]

バージョン	変更点
v15.14.0, v14.18.0	data 引数が AsyncIterable、Iterable、および Stream をサポートするようになりました。
v14.0.0	data パラメーターは、サポートされていない入力を文字列に強制変換しなくなりました。
v10.0.0	v10.0.0 で追加

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> data が文字列の場合に期待される文字エンコーディング。デフォルト: 'utf8'

• 戻り値: <Promise>

データをファイルに非同期的に書き込みます。ファイルがすでに存在する場合は置き換えられます。 data は、文字列、バッファー、<AsyncIterable>、または<Iterable> オブジェクトにすることができます。Promise は成功時に引数なしで履行されます。

options が文字列の場合、それは encoding を指定します。

<FileHandle> は書き込みをサポートする必要があります。

Promise が履行（または拒否）されるのを待たずに、同じファイルに対して filehandle.writeFile() を複数回使用することは安全ではありません。

ファイルハンドルに対して 1 回以上の filehandle.write() 呼び出しが行われた後に filehandle.writeFile() 呼び出しが行われた場合、データはファイルの現在位置からファイルの末尾まで書き込まれます。常にファイルの先頭から書き込むわけではありません。

filehandle.writev(buffers[, position])

追加: v12.9.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> buffers からのデータが書き込まれるファイルの先頭からのオフセット。position が number でない場合、データは現在の位置に書き込まれます。デフォルト: null
• 戻り値: <Promise>

<ArrayBufferView> の配列をファイルに書き込みます。

Promise は、以下の 2 つのプロパティを含むオブジェクトで解決されます。

• bytesWritten <integer> 書き込まれたバイト数
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> buffers 入力への参照。

Promise が fulfilled (または rejected) になるのを待たずに、同じファイルに対して writev() を複数回呼び出すのは安全ではありません。

Linux では、ファイルが追記モードで開かれている場合、位置指定書き込みは機能しません。カーネルは position 引数を無視し、常にデータの末尾に追記します。

filehandle[Symbol.asyncDispose]()

追加: v20.4.0, v18.18.0

[Stable: 1 - 実験的]

Stable: 1 安定度: 1 - 実験的

filehandle.close() のエイリアスです。

fsPromises.access(path[, mode])

Added in: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <integer> Default: fs.constants.F_OK
• Returns: <Promise> 成功時に undefined で解決します。

path で指定されたファイルまたはディレクトリに対するユーザーの権限をテストします。mode 引数は、実行されるアクセシビリティチェックを指定するオプションの整数です。mode は、値 fs.constants.F_OK、または fs.constants.R_OK、fs.constants.W_OK、および fs.constants.X_OK のビット単位の OR で構成されるマスクのいずれかである必要があります（例：fs.constants.W_OK | fs.constants.R_OK）。mode の可能な値については、ファイルアクセス定数 を確認してください。

アクセシビリティチェックが成功した場合、Promise は値なしで解決されます。アクセシビリティチェックのいずれかが失敗した場合、Promise は <Error> オブジェクトで拒否されます。次の例では、現在のプロセスがファイル /etc/passwd を読み書きできるかどうかを確認します。

import { access, constants } from 'node:fs/promises'

try {
  await access('/etc/passwd', constants.R_OK | constants.W_OK)
  console.log('can access')
} catch {
  console.error('cannot access')
}

fsPromises.open() を呼び出す前に、ファイルのアクセシビリティをチェックするために fsPromises.access() を使用することはお勧めしません。そうすると、他のプロセスが 2 つの呼び出しの間でファイルの状態を変更する可能性があるため、競合状態が発生します。代わりに、ユーザーコードはファイルを直接開く/読み取る/書き込む必要があり、ファイルにアクセスできない場合に発生したエラーを処理する必要があります。

fsPromises.appendFile(path, data[, options])

[履歴]

バージョン	変更点
v21.1.0, v20.10.0	flush オプションがサポートされるようになりました。
v10.0.0	Added in: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> ファイル名または <FileHandle>

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Default: 'utf8'
  • mode <integer> Default: 0o666
  • flag <string> ファイルシステムの flag のサポート を参照してください。 Default: 'a'。
  • flush <boolean> true の場合、基になるファイル記述子は閉じられる前にフラッシュされます。 Default: false。

• Returns: <Promise> 成功時に undefined で解決します。

ファイルが存在しない場合は作成し、ファイルに非同期的にデータを追加します。data は文字列または <Buffer> にすることができます。

options が文字列の場合、エンコーディングを指定します。

mode オプションは、新しく作成されたファイルにのみ影響します。詳細については、fs.open() を参照してください。

path は、追記用に開かれた（fsPromises.open() を使用）<FileHandle> として指定できます。

fsPromises.chmod(path, mode)

追加: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• 戻り値: <Promise> 成功時に undefined で履行します。

ファイルの権限を変更します。

fsPromises.chown(path, uid, gid)

追加: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• 戻り値: <Promise> 成功時に undefined で履行します。

ファイルの所有者を変更します。

fsPromises.copyFile(src, dest[, mode])

[履歴]

バージョン	変更点
v14.0.0	flags 引数を mode に変更し、より厳密な型検証を課しました。
v10.0.0	追加: v10.0.0

• src <string> | <Buffer> | <URL> コピー元のファイル名

• dest <string> | <Buffer> | <URL> コピー先のファイル名

• mode <integer> コピー操作の動作を指定するオプションの修飾子。2 つ以上の値のビット単位の OR で構成されるマスクを作成できます（例：fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE）。デフォルト: 0。

  • fs.constants.COPYFILE_EXCL: dest がすでに存在する場合、コピー操作は失敗します。
  • fs.constants.COPYFILE_FICLONE: コピー操作は、コピーオンライトのリファレンスリンクを作成しようとします。プラットフォームがコピーオンライトをサポートしていない場合は、フォールバックのコピーメカニズムが使用されます。
  • fs.constants.COPYFILE_FICLONE_FORCE: コピー操作は、コピーオンライトのリファレンスリンクを作成しようとします。プラットフォームがコピーオンライトをサポートしていない場合、操作は失敗します。

• 戻り値: <Promise> 成功時に undefined で履行します。

src を dest に非同期的にコピーします。 デフォルトでは、dest がすでに存在する場合は上書きされます。

コピー操作のアトミシティについては保証されません。 コピー先のファイルが書き込み用に開かれた後にエラーが発生した場合、コピー先を削除しようとします。

import { copyFile, constants } from 'node:fs/promises'

try {
  await copyFile('source.txt', 'destination.txt')
  console.log('source.txt was copied to destination.txt')
} catch {
  console.error('The file could not be copied')
}

// COPYFILE_EXCL を使用すると、destination.txt が存在する場合、操作は失敗します。
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL)
  console.log('source.txt was copied to destination.txt')
} catch {
  console.error('The file could not be copied')
}

fsPromises.cp(src, dest[, options])

[履歴]

バージョン	変更点
v22.3.0	この API は実験的ではなくなりました。
v20.1.0, v18.17.0	fs.copyFile() の mode 引数としてコピー動作を指定するための追加の mode オプションを受け入れるようになりました。
v17.6.0, v16.15.0	シンボリックリンクのパス解決を実行するかどうかを指定するための追加の verbatimSymlinks オプションを受け入れるようになりました。
v16.7.0	v16.7.0 で追加されました。

• src <string> | <URL> コピー元のパス。

• dest <string> | <URL> コピー先のパス。

• options <Object>

  • dereference <boolean> シンボリックリンクを解決します。デフォルト: false。

  • errorOnExist <boolean> force が false で、コピー先にファイルが存在する場合に、エラーをスローします。 デフォルト: false。

  • filter <Function> コピーするファイル/ディレクトリをフィルタリングするための関数。アイテムをコピーする場合は true を返し、無視する場合は false を返します。ディレクトリを無視すると、その内容もすべてスキップされます。true または false に解決する Promise を返すこともできます。 デフォルト: undefined。

  • src <string> コピー元のパス。

  • dest <string> コピー先のパス。

  • 戻り値: <boolean> | <Promise> boolean に強制変換可能な値、またはそのような値で満たされる Promise。

  • force <boolean> 既存のファイルまたはディレクトリを上書きします。これを false に設定すると、コピー先にファイルが存在する場合、コピー操作はエラーを無視します。この動作を変更するには、errorOnExist オプションを使用してください。デフォルト: true。

  • mode <integer> コピー操作の修飾子。 デフォルト: 0。fsPromises.copyFile() の mode フラグを参照してください。

  • preserveTimestamps <boolean> true の場合、src のタイムスタンプが保持されます。デフォルト: false。

  • recursive <boolean> ディレクトリを再帰的にコピーします デフォルト: false

  • verbatimSymlinks <boolean> true の場合、シンボリックリンクのパス解決はスキップされます。デフォルト: false

• 戻り値: <Promise> 成功時に undefined で解決します。

src から dest へ、サブディレクトリやファイルを含むディレクトリ構造全体を非同期的にコピーします。

あるディレクトリを別のディレクトリにコピーする場合、グロブはサポートされておらず、動作は cp dir1/ dir2/ と似ています。

fsPromises.glob(pattern[, options])

[History]

Version	Changes
v22.2.0	withFileTypes をオプションとしてサポート。
v22.0.0	v22.0.0 で追加。

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - 試験的

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> 現在の作業ディレクトリ。デフォルト: process.cwd()
  • exclude <Function> ファイル/ディレクトリを除外する関数。項目を除外する場合は true を、含める場合は false を返します。デフォルト: undefined。
  • withFileTypes <boolean> glob がパスを Dirent として返す場合は true、そうでない場合は false。デフォルト: false。

• Returns: <AsyncIterator> パターンに一致するファイルのパスを生成する AsyncIterator。

ESM

import { glob } from 'node:fs/promises'

for await (const entry of glob('**/*.js')) console.log(entry)

CJS

const { glob } = require('node:fs/promises')

;(async () => {
  for await (const entry of glob('**/*.js')) console.log(entry)
})()

fsPromises.lchmod(path, mode)

非推奨: v10.0.0 以降

• path <string> | <Buffer> | <URL>
• mode <integer>
• Returns: <Promise> 成功時に undefined で解決される Promise。

シンボリックリンクの権限を変更します。

このメソッドは macOS でのみ実装されています。

fsPromises.lchown(path, uid, gid)

[履歴]

バージョン	変更点
v10.6.0	この API は非推奨ではなくなりました。
v10.0.0	追加: v10.0.0

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• 戻り値: <Promise> 成功時に undefined で解決します。

シンボリックリンクの所有権を変更します。

fsPromises.lutimes(path, atime, mtime)

追加: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 戻り値: <Promise> 成功時に undefined で解決します。

パスがシンボリックリンクを参照している場合、リンクは間接参照されないという違いを除いて、fsPromises.utimes() と同様の方法でファイルのアクセス時間と修正時間を変更します。代わりに、シンボリックリンク自体のタイムスタンプが変更されます。

fsPromises.link(existingPath, newPath)

追加: v10.0.0

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 戻り値: <Promise> 成功した場合 undefined で解決されます。

existingPath から newPath への新しいリンクを作成します。詳細については、POSIX の link(2) ドキュメントを参照してください。

fsPromises.lstat(path[, options])

[履歴]

バージョン	変更点
v10.5.0	返される数値が bigint であるべきかどうかを指定する追加の options オブジェクトを受け入れます。
v10.0.0	追加: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> 返される<fs.Stats>オブジェクトの数値が bigint であるかどうか。 デフォルト: false。

• 戻り値: <Promise> 指定されたシンボリックリンク path の<fs.Stats>オブジェクトで解決されます。

path がシンボリックリンクを参照しない限り、fsPromises.stat() と同等です。シンボリックリンクの場合は、参照先のファイルではなく、リンク自体が stat されます。詳細については、POSIX の lstat(2) ドキュメントを参照してください。

fsPromises.mkdir(path[, options])

追加: v10.0.0

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> デフォルト: false
  • mode <string> | <integer> Windows ではサポートされていません。デフォルト: 0o777
• 戻り値: <Promise> 成功した場合、recursive が false の場合は undefined で、recursive が true の場合は最初に作成されたディレクトリパスで解決します。

非同期でディレクトリを作成します。

オプションの options 引数は、mode (パーミッションとスティッキービット) を指定する整数、または mode プロパティと、親ディレクトリを作成するかどうかを示す recursive プロパティを持つオブジェクトにすることができます。path が存在するディレクトリであるときに fsPromises.mkdir() を呼び出すと、recursive が false の場合にのみリジェクトされます。

ESM

import { mkdir } from 'node:fs/promises'

try {
  const projectFolder = new URL('./test/project/', import.meta.url)
  const createDir = await mkdir(projectFolder, { recursive: true })

  console.log(`created ${createDir}`)
} catch (err) {
  console.error(err.message)
}

CJS

const { mkdir } = require('node:fs/promises')
const { join } = require('node:path')

async function makeDirectory() {
  const projectFolder = join(__dirname, 'test', 'project')
  const dirCreation = await mkdir(projectFolder, { recursive: true })

  console.log(dirCreation)
  return dirCreation
}

makeDirectory().catch(console.error)

fsPromises.mkdtemp(prefix[, options])

[履歴]

バージョン	変更点
v20.6.0, v18.19.0	prefix パラメーターがバッファーと URL を受け入れるようになりました。
v16.5.0, v14.18.0	prefix パラメーターが空文字列を受け入れるようになりました。
v10.0.0	v10.0.0 で追加されました

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'

• 戻り値: <Promise> 新しく作成された一時ディレクトリのファイルシステムパスを含む文字列で履行されます。

一意の一時ディレクトリを作成します。一意のディレクトリ名は、提供された prefix の末尾に 6 つのランダムな文字を追加することによって生成されます。プラットフォームの不整合のため、prefix に末尾の X 文字を使用しないでください。一部のプラットフォーム（特に BSD）では、6 つ以上のランダムな文字を返すことができ、prefix の末尾の X 文字をランダムな文字に置き換えます。

オプションの options 引数には、使用する文字エンコーディングを指定する文字列、または encoding プロパティを持つオブジェクトを指定できます。

import { mkdtemp } from 'node:fs/promises'
import { join } from 'node:path'
import { tmpdir } from 'node:os'

try {
  await mkdtemp(join(tmpdir(), 'foo-'))
} catch (err) {
  console.error(err)
}

fsPromises.mkdtemp() メソッドは、6 つのランダムに選択された文字を prefix 文字列に直接追加します。たとえば、ディレクトリ /tmp が与えられた場合、/tmp 内 に一時ディレクトリを作成する意図がある場合、prefix は末尾のプラットフォーム固有のパス区切り文字 (require('node:path').sep) で終わる必要があります。

fsPromises.open(path, flags[, mode])

[履歴]

バージョン	変更点
v11.1.0	flags引数がオプションになり、デフォルト値が'r'になりました。
v10.0.0	v10.0.0 で追加されました。

• path <string> | <Buffer> | <URL>
• flags <string> | <number> ファイルシステムのflagsのサポートを参照してください。 デフォルト: 'r'。
• mode <string> | <integer> ファイルが作成される場合、ファイルモード（パーミッションとスティッキービット）を設定します。 デフォルト: 0o666（読み取りおよび書き込み可能）。
• 戻り値: <Promise> <FileHandle> オブジェクトで解決されます。

<FileHandle>を開きます。

詳細については、POSIX のopen(2)のドキュメントを参照してください。

一部の文字（\< \> : " / \ | ? *）は、ファイル、パス、および名前空間の名前付けで説明されているように、Windows で予約されています。NTFS では、ファイル名にコロンが含まれている場合、Node.js はこの MSDN ページで説明されているように、ファイルシステムストリームを開きます。

fsPromises.opendir(path[, options])

[履歴]

バージョン	変更点
v20.1.0, v18.17.0	recursiveオプションが追加されました。
v13.1.0, v12.16.0	bufferSizeオプションが導入されました。
v12.12.0	v12.12.0 で追加されました。

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> デフォルト: 'utf8'
  • bufferSize <number> ディレクトリから読み取るときに内部的にバッファリングされるディレクトリエントリの数。値が高いほどパフォーマンスは向上しますが、メモリ使用量も増加します。 デフォルト: 32
  • recursive <boolean> 解決されたDirは、すべてのサブファイルとディレクトリを含む<AsyncIterable>になります。デフォルト: false

• 戻り値: <Promise> <fs.Dir>で解決されます。

反復スキャンのためにディレクトリを非同期的に開きます。詳細については、POSIX のopendir(3)のドキュメントを参照してください。

<fs.Dir>を作成します。これには、ディレクトリからの読み取りとクリーンアップのためのすべての追加機能が含まれています。

encodingオプションは、ディレクトリを開く際および後続の読み取り操作中にpathのエンコーディングを設定します。

非同期イテレーションを使用する例：

import { opendir } from 'node:fs/promises'

try {
  const dir = await opendir('./')
  for await (const dirent of dir) console.log(dirent.name)
} catch (err) {
  console.error(err)
}

非同期イテレーターを使用する場合、イテレーターが終了した後、<fs.Dir>オブジェクトは自動的に閉じられます。

fsPromises.readdir(path[, options])

[履歴]

バージョン	変更点
v20.1.0, v18.17.0	recursive オプションが追加されました。
v10.11.0	新しいオプション withFileTypes が追加されました。
v10.0.0	v10.0.0 で追加されました。

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'
  • withFileTypes <boolean> デフォルト: false
  • recursive <boolean> trueの場合、ディレクトリの内容を再帰的に読み取ります。再帰モードでは、すべてのファイル、サブファイル、およびディレクトリが一覧表示されます。デフォルト: false。

• 戻り値: <Promise> ディレクトリ内のファイル名の配列（'.' と '..'を除く）で解決されます。

ディレクトリの内容を読み取ります。

オプションの options 引数は、エンコーディングを指定する文字列、またはファイル名に使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。encoding が 'buffer' に設定されている場合、返されるファイル名は <Buffer> オブジェクトとして渡されます。

options.withFileTypes が true に設定されている場合、返される配列には <fs.Dirent> オブジェクトが含まれます。

import { readdir } from 'node:fs/promises'

try {
  const files = await readdir(path)
  for (const file of files) console.log(file)
} catch (err) {
  console.error(err)
}

fsPromises.readFile(path[, options])

[履歴]

バージョン	変更点
v15.2.0, v14.17.0	options 引数に、進行中の readFile リクエストを中止するための AbortSignal を含めることができるようになりました。
v10.0.0	v10.0.0 で追加されました

• path <string> | <Buffer> | <URL> | <FileHandle> ファイル名または FileHandle

• options <Object> | <string>

  • encoding <string> | <null> デフォルト: null
  • flag <string> ファイルシステムの flags のサポート を参照してください。 デフォルト: 'r'。
  • signal <AbortSignal> 進行中の readFile を中止できるようにします

• 戻り値: <Promise> ファイルの内容で解決します。

ファイルのすべての内容を非同期に読み取ります。

エンコーディングが指定されていない場合（options.encodingを使用）、データは<Buffer>オブジェクトとして返されます。それ以外の場合、データは文字列になります。

optionsが文字列の場合、それはエンコーディングを指定します。

pathがディレクトリである場合、fsPromises.readFile()の動作はプラットフォームに固有です。 macOS、Linux、および Windows では、Promise はエラーで拒否されます。 FreeBSD では、ディレクトリの内容の表現が返されます。

実行中のコードと同じディレクトリにあるpackage.jsonファイルを読み取る例：

ESM

import { readFile } from 'node:fs/promises'
try {
  const filePath = new URL('./package.json', import.meta.url)
  const contents = await readFile(filePath, { encoding: 'utf8' })
  console.log(contents)
} catch (err) {
  console.error(err.message)
}

CJS

const { readFile } = require('node:fs/promises')
const { resolve } = require('node:path')
async function logFile() {
  try {
    const filePath = resolve('./package.json')
    const contents = await readFile(filePath, { encoding: 'utf8' })
    console.log(contents)
  } catch (err) {
    console.error(err.message)
  }
}
logFile()

<AbortSignal>を使用して、進行中のreadFileを中止することが可能です。 リクエストが中止された場合、返される Promise はAbortErrorで拒否されます。

import { readFile } from 'node:fs/promises'

try {
  const controller = new AbortController()
  const { signal } = controller
  const promise = readFile(fileName, { signal })

  // Promiseが確定する前にリクエストを中止します。
  controller.abort()

  await promise
} catch (err) {
  // リクエストが中止された場合 - errはAbortErrorです
  console.error(err)
}

進行中のリクエストを中止しても、個々のオペレーティングシステムのリクエストが中止されるのではなく、fs.readFileが実行する内部バッファリングが中止されます。

指定された<FileHandle>は読み取りをサポートしている必要があります。

fsPromises.readlink(path[, options])

追加: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'

• 戻り値: <Promise> 成功時にlinkStringで履行します。

pathで参照されるシンボリックリンクの内容を読み取ります。詳細は POSIX readlink(2)のドキュメントを参照してください。promise は成功時にlinkStringで履行されます。

オプションのoptions引数は、エンコーディングを指定する文字列、または返されるリンクパスに使用する文字エンコーディングを指定するencodingプロパティを持つオブジェクトにすることができます。encodingが'buffer'に設定されている場合、返されるリンクパスは<Buffer>オブジェクトとして渡されます。

fsPromises.realpath(path[, options])

追加: v10.0.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'

• 戻り値: <Promise> 成功時に解決されたパスで履行します。

fs.realpath.native()関数と同じセマンティクスを使用して、pathの実際の場所を決定します。

UTF8 文字列に変換できるパスのみがサポートされています。

オプションのoptions引数は、エンコーディングを指定する文字列、またはパスに使用する文字エンコーディングを指定するencodingプロパティを持つオブジェクトにすることができます。encodingが'buffer'に設定されている場合、返されるパスは<Buffer>オブジェクトとして渡されます。

Linux では、Node.js が musl libc にリンクされている場合、この関数が機能するためには、procfs ファイルシステムを/procにマウントする必要があります。Glibc にはこの制限はありません。

fsPromises.rename(oldPath, newPath)

追加: v10.0.0

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 戻り値: <Promise> 成功時に undefined で解決します。

oldPath を newPath にリネームします。

fsPromises.rmdir(path[, options])

[履歴]

バージョン	変更
v16.0.0	ファイルである path に対して fsPromises.rmdir(path, { recursive: true }) を使用することは許可されなくなり、Windows では ENOENT エラー、POSIX では ENOTDIR エラーが発生するようになりました。
v16.0.0	存在しない path に対して fsPromises.rmdir(path, { recursive: true }) を使用することは許可されなくなり、ENOENT エラーが発生するようになりました。
v16.0.0	recursive オプションは非推奨になり、使用すると非推奨警告がトリガーされます。
v14.14.0	recursive オプションは非推奨になりました。代わりに fsPromises.rm を使用してください。
v13.3.0, v12.16.0	maxBusyTries オプションは maxRetries に名前が変更され、デフォルトは 0 になりました。emfileWait オプションは削除され、EMFILE エラーは他のエラーと同じリトライロジックを使用します。retryDelay オプションがサポートされるようになりました。ENFILE エラーがリトライされるようになりました。
v12.10.0	recursive、maxBusyTries、および emfileWait オプションがサポートされるようになりました。
v10.0.0	追加: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、または EPERM エラーが発生した場合、Node.js は各試行で retryDelay ミリ秒長く線形バックオフ待機で操作を再試行します。このオプションは再試行回数を表します。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 0。
  • recursive <boolean> true の場合、再帰的なディレクトリ削除を実行します。再帰モードでは、操作は失敗時に再試行されます。デフォルト: false。非推奨。
  • retryDelay <integer> 再試行間の待機時間（ミリ秒単位）。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 100。

• 戻り値: <Promise> 成功時に undefined で解決します。

path で識別されるディレクトリを削除します。

ファイル（ディレクトリではない）で fsPromises.rmdir() を使用すると、Windows では ENOENT エラー、POSIX では ENOTDIR エラーでプロミスが拒否されます。

rm -rf Unix コマンドと同様の動作を得るには、オプション { recursive: true, force: true } を指定して fsPromises.rm() を使用します。

fsPromises.rm(path[, options])

Added in: v14.14.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • force <boolean> trueの場合、pathが存在しない場合でも例外は無視されます。デフォルト: false。
  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、またはEPERMエラーが発生した場合、Node.js は各試行でretryDelayミリ秒ずつ線形バックオフ待機で操作を再試行します。このオプションは、再試行回数を表します。このオプションは、recursiveオプションがtrueでない場合は無視されます。デフォルト: 0。
  • recursive <boolean> trueの場合、再帰的なディレクトリ削除を実行します。再帰モードでは、失敗した場合に操作が再試行されます。デフォルト: false。
  • retryDelay <integer> 再試行間の待機時間（ミリ秒単位）。このオプションは、recursiveオプションがtrueでない場合は無視されます。デフォルト: 100。

• Returns: <Promise> 成功時にundefinedで解決します。

ファイルとディレクトリを削除します（標準 POSIX rmユーティリティをモデルにしています）。

fsPromises.stat(path[, options])

[履歴]

バージョン	変更点
v10.5.0	返される数値が bigint であるべきかどうかを指定するための追加のoptionsオブジェクトを受け入れます。
v10.0.0	追加: v10.0.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> 返される<fs.Stats>オブジェクトの数値がbigintであるべきかどうか。デフォルト: false。

• Returns: <Promise> 指定されたpathの<fs.Stats>オブジェクトで解決します。

fsPromises.statfs(path[, options])

追加: v19.6.0, v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> 返される<fs.StatFs>オブジェクトの数値がbigintであるかどうか。デフォルト: false。

• 戻り値: 与えられたpathに対する<fs.StatFs>オブジェクトで解決される<Promise>。

fsPromises.symlink(target, path[, type])

[履歴]

バージョン	変更
v19.0.0	type引数がnullまたは省略された場合、Node.js はtarget型を自動検出し、dirまたはfileを自動的に選択します。
v10.0.0	追加: v10.0.0

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> デフォルト: null
• 戻り値: 成功時にundefinedで解決される<Promise>。

シンボリックリンクを作成します。

type引数は Windows プラットフォームでのみ使用され、'dir'、'file'、または'junction'のいずれかになります。type引数がnullの場合、Node.js はtarget型を自動検出し、'file'または'dir'を使用します。targetが存在しない場合は、'file'が使用されます。Windows のジャンクションポイントは、宛先パスが絶対パスである必要があります。'junction'を使用すると、target引数は自動的に絶対パスに正規化されます。NTFS ボリュームのジャンクションポイントは、ディレクトリのみを指すことができます。

fsPromises.truncate(path[, len])

Added in: v10.0.0

• path <string> | <Buffer> | <URL>
• len <integer> デフォルト: 0
• 戻り値: <Promise> 成功時に undefined で解決されます。

path のコンテンツを len バイトに切り詰めます（短縮または延長）。

fsPromises.unlink(path)

Added in: v10.0.0

• path <string> | <Buffer> | <URL>
• 戻り値: <Promise> 成功時に undefined で解決されます。

path がシンボリックリンクを参照している場合、そのリンクが参照するファイルまたはディレクトリに影響を与えずにリンクが削除されます。path がシンボリックリンクではないファイルパスを参照している場合、ファイルは削除されます。詳細については、POSIX unlink(2) のドキュメントを参照してください。

fsPromises.utimes(path, atime, mtime)

Added in: v10.0.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 戻り値: <Promise> 成功時に undefined で解決されます。

path で参照されるオブジェクトのファイルシステムのタイムスタンプを変更します。

atime および mtime 引数は次のルールに従います。

• 値は、Unix エポック時間を表す数値、Date、または '123456789.0' のような数値文字列のいずれかです。
• 値が数値に変換できない場合、または NaN、Infinity、-Infinity の場合、Error がスローされます。

fsPromises.watch(filename[, options])

追加: v15.9.0, v14.18.0

• filename <string> | <Buffer> | <URL>

• options <string> | <Object>

  • persistent <boolean> ファイルが監視されている間、プロセスが実行を継続するかどうかを示します。 デフォルト: true。
  • recursive <boolean> すべてのサブディレクトリを監視するか、現在のディレクトリのみを監視するかを示します。これはディレクトリが指定された場合に適用され、サポートされているプラットフォームでのみ適用されます（注意点を参照）。 デフォルト: false。
  • encoding <string> リスナーに渡されるファイル名に使用する文字エンコーディングを指定します。 デフォルト: 'utf8'。
  • signal <AbortSignal> ウォッチャーを停止する必要があるときにシグナルを送信するために使用される<AbortSignal>。

• 戻り値: プロパティを持つオブジェクトの<AsyncIterator>:

  • eventType <string> 変更の種類
  • filename <string> | <Buffer> | <null> 変更されたファイルの名前。

filename の変更を監視する非同期イテレータを返します。ここで filename はファイルまたはディレクトリです。

const { watch } = require('node:fs/promises')

const ac = new AbortController()
const { signal } = ac
setTimeout(() => ac.abort(), 10000)
;(async () => {
  try {
    const watcher = watch(__filename, { signal })
    for await (const event of watcher) console.log(event)
  } catch (err) {
    if (err.name === 'AbortError') return
    throw err
  }
})()

ほとんどのプラットフォームでは、ディレクトリにファイル名が表示または非表示になるたびに 'rename' が発生します。

fs.watch() のすべての注意点は、fsPromises.watch() にも適用されます。

fsPromises.writeFile(file, data[, options])

[履歴]

バージョン	変更点
v21.0.0, v20.10.0	flush オプションがサポートされるようになりました。
v15.14.0, v14.18.0	data 引数が AsyncIterable、Iterable、および Stream をサポートするようになりました。
v15.2.0, v14.17.0	オプション引数に、進行中の writeFile リクエストを中止するための AbortSignal を含めることができるようになりました。
v14.0.0	data パラメーターは、サポートされていない入力を文字列に強制変換しなくなりました。
v10.0.0	v10.0.0 で追加。

• file <string> | <Buffer> | <URL> | <FileHandle> ファイル名または FileHandle

• data <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>

• options <Object> | <string>

  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <integer> デフォルト: 0o666
  • flag <string> ファイルシステムの flags のサポートを参照してください。 デフォルト: 'w'。
  • flush <boolean> すべてのデータがファイルに正常に書き込まれ、flush が true の場合、データフラッシュに filehandle.sync() が使用されます。 デフォルト: false。
  • signal <AbortSignal> 進行中の writeFile を中止できます

• 戻り値: <Promise> 成功時に undefined で解決されます。

非同期でデータをファイルに書き込み、ファイルが既に存在する場合はファイルを置き換えます。data は、文字列、バッファー、<AsyncIterable>、または<Iterable>オブジェクトにすることができます。

data がバッファーの場合、encoding オプションは無視されます。

options が文字列の場合、エンコーディングを指定します。

mode オプションは、新しく作成されたファイルにのみ影響します。詳細については、fs.open() を参照してください。

指定された<FileHandle>は、書き込みをサポートしている必要があります。

プロミスが確定するのを待たずに、同じファイルに対して fsPromises.writeFile() を複数回使用するのは安全ではありません。

fsPromises.readFile と同様に、fsPromises.writeFile は、渡されたバッファーを書き込むために内部で複数の write 呼び出しを実行する便利なメソッドです。パフォーマンスが重要なコードの場合は、fs.createWriteStream() または filehandle.createWriteStream() の使用を検討してください。

<AbortSignal>を使用して、fsPromises.writeFile()をキャンセルすることができます。キャンセルは「ベストエフォート」であり、ある程度のデータがまだ書き込まれる可能性があります。

import { writeFile } from 'node:fs/promises'
import { Buffer } from 'node:buffer'

try {
  const controller = new AbortController()
  const { signal } = controller
  const data = new Uint8Array(Buffer.from('Hello Node.js'))
  const promise = writeFile('message.txt', data, { signal })

  // プロミスが解決する前にリクエストを中止します。
  controller.abort()

  await promise
} catch (err) {
  // リクエストが中止されると - err は AbortError になります
  console.error(err)
}

進行中のリクエストを中止しても、個々のオペレーティングシステムのリクエストは中止されず、fs.writeFile が実行する内部バッファリングが中止されます。

fsPromises.constants

追加: v18.4.0, v16.17.0

• <Object>

ファイルシステム操作でよく使用される定数を含むオブジェクトを返します。オブジェクトはfs.constantsと同じです。詳細については、FS 定数を参照してください。

コールバック API

コールバック API は、イベントループをブロックすることなく、すべての操作を非同期的に実行し、完了時またはエラー時にコールバック関数を呼び出します。

コールバック API は、基盤となる Node.js スレッドプールを使用して、イベントループスレッド外でファイルシステム操作を実行します。これらの操作は同期化されておらず、スレッドセーフではありません。同じファイルに対して複数の同時変更を行う場合は注意が必要であり、データが破損する可能性があります。

fs.access(path[, mode], callback)

[履歴]

バージョン	変更点
v20.8.0	fsに直接存在していた定数fs.F_OK、fs.R_OK、fs.W_OK、およびfs.X_OKは非推奨になりました。
v18.0.0	callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v7.6.0	pathパラメータは、file:プロトコルを使用する WHATWG URLオブジェクトにすることができます。
v6.3.0	fsに直接存在していたfs.R_OKなどの定数は、ソフト非推奨としてfs.constantsに移動しました。したがって、Node.js \< v6.3.0では、これらの定数にアクセスするためにfsを使用するか、すべてのバージョンで動作するように`(fs.constants
v0.11.15	v0.11.15 で追加。

• path <string> | <Buffer> | <URL>
• mode <integer> デフォルト: fs.constants.F_OK
• callback <Function>
  • err <Error>

pathで指定されたファイルまたはディレクトリに対するユーザーの権限をテストします。mode引数は、実行するアクセシビリティチェックを指定するオプションの整数です。modeは、値fs.constants.F_OK、またはfs.constants.R_OK、fs.constants.W_OK、およびfs.constants.X_OKのいずれかのビット単位 OR で構成されるマスクのいずれかである必要があります（例：fs.constants.W_OK | fs.constants.R_OK）。modeの可能な値については、ファイルアクセス定数を確認してください。

最後の引数callbackは、エラー引数を伴って呼び出されるコールバック関数です。アクセシビリティチェックのいずれかが失敗した場合、エラー引数はErrorオブジェクトになります。次の例では、package.jsonが存在するかどうか、および読み取り可能または書き込み可能であるかどうかを確認します。

import { access, constants } from 'node:fs'

const file = 'package.json'

// 現在のディレクトリにファイルが存在するかどうかを確認します。
access(file, constants.F_OK, err => {
  console.log(`${file} ${err ? 'does not exist' : 'exists'}`)
})

// ファイルが読み取り可能かどうかを確認します。
access(file, constants.R_OK, err => {
  console.log(`${file} ${err ? 'is not readable' : 'is readable'}`)
})

// ファイルが書き込み可能かどうかを確認します。
access(file, constants.W_OK, err => {
  console.log(`${file} ${err ? 'is not writable' : 'is writable'}`)
})

// ファイルが読み取り可能で書き込み可能かどうかを確認します。
access(file, constants.R_OK | constants.W_OK, err => {
  console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`)
})

fs.access()を使用して、fs.open()、fs.readFile()、またはfs.writeFile()を呼び出す前にファイルのアクセシビリティを確認しないでください。そうすると、2 つの呼び出しの間で他のプロセスがファイルの状態を変更する可能性があるため、競合状態が発生します。代わりに、ユーザーコードはファイルを直接開く/読み取る/書き込む必要があり、ファイルにアクセスできない場合は発生したエラーを処理する必要があります。

書き込み（推奨されません）

import { access, open, close } from 'node:fs'

access('myfile', err => {
  if (!err) {
    console.error('myfile already exists')
    return
  }

  open('myfile', 'wx', (err, fd) => {
    if (err) throw err

    try {
      writeMyData(fd)
    } finally {
      close(fd, err => {
        if (err) throw err
      })
    }
  })
})

書き込み（推奨）

import { open, close } from 'node:fs'

open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists')
      return
    }

    throw err
  }

  try {
    writeMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

読み取り（推奨されません）

import { access, open, close } from 'node:fs'
access('myfile', err => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist')
      return
    }

    throw err
  }

  open('myfile', 'r', (err, fd) => {
    if (err) throw err

    try {
      readMyData(fd)
    } finally {
      close(fd, err => {
        if (err) throw err
      })
    }
  })
})

読み取り（推奨）

import { open, close } from 'node:fs'

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist')
      return
    }

    throw err
  }

  try {
    readMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

上記の「推奨されない」例では、アクセシビリティを確認してからファイルを使用します。「推奨」の例の方が優れているのは、ファイルを直接使用し、エラーが発生した場合はそれを処理するためです。

一般に、ファイルのアクセシビリティは、ファイルが直接使用されない場合にのみ確認してください。たとえば、アクセシビリティが別のプロセスからのシグナルである場合などです。

Windows では、ディレクトリのアクセス制御ポリシー（ACL）により、ファイルまたはディレクトリへのアクセスが制限される場合があります。ただし、fs.access()関数は ACL をチェックしないため、ACL がユーザーの読み取りまたは書き込みを制限している場合でも、パスにアクセス可能であると報告する可能性があります。

fs.appendFile(path, data[, options], callback)

[履歴]

バージョン	変更点
v21.1.0, v20.10.0	flush オプションがサポートされました。
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.0.0	callback パラメータはオプションではなくなりました。渡さないと、実行時に TypeError がスローされます。
v7.0.0	callback パラメータはオプションではなくなりました。渡さないと、ID DEP0013 で非推奨警告が出力されます。
v7.0.0	渡された options オブジェクトは変更されなくなりました。
v5.0.0	file パラメータがファイルディスクリプタになりました。
v0.6.7	v0.6.7 で追加されました。

• path <string> | <Buffer> | <URL> | <number> ファイル名またはファイルディスクリプタ

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <integer> デフォルト: 0o666
  • flag <string> ファイルシステムの flags のサポート を参照してください。 デフォルト: 'a'。
  • flush <boolean> true の場合、基になるファイルディスクリプタは閉じられる前にフラッシュされます。 デフォルト: false。

• callback <Function>

  • err <Error>

ファイルを非同期でデータ追記し、ファイルが存在しない場合は作成します。data は文字列または <Buffer> になります。

mode オプションは、新しく作成されたファイルにのみ影響します。詳細については、fs.open() を参照してください。

import { appendFile } from 'node:fs'

appendFile('message.txt', '追記するデータ', err => {
  if (err) throw err
  console.log('「追記するデータ」がファイルに追記されました!')
})

options が文字列の場合、エンコーディングを指定します。

import { appendFile } from 'node:fs'

appendFile('message.txt', '追記するデータ', 'utf8', callback)

path は、追記用にオープンされた数値ファイルディスクリプタとして指定できます（fs.open() または fs.openSync() を使用）。ファイルディスクリプタは自動的に閉じられません。

import { open, close, appendFile } from 'node:fs'

function closeFd(fd) {
  close(fd, err => {
    if (err) throw err
  })
}

open('message.txt', 'a', (err, fd) => {
  if (err) throw err

  try {
    appendFile(fd, '追記するデータ', 'utf8', err => {
      closeFd(fd)
      if (err) throw err
    })
  } catch (err) {
    closeFd(fd)
    throw err
  }
})

fs.chmod(path, mode, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE をスローするようになりました。
v10.0.0	callback パラメーターは必須になりました。渡さないと実行時に TypeError がスローされます。
v7.6.0	path パラメーターは file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v7.0.0	callback パラメーターは必須になりました。渡さないと、ID DEP0013 の非推奨警告が発行されます。
v0.1.30	v0.1.30 で追加されました

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

ファイルのパーミッションを非同期的に変更します。完了コールバックには、起こりうる例外以外の引数は渡されません。

詳細については、POSIX chmod(2) のドキュメントを参照してください。

import { chmod } from 'node:fs'

chmod('my_file.txt', 0o775, err => {
  if (err) throw err
  console.log('ファイル "my_file.txt" のパーミッションが変更されました！')
})

ファイルモード

fs.chmod() および fs.chmodSync() メソッドで使用される mode 引数は、次の定数の論理 OR を使用して作成される数値ビットマスクです。

定数	8 進数	説明
fs.constants.S_IRUSR	0o400	所有者による読み取り
fs.constants.S_IWUSR	0o200	所有者による書き込み
fs.constants.S_IXUSR	0o100	所有者による実行/検索
fs.constants.S_IRGRP	0o40	グループによる読み取り
fs.constants.S_IWGRP	0o20	グループによる書き込み
fs.constants.S_IXGRP	0o10	グループによる実行/検索
fs.constants.S_IROTH	0o4	他のユーザーによる読み取り
fs.constants.S_IWOTH	0o2	他のユーザーによる書き込み
fs.constants.S_IXOTH	0o1	他のユーザーによる実行/検索

mode を構成する簡単な方法は、3 つの 8 進数 (例: 765) のシーケンスを使用することです。最も左の数字 (例の 7) は、ファイルの所有者のパーミッションを指定します。中央の数字 (例の 6) は、グループのパーミッションを指定します。最も右の数字 (例の 5) は、他のユーザーのパーミッションを指定します。

数字	説明
7	読み取り、書き込み、および実行
6	読み取りと書き込み
5	読み取りと実行
4	読み取り専用
3	書き込みと実行
2	書き込み専用
1	実行専用
0	パーミッションなし

たとえば、8 進数値 0o765 は次の意味になります。

• 所有者はファイルの読み取り、書き込み、および実行が可能です。
• グループはファイルの読み取りと書き込みが可能です。
• 他のユーザーはファイルの読み取りと実行が可能です。

ファイルモードが予期される場所で生の数値を使用する場合、0o777 より大きい値を使用すると、プラットフォーム固有の動作が発生する可能性があり、一貫して動作することはサポートされていません。そのため、S_ISVTX、S_ISGID、または S_ISUID のような定数は fs.constants で公開されていません。

注意: Windows では書き込みパーミッションのみを変更でき、グループ、所有者、または他のユーザーのパーミッションの区別は実装されていません。

fs.chown(path, uid, gid, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v10.0.0	callback パラメータは必須になりました。渡さないと、実行時に TypeError がスローされます。
v7.6.0	path パラメータは file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v7.0.0	callback パラメータは必須になりました。渡さないと、ID DEP0013 の非推奨警告が発行されます。
v0.1.97	追加: v0.1.97

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

ファイルの所有者とグループを非同期的に変更します。完了コールバックには、例外が発生した場合を除き、引数は渡されません。

詳細は、POSIX の chown(2) ドキュメントを参照してください。

fs.close(fd[, callback])

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v15.9.0, v14.17.0	コールバックが提供されない場合、デフォルトのコールバックが使用されるようになりました。
v10.0.0	callback パラメータは必須になりました。渡さないと、実行時に TypeError がスローされます。
v7.0.0	callback パラメータは必須になりました。渡さないと、ID DEP0013 の非推奨警告が発行されます。
v0.0.2	追加: v0.0.2

• fd <integer>
• callback <Function>
  • err <Error>

ファイル記述子を閉じます。完了コールバックには、例外が発生した場合を除き、引数は渡されません。

他の fs 操作で現在使用中のファイル記述子 (fd) に対して fs.close() を呼び出すと、未定義の動作につながる可能性があります。

詳細は、POSIX の close(2) ドキュメントを参照してください。

fs.copyFile(src, dest[, mode], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなく、ERR_INVALID_ARG_TYPEをスローするようになりました。
v14.0.0	flags 引数を mode に変更し、より厳密な型検証を課しました。
v8.5.0	追加: v8.5.0

• src <string> | <Buffer> | <URL> コピー元のファイル名
• dest <string> | <Buffer> | <URL> コピー先のファイル名
• mode <integer> コピー操作の修飾子。デフォルト: 0。
• callback <Function>
  • err <Error>

src を dest に非同期的にコピーします。デフォルトでは、dest が既に存在する場合、上書きされます。コールバック関数には、発生する可能性のある例外以外の引数は渡されません。Node.js はコピー操作の原子性については保証しません。書き込みのためにコピー先のファイルを開いた後にエラーが発生した場合、Node.js はコピー先の削除を試みます。

mode は、コピー操作の動作を指定するオプションの整数です。2 つ以上の値のビット単位の OR で構成されるマスクを作成できます (例: fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE)。

• fs.constants.COPYFILE_EXCL: コピー先 (dest) が既に存在する場合、コピー操作は失敗します。
• fs.constants.COPYFILE_FICLONE: コピー操作は、コピーオンライトのリフリンクを作成しようとします。プラットフォームがコピーオンライトをサポートしていない場合は、フォールバック コピーメカニズムが使用されます。
• fs.constants.COPYFILE_FICLONE_FORCE: コピー操作は、コピーオンライトのリフリンクを作成しようとします。プラットフォームがコピーオンライトをサポートしていない場合、操作は失敗します。

import { copyFile, constants } from 'node:fs'

function callback(err) {
  if (err) throw err
  console.log('source.txt が destination.txt にコピーされました')
}

// デフォルトでは、destination.txt が作成されるか、上書きされます。
copyFile('source.txt', 'destination.txt', callback)

// COPYFILE_EXCL を使用すると、destination.txt が存在する場合、操作は失敗します。
copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback)

fs.cp(src, dest[, options], callback)

[履歴]

バージョン	変更点
v22.3.0	この API は実験的ではなくなりました。
v20.1.0, v18.17.0	fs.copyFile() の mode 引数としてコピーの動作を指定するための追加の mode オプションを受け入れるようになりました。
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK ではなく ERR_INVALID_ARG_TYPE がスローされるようになりました。
v17.6.0, v16.15.0	シンボリックリンクのパス解決を実行するかどうかを指定するための追加の verbatimSymlinks オプションを受け入れるようになりました。
v16.7.0	v16.7.0 で追加されました。

• src <string> | <URL> コピー元のパス。

• dest <string> | <URL> コピー先のパス。

• options <Object>

  • dereference <boolean> シンボリックリンクをデリファレンスします。デフォルト: false。

  • errorOnExist <boolean> force が false の場合、コピー先が存在するとエラーをスローします。デフォルト: false。

  • filter <Function> コピーするファイル/ディレクトリをフィルタリングする関数。項目をコピーする場合は true を、無視する場合は false を返します。ディレクトリを無視すると、その内容もすべてスキップされます。true または false に解決する Promise を返すこともできます。デフォルト: undefined。

  • src <string> コピー元のパス。

  • dest <string> コピー先のパス。

  • 戻り値: <boolean> | <Promise> boolean に強制できる値またはそのような値で完了する Promise。

  • force <boolean> 既存のファイルまたはディレクトリを上書きします。これが false に設定されていてコピー先が存在する場合、コピー操作はエラーを無視します。この動作を変更するには errorOnExist オプションを使用してください。デフォルト: true。

  • mode <integer> コピー操作の修飾子。デフォルト: 0。fs.copyFile() の mode フラグを参照してください。

  • preserveTimestamps <boolean> true の場合、src のタイムスタンプが保持されます。デフォルト: false。

  • recursive <boolean> ディレクトリを再帰的にコピーします。デフォルト: false

  • verbatimSymlinks <boolean> true の場合、シンボリックリンクのパス解決はスキップされます。デフォルト: false

• callback <Function>

  • err <Error>

src から dest へのディレクトリ構造全体（サブディレクトリとファイルを含む）を非同期にコピーします。

あるディレクトリを別のディレクトリにコピーする場合、グロブはサポートされておらず、動作は cp dir1/ dir2/ に似ています。

fs.createReadStream(path[, options])

[履歴]

バージョン	変更点
v16.10.0	fd が提供されている場合、fs オプションは open メソッドを必要としません。
v16.10.0	autoClose が false の場合、fs オプションは close メソッドを必要としません。
v15.5.0	AbortSignal のサポートを追加。
v15.4.0	fd オプションで FileHandle 引数を受け付けるようになりました。
v14.0.0	emitClose のデフォルトを true に変更。
v13.6.0, v12.17.0	fs オプションで、使用される fs 実装をオーバーライドできるようになりました。
v12.10.0	emitClose オプションを有効化。
v11.0.0	start と end に新しい制限を課し、入力値を適切に処理できない場合に、より適切なエラーをスローするようにしました。
v7.6.0	path パラメータは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v7.0.0	渡された options オブジェクトは変更されなくなりました。
v2.3.0	渡された options オブジェクトは文字列にすることができます。
v0.1.31	v0.1.31 で追加。

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • flags <string> ファイルシステムの flags のサポートを参照してください。 デフォルト: 'r'。
  • encoding <string> デフォルト: null
  • fd <integer> | <FileHandle> デフォルト: null
  • mode <integer> デフォルト: 0o666
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • end <integer> デフォルト: Infinity
  • highWaterMark <integer> デフォルト: 64 * 1024
  • fs <Object> | <null> デフォルト: null
  • signal <AbortSignal> | <null> デフォルト: null

• 戻り値: <fs.ReadStream>

options には、ファイル全体ではなくファイルのバイト範囲を読み取るための start と end の値を含めることができます。 start と end は両方とも包括的で、0 からカウントを開始します。許可される値は [0, Number.MAX_SAFE_INTEGER] の範囲です。 fd が指定されていて、start が省略されているか undefined の場合、fs.createReadStream() は現在のファイル位置から順番に読み取ります。 encoding は、<Buffer> で受け入れられるもののいずれかを使用できます。

fd が指定されている場合、ReadStream は path 引数を無視し、指定されたファイル記述子を使用します。 これは 'open' イベントが発行されないことを意味します。 fd はブロッキングである必要があります。非ブロッキング fd は <net.Socket> に渡す必要があります。

fd が、キーボードやサウンドカードなど、ブロッキング読み取りのみをサポートするキャラクタデバイスを指している場合、データが利用可能になるまで読み取り操作は完了しません。 これにより、プロセスが終了できなくなり、ストリームが自然に閉じられなくなる可能性があります。

デフォルトでは、ストリームは破棄された後に 'close' イベントを発行します。 この動作を変更するには、emitClose オプションを false に設定してください。

fs オプションを提供することで、open、read、および close の対応する fs 実装をオーバーライドできます。 fs オプションを提供する場合、read のオーバーライドが必要です。 fd が提供されていない場合は、open のオーバーライドも必要です。 autoClose が true の場合は、close のオーバーライドも必要です。

import { createReadStream } from 'node:fs'

// いくつかのキャラクタデバイスからストリームを作成します。
const stream = createReadStream('/dev/input/event0')
setTimeout(() => {
  stream.close() // これはストリームを閉じない場合があります。
  // 基になるリソースがファイル終了をそれ自体で示していたかのように、ストリームの終わりを人為的にマークすると、ストリームを閉じることができます。
  // これは保留中の読み取り操作をキャンセルせず、そのような操作がある場合、プロセスは完了するまで正常に終了できない可能性があります。
  stream.push(null)
  stream.read(0)
}, 100)

autoClose が false の場合、エラーが発生した場合でもファイル記述子は閉じられません。 ファイル記述子のリークがないことを確認し、閉じるのはアプリケーションの責任です。 autoClose が true (デフォルトの動作) に設定されている場合、'error' または 'end' でファイル記述子が自動的に閉じられます。

mode はファイルモード (パーミッションとスティッキービット) を設定しますが、ファイルが作成された場合にのみです。

100 バイトのファイルの最後の 10 バイトを読み取る例:

import { createReadStream } from 'node:fs'

createReadStream('sample.txt', { start: 90, end: 99 })

options が文字列の場合、エンコーディングを指定します。

fs.createWriteStream(path[, options])

[履歴]

バージョン	変更点
v21.0.0, v20.10.0	flush オプションがサポートされるようになりました。
v16.10.0	fd が提供されている場合、fs オプションは open メソッドを必要としません。
v16.10.0	autoClose が false の場合、fs オプションは close メソッドを必要としません。
v15.5.0	AbortSignal のサポートが追加されました。
v15.4.0	fd オプションは FileHandle 引数を受け入れるようになりました。
v14.0.0	emitClose のデフォルトが true に変更されました。
v13.6.0, v12.17.0	fs オプションで、使用する fs 実装を上書きできるようになりました。
v12.10.0	emitClose オプションが有効になりました。
v7.6.0	path パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v7.0.0	渡された options オブジェクトが変更されることはありません。
v5.5.0	autoClose オプションがサポートされるようになりました。
v2.3.0	渡された options オブジェクトが文字列にできるようになりました。
v0.1.31	追加: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • flags <string> ファイルシステムの flags のサポート を参照してください。 デフォルト: 'w'。
  • encoding <string> デフォルト: 'utf8'
  • fd <integer> | <FileHandle> デフォルト: null
  • mode <integer> デフォルト: 0o666
  • autoClose <boolean> デフォルト: true
  • emitClose <boolean> デフォルト: true
  • start <integer>
  • fs <Object> | <null> デフォルト: null
  • signal <AbortSignal> | <null> デフォルト: null
  • highWaterMark <number> デフォルト: 16384
  • flush <boolean> true の場合、基になるファイル記述子は、閉じられる前にフラッシュされます。 デフォルト: false。

• 戻り値: <fs.WriteStream>

options には、ファイルの先頭を過ぎた位置にデータを書き込むことができる start オプションを含めることもできます。許容される値は [0, Number.MAX_SAFE_INTEGER] の範囲です。ファイルを置き換えるのではなく変更するには、flags オプションをデフォルトの w ではなく r+ に設定する必要がある場合があります。encoding は、<Buffer> で受け入れられるもののいずれかになります。

autoClose が true (デフォルトの動作) に設定されている場合、'error' または 'finish' でファイル記述子が自動的に閉じられます。autoClose が false の場合、エラーが発生した場合でも、ファイル記述子は閉じられません。それを閉じてファイル記述子のリークがないことを確認するのはアプリケーションの責任です。

デフォルトでは、ストリームは破棄された後に 'close' イベントを発行します。この動作を変更するには、emitClose オプションを false に設定します。

fs オプションを提供することにより、open、write、writev、および close の対応する fs 実装を上書きすることが可能です。writev() なしで write() をオーバーライドすると、一部の最適化 (_writev()) が無効になるため、パフォーマンスが低下する可能性があります。fs オプションを提供する場合、少なくとも write と writev のいずれかのオーバーライドが必要です。fd オプションが提供されていない場合は、open のオーバーライドも必要です。autoClose が true の場合は、close のオーバーライドも必要です。

<fs.ReadStream> と同様に、fd が指定されている場合、<fs.WriteStream> は path 引数を無視し、指定されたファイル記述子を使用します。これは、'open' イベントが発行されないことを意味します。fd はブロックする必要があります。非ブロック fd は、<net.Socket> に渡す必要があります。

options が文字列の場合、それはエンコーディングを指定します。

fs.exists(path, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK ではなく ERR_INVALID_ARG_TYPE がスローされるようになりました。
v7.6.0	path パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v1.0.0	非推奨: v1.0.0 以降
v0.0.2	追加: v0.0.2

[安定版: 0 - 非推奨]

安定版: 0 安定度: 0 - 非推奨: 代わりに fs.stat() または fs.access() を使用してください。

• path <string> | <Buffer> | <URL>
• callback <Function>
  • exists <boolean>

与えられた path に要素が存在するかどうかを、ファイルシステムで確認してテストします。次に、callback 引数を true または false のいずれかで呼び出します。

import { exists } from 'node:fs'

exists('/etc/passwd', e => {
  console.log(e ? '存在します' : 'passwd はありません!')
})

このコールバックのパラメーターは、他の Node.js コールバックと一貫性がありません。 通常、Node.js コールバックの最初のパラメーターは err パラメーターであり、オプションで他のパラメーターが続きます。fs.exists() コールバックには、1 つのブールパラメーターしかありません。これは、fs.exists() の代わりに fs.access() が推奨される理由の 1 つです。

path がシンボリックリンクの場合、それは追跡されます。したがって、path が存在しても、存在しない要素を指している場合、コールバックは値 false を受け取ります。

fs.open()、fs.readFile()、または fs.writeFile() を呼び出す前に、ファイルの存在を確認するために fs.exists() を使用することは推奨されません。そうすると、2 つの呼び出しの間で他のプロセスがファイルの状態を変更する可能性があるため、競合状態が発生します。代わりに、ユーザーコードはファイルを直接開く/読み取り/書き込みを行い、ファイルが存在しない場合に発生するエラーを処理する必要があります。

書き込み (推奨されません)

import { exists, open, close } from 'node:fs'

exists('myfile', e => {
  if (e) {
    console.error('myfile はすでに存在します')
  } else {
    open('myfile', 'wx', (err, fd) => {
      if (err) throw err

      try {
        writeMyData(fd)
      } finally {
        close(fd, err => {
          if (err) throw err
        })
      }
    })
  }
})

書き込み (推奨)

import { open, close } from 'node:fs'
open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile はすでに存在します')
      return
    }

    throw err
  }

  try {
    writeMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

読み取り (推奨されません)

import { open, close, exists } from 'node:fs'

exists('myfile', e => {
  if (e) {
    open('myfile', 'r', (err, fd) => {
      if (err) throw err

      try {
        readMyData(fd)
      } finally {
        close(fd, err => {
          if (err) throw err
        })
      }
    })
  } else {
    console.error('myfile は存在しません')
  }
})

読み取り (推奨)

import { open, close } from 'node:fs'

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile は存在しません')
      return
    }

    throw err
  }

  try {
    readMyData(fd)
  } finally {
    close(fd, err => {
      if (err) throw err
    })
  }
})

上記の「推奨されない」例では、存在を確認してからファイルを使用しています。一方、「推奨される」例は、ファイルを直接使用し、エラーがあれば処理するため、より優れています。

一般的に、ファイルの存在は、そのファイルが直接使用されない場合にのみ確認してください。たとえば、その存在が別のプロセスからのシグナルである場合などです。

fs.fchmod(fd, mode, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.0.0	callback パラメータは必須になりました。渡さないと、実行時に TypeError がスローされます。
v7.0.0	callback パラメータは必須になりました。渡さないと、ID DEP0013 の非推奨警告が発行されます。
v0.4.7	v0.4.7 で追加されました。

• fd <integer>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

ファイルに対するアクセス許可を設定します。完了コールバックには、発生する可能性のある例外以外の引数は渡されません。

詳細については、POSIX fchmod(2) のドキュメントを参照してください。

fs.fchown(fd, uid, gid, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.0.0	callback パラメータは必須になりました。渡さないと、実行時に TypeError がスローされます。
v7.0.0	callback パラメータは必須になりました。渡さないと、ID DEP0013 の非推奨警告が発行されます。
v0.4.7	v0.4.7 で追加されました。

• fd <integer>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

ファイルの所有者を設定します。完了コールバックには、発生する可能性のある例外以外の引数は渡されません。

詳細については、POSIX fchown(2) のドキュメントを参照してください。

fs.fdatasync(fd, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.0.0	callback パラメーターはオプションではなくなりました。渡さないと実行時に TypeError がスローされます。
v7.0.0	callback パラメーターはオプションではなくなりました。渡さないと ID DEP0013 の非推奨警告が発生します。
v0.1.96	v0.1.96 で追加されました。

• fd <integer>
• callback <Function>
  • err <Error>

ファイルに関連付けられた現在キューに入れられているすべての I/O 操作を、オペレーティングシステムの同期 I/O 完了状態に強制します。詳細は、POSIX fdatasync(2) のドキュメントを参照してください。完了コールバックには、例外の可能性以外の引数は渡されません。

fs.fstat(fd[, options], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.5.0	返される数値が bigint であるかどうかを指定する追加の options オブジェクトを受け入れるようになりました。
v10.0.0	callback パラメーターはオプションではなくなりました。渡さないと実行時に TypeError がスローされます。
v7.0.0	callback パラメーターはオプションではなくなりました。渡さないと ID DEP0013 の非推奨警告が発生します。
v0.1.95	v0.1.95 で追加されました。

• fd <integer>

• options <Object>

  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるかどうか。デフォルト: false。

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

ファイル記述子の <fs.Stats> を使ってコールバックを呼び出します。

詳細については、POSIX fstat(2) のドキュメントを参照してください。

fs.fsync(fd, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK ではなく ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.0.0	callback パラメーターは必須になりました。渡さないと、実行時に TypeError がスローされます。
v7.0.0	callback パラメーターは必須ではなくなりました。渡さないと、ID DEP0013 の非推奨警告が出力されます。
v0.1.96	v0.1.96 で追加されました。

• fd <integer>
• callback <Function>
  • err <Error>

オープンされているファイルディスクリプターのすべてのデータがストレージデバイスにフラッシュされるように要求します。具体的な実装はオペレーティングシステムおよびデバイスに固有です。詳細については、POSIX fsync(2) のドキュメントを参照してください。完了コールバックには、起こりうる例外以外の引数は渡されません。

fs.ftruncate(fd[, len], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK ではなく ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.0.0	callback パラメーターは必須になりました。渡さないと、実行時に TypeError がスローされます。
v7.0.0	callback パラメーターは必須ではなくなりました。渡さないと、ID DEP0013 の非推奨警告が出力されます。
v0.8.6	v0.8.6 で追加されました。

• fd <integer>
• len <integer> デフォルト: 0
• callback <Function>
  • err <Error>

ファイルディスクリプターを切り詰めます。完了コールバックには、起こりうる例外以外の引数は渡されません。

詳細については、POSIX ftruncate(2) のドキュメントを参照してください。

ファイルディスクリプターで参照されるファイルが len バイトより大きい場合、ファイルの最初の len バイトのみが保持されます。

たとえば、次のプログラムはファイルの最初の 4 バイトのみを保持します。

import { open, close, ftruncate } from 'node:fs'

function closeFd(fd) {
  close(fd, err => {
    if (err) throw err
  })
}

open('temp.txt', 'r+', (err, fd) => {
  if (err) throw err

  try {
    ftruncate(fd, 4, err => {
      closeFd(fd)
      if (err) throw err
    })
  } catch (err) {
    closeFd(fd)
    if (err) throw err
  }
})

ファイルが以前に len バイトより短かった場合は拡張され、拡張された部分はヌルバイト ('\0') で埋められます。

len が負の場合は 0 が使用されます。

fs.futimes(fd, atime, mtime, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE をスローするようになりました。
v10.0.0	callback パラメータはオプションではなくなりました。渡さない場合、実行時に TypeError がスローされます。
v7.0.0	callback パラメータはオプションではなくなりました。渡さない場合、ID DEP0013 の非推奨警告が発せられます。
v4.1.0	数値文字列、NaN、および Infinity が時間指定子として許可されるようになりました。
v0.4.2	追加: v0.4.2

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

指定されたファイルディスクリプタによって参照されるオブジェクトのファイルシステムのタイムスタンプを変更します。fs.utimes() を参照してください。

fs.glob(pattern[, options], callback)

[履歴]

バージョン	変更点
v22.2.0	withFileTypes をオプションとしてサポートしました。
v22.0.0	追加: v22.0.0

[安定版: 1 - 試験的]

安定版: 1 安定版: 1 - 試験的

• pattern <string> | <string[]>
• options <Object>
  • cwd <string> 現在の作業ディレクトリ。デフォルト: process.cwd()
  • exclude <Function> ファイル/ディレクトリを除外するための関数。項目を除外する場合は true を、含める場合は false を返します。デフォルト: undefined。
  • withFileTypes <boolean> glob がパスを Dirent として返す場合は true、それ以外の場合は false。デフォルト: false。
• callback <Function>
  • err <Error>

指定されたパターンに一致するファイルを取得します。

ESM

import { glob } from 'node:fs'

glob('**/*.js', (err, matches) => {
  if (err) throw err
  console.log(matches)
})

CJS

const { glob } = require('node:fs')

glob('**/*.js', (err, matches) => {
  if (err) throw err
  console.log(matches)
})

fs.lchmod(path, mode, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v16.0.0	複数のエラーが返された場合、返されるエラーは AggregateError になる可能性があります。
v10.0.0	callback パラメーターはオプションではなくなりました。渡さないと、実行時に TypeError がスローされます。
v7.0.0	callback パラメーターはオプションではなくなりました。渡さないと、ID DEP0013 の非推奨警告が発生します。
v0.4.7	非推奨: v0.4.7 以降

• path <string> | <Buffer> | <URL>
• mode <integer>
• callback <Function>
  • err <Error> | <AggregateError>

シンボリックリンクのパーミッションを変更します。完了コールバックには、例外が発生した場合以外は引数は渡されません。

このメソッドは macOS でのみ実装されています。

詳細については、POSIX lchmod(2) のドキュメントを参照してください。

fs.lchown(path, uid, gid, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.6.0	この API は非推奨ではなくなりました。
v10.0.0	callback パラメーターはオプションではなくなりました。渡さないと、実行時に TypeError がスローされます。
v7.0.0	callback パラメーターはオプションではなくなりました。渡さないと、ID DEP0013 の非推奨警告が発生します。
v0.4.7	ドキュメントのみの非推奨。

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

シンボリックリンクの所有者を設定します。完了コールバックには、例外が発生した場合以外は引数は渡されません。

詳細については、POSIX lchown(2) のドキュメントを参照してください。

fs.lutimes(path, atime, mtime, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v14.5.0, v12.19.0	追加: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

fs.utimes() と同じようにファイルのアクセス時間と変更時間を変更しますが、パスがシンボリックリンクを参照する場合、リンクは逆参照されず、代わりにシンボリックリンク自体のタイムスタンプが変更される点が異なります。

完了コールバックには、起こりうる例外以外の引数は渡されません。

fs.link(existingPath, newPath, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.0.0	callback パラメータはオプションではなくなりました。渡さないと実行時に TypeError がスローされます。
v7.6.0	existingPath パラメータと newPath パラメータは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。現在、サポートはまだ実験的です。
v7.0.0	callback パラメータはオプションではなくなりました。渡さないと、ID DEP0013 の非推奨警告が発せられます。
v0.1.31	追加: v0.1.31

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

existingPath から newPath への新しいリンクを作成します。詳細については、POSIX link(2) のドキュメントを参照してください。完了コールバックには、起こりうる例外以外の引数は渡されません。

fs.lstat(path[, options], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.5.0	返される数値が bigint であるかどうかを指定するための追加の options オブジェクトを受け入れるようになりました。
v10.0.0	callback パラメータが必須になりました。渡さない場合は、実行時に TypeError がスローされます。
v7.6.0	path パラメータは、file: プロトコルを使用した WHATWG URL オブジェクトにできます。
v7.0.0	callback パラメータが必須になりました。渡さない場合は、ID DEP0013 の非推奨警告が発行されます。
v0.1.30	v0.1.30 で追加されました。

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるかどうか。デフォルト: false。

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

パスで参照されるシンボリックリンクの <fs.Stats> を取得します。コールバックは (err, stats) の 2 つの引数を受け取り、stats は <fs.Stats> オブジェクトです。lstat() は stat() と同じですが、path がシンボリックリンクの場合、参照先のファイルではなく、リンク自体が stat されます。

詳細については、POSIX の lstat(2) ドキュメントを参照してください。

fs.mkdir(path[, options], callback)

[履歴]

バージョン	変更点
v18.0.0	callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v13.11.0, v12.17.0	recursiveモードでは、コールバックは最初に作成されたパスを引数として受け取るようになりました。
v10.12.0	2 番目の引数に、recursiveとmodeプロパティを持つoptionsオブジェクトを使用できるようになりました。
v10.0.0	callbackパラメータは必須になりました。渡さないと、実行時にTypeErrorがスローされます。
v7.6.0	pathパラメータは、file:プロトコルを使用する WHATWG URLオブジェクトを使用できるようになりました。
v7.0.0	callbackパラメータは必須になりました。渡さないと、ID DEP0013 の非推奨警告が発行されます。
v0.1.8	v0.1.8 で追加されました。

• path <string> | <Buffer> | <URL>

• options <Object> | <integer>

  • recursive <boolean> デフォルト: false
  • mode <string> | <integer> Windows ではサポートされていません。 デフォルト: 0o777.

• callback <Function>

  • err <Error>
  • path <string> | <undefined> recursiveがtrueに設定されてディレクトリが作成された場合にのみ存在します。

非同期的にディレクトリを作成します。

コールバックには、可能性のある例外と、recursiveがtrueの場合は、作成された最初のディレクトリパス (err[, path]) が渡されます。ディレクトリが作成されなかった場合（たとえば、以前に作成されていた場合）、recursiveがtrueの場合でも、pathはundefinedになる可能性があります。

オプションのoptions引数は、mode（パーミッションとスティッキービット）を指定する整数、またはmodeプロパティと、親ディレクトリを作成する必要があるかどうかを示すrecursiveプロパティを持つオブジェクトにすることができます。 pathが既存のディレクトリである場合にfs.mkdir()を呼び出すと、recursiveが false の場合にのみエラーが発生します。 recursiveが false で、ディレクトリが存在する場合は、EEXISTエラーが発生します。

import { mkdir } from 'node:fs'

// ./tmpと./tmp/aが存在するかどうかに関係なく、./tmp/a/appleを作成します。
mkdir('./tmp/a/apple', { recursive: true }, err => {
  if (err) throw err
})

Windows では、再帰を使用した場合でも、ルートディレクトリでfs.mkdir()を使用するとエラーが発生します。

import { mkdir } from 'node:fs'

mkdir('/', { recursive: true }, err => {
  // => [Error: EPERM: operation not permitted, mkdir 'C:\']
})

詳細については、POSIX mkdir(2) ドキュメントを参照してください。

fs.mkdtemp(prefix[, options], callback)

[履歴]

バージョン	変更
v20.6.0, v18.19.0	prefix パラメータがバッファと URL を受け入れるようになりました。
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v16.5.0, v14.18.0	prefix パラメータが空文字列を受け入れるようになりました。
v10.0.0	callback パラメータがオプションではなくなりました。渡さないと、実行時に TypeError がスローされます。
v7.0.0	callback パラメータがオプションではなくなりました。渡さないと、ID DEP0013 の非推奨警告が発せられます。
v6.2.1	callback パラメータがオプションになりました。
v5.10.0	v5.10.0 で追加されました。

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'

• callback <Function>

  • err <Error>
  • directory <string>

一意な一時ディレクトリを作成します。

一意な一時ディレクトリを作成するために、必須の prefix の後ろに 6 つのランダムな文字を生成して追加します。プラットフォームの不整合のため、prefix 内で末尾に X 文字を使用することは避けてください。一部のプラットフォーム（特に BSD）では、6 つ以上のランダムな文字が返される可能性があり、prefix 内の末尾の X 文字がランダムな文字で置き換えられることがあります。

作成されたディレクトリパスは、コールバックの 2 番目のパラメータに文字列として渡されます。

オプションの options 引数は、使用する文字エンコーディングを指定する文字列、または encoding プロパティを持つオブジェクトにすることができます。

import { mkdtemp } from 'node:fs'
import { join } from 'node:path'
import { tmpdir } from 'node:os'

mkdtemp(join(tmpdir(), 'foo-'), (err, directory) => {
  if (err) throw err
  console.log(directory)
  // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
})

fs.mkdtemp() メソッドは、ランダムに選択された 6 つの文字を prefix 文字列に直接追加します。たとえば、ディレクトリ /tmp が与えられたとき、/tmp 内 に一時ディレクトリを作成することが意図されている場合、prefix はプラットフォーム固有のパス区切り文字（require('node:path').sep）で終わる必要があります。

import { tmpdir } from 'node:os'
import { mkdtemp } from 'node:fs'

// 新しい一時ディレクトリの親ディレクトリ
const tmpDir = tmpdir()

// このメソッドは *不正* です:
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // `/tmpabc123` のようなものが表示されます。
  // 新しい一時ディレクトリは、/tmp ディレクトリ *内* ではなく、ファイルシステムのルートに作成されます。
})

// このメソッドは *正しい* です:
import { sep } from 'node:path'
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err
  console.log(directory)
  // `/tmp/abc123` のようなものが表示されます。
  // 新しい一時ディレクトリは、/tmp ディレクトリ内に作成されます。
})

fs.open(path[, flags[, mode]], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE をスローするようになりました。
v11.1.0	flags 引数がオプションになり、デフォルトは 'r' になりました。
v9.9.0	as および as+ フラグがサポートされるようになりました。
v7.6.0	path パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v0.0.2	v0.0.2 で追加されました。

• path <string> | <Buffer> | <URL>
• flags <string> | <number> ファイルシステムの flags のサポート を参照してください。 デフォルト: 'r'。
• mode <string> | <integer> デフォルト: 0o666 (読み取りおよび書き込み可能)
• callback <Function>
  • err <Error>
  • fd <integer>

非同期ファイルオープン。詳細については、POSIX open(2) のドキュメントを参照してください。

mode は、ファイルが作成された場合にのみ、ファイルのモード（パーミッションとスティッキービット）を設定します。Windows では、書き込み権限のみを操作できます。fs.chmod() を参照してください。

コールバックは 2 つの引数 (err, fd) を受け取ります。

一部の文字 (\< \> : " / \ | ? *) は、ファイル、パス、名前空間の名前付け で説明されているように、Windows で予約されています。NTFS では、ファイル名にコロンが含まれている場合、Node.js は、この MSDN ページ で説明されているように、ファイル システム ストリームを開きます。

fs.open() に基づく関数もこの動作を示します: fs.writeFile()、fs.readFile() など。

fs.openAsBlob(path[, options])

追加: v19.8.0

[Stable: 1 - 実験的]

Stable: 1 安定性: 1 - 実験的

• path <string> | <Buffer> | <URL>

• options <Object>

  • type <string> Blob のオプションの MIME タイプ。

• 戻り値: <Promise> 成功すると<Blob>で解決される。

与えられたファイルによってデータがバックアップされた<Blob>を返します。

<Blob>が作成された後、ファイルを変更してはなりません。 変更すると、<Blob>データの読み取りがDOMExceptionエラーで失敗します。 Blobが作成されたとき、およびファイルデータがディスク上で変更されたかどうかを検出するために各読み取りの前に、ファイルに対する同期 stat 操作が行われます。

ESM

import { openAsBlob } from 'node:fs'

const blob = await openAsBlob('the.file.txt')
const ab = await blob.arrayBuffer()
blob.stream()

CJS

const { openAsBlob } = require('node:fs')

;(async () => {
  const blob = await openAsBlob('the.file.txt')
  const ab = await blob.arrayBuffer()
  blob.stream()
})()

fs.opendir(path[, options], callback)

[履歴]

バージョン	変更点
v20.1.0, v18.17.0	recursiveオプションが追加されました。
v18.0.0	callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v13.1.0, v12.16.0	bufferSizeオプションが導入されました。
v12.12.0	追加: v12.12.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> デフォルト: 'utf8'
  • bufferSize <number> ディレクトリから読み取るときに内部でバッファリングされるディレクトリ エントリの数。 値が大きいほどパフォーマンスは向上しますが、メモリ使用量が増加します。 デフォルト: 32
  • recursive <boolean> デフォルト: false

• callback <Function>

  • err <Error>
  • dir <fs.Dir>

非同期的にディレクトリを開きます。 詳しくは、POSIX opendir(3)ドキュメントをご覧ください。

ディレクトリから読み取りとクリーンアップを行うためのすべての機能を含む<fs.Dir>を作成します。

encodingオプションは、ディレクトリを開くときと後続の読み取り操作中にpathのエンコーディングを設定します。

fs.read(fd, buffer, offset, length, position, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.10.0	buffer パラメーターは、任意の TypedArray または DataView にできるようになりました。
v7.4.0	buffer パラメーターは Uint8Array にできるようになりました。
v6.0.0	length パラメーターは 0 にできるようになりました。
v0.0.2	追加: v0.0.2

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> データが書き込まれるバッファー。
• offset <integer> データを書き込む buffer 内の位置。
• length <integer> 読み込むバイト数。
• position <integer> | <bigint> | <null> ファイル内の読み込みを開始する場所を指定します。position が null または -1 の場合、データは現在のファイル位置から読み込まれ、ファイル位置が更新されます。position が 0 以上の整数の場合、ファイル位置は変更されません。
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

fd で指定されたファイルからデータを読み込みます。

コールバックには、3 つの引数 (err, bytesRead, buffer) が与えられます。

ファイルが同時変更されない場合、読み込まれるバイト数がゼロになると、ファイルの末尾に達します。

このメソッドが util.promisify() されたバージョンとして呼び出された場合、bytesRead および buffer プロパティを持つ Object の Promise を返します。

fs.read() メソッドは、ファイル記述子 (fd) で指定されたファイルからデータを読み込みます。length 引数は、Node.js がカーネルから読み込もうとする最大バイト数を示します。ただし、読み込まれる実際のバイト数 (bytesRead) は、さまざまな理由で指定された length よりも少なくなる可能性があります。

例：

• ファイルが指定された length よりも短い場合、bytesRead は実際に読み込まれたバイト数に設定されます。
• ファイルがバッファーを埋める前に EOF (End of File) に遭遇した場合、Node.js は EOF に遭遇するまですべての利用可能なバイトを読み込み、コールバックの bytesRead パラメーターは実際に読み込まれたバイト数を示し、これは指定された length よりも少なくなる可能性があります。
• ファイルが遅いネットワーク filesystem にある場合、または読み取り中にその他の問題が発生した場合、bytesRead は指定された length よりも少なくなる可能性があります。

したがって、fs.read() を使用する場合は、ファイルから実際に読み込まれたバイト数を判断するために bytesRead 値を確認することが重要です。アプリケーションのロジックに応じて、指定された length よりも bytesRead が少ない場合の処理が必要になる場合があります。たとえば、最小限のバイト数が必要な場合は、読み取り呼び出しをループでラップするなどです。

この動作は、POSIX の preadv2 関数に似ています。

fs.read(fd[, options], callback)

[History]

Version	Changes
v13.11.0, v12.17.0	Options オブジェクトを渡して、buffer、offset、length、および position をオプションにできるようになりました。
v13.11.0, v12.17.0	追加: v13.11.0, v12.17.0

• fd <integer>
• options <Object>
  • buffer <Buffer> | <TypedArray> | <DataView> Default: Buffer.alloc(16384)
  • offset <integer> Default: 0
  • length <integer> Default: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> Default: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

fs.read()関数と同様に、このバージョンではオプションのoptionsオブジェクトを受け取ります。 optionsオブジェクトが指定されていない場合は、上記のデフォルト値が使用されます。

fs.read(fd, buffer[, options], callback)

追加: v18.2.0, v16.17.0

• fd <整数>
• buffer <Buffer> | <TypedArray> | <DataView> データが書き込まれるバッファー。
• options <オブジェクト>
  • offset <整数> デフォルト: 0
  • length <整数> デフォルト: buffer.byteLength - offset
  • position <整数> | <bigint> デフォルト: null
• callback <関数>
  • err <Error>
  • bytesRead <整数>
  • buffer <Buffer>

fs.read() 関数と同様に、このバージョンではオプションの options オブジェクトを受け取ります。options オブジェクトが指定されていない場合、上記のデフォルト値が使用されます。

fs.readdir(path[, options], callback)

[履歴]

バージョン	変更点
v20.1.0, v18.17.0	recursive オプションを追加。
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.10.0	新しいオプション withFileTypes が追加されました。
v10.0.0	callback パラメーターは必須ではなくなりました。渡さないと、ランタイムで TypeError がスローされます。
v7.6.0	path パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v7.0.0	callback パラメーターは必須ではなくなりました。渡さないと、ID DEP0013 の非推奨警告が発行されます。
v6.0.0	options パラメーターが追加されました。
v0.1.8	追加: v0.1.8

• path <文字列> | <Buffer> | <URL>
• options <文字列> | <オブジェクト>
  • encoding <文字列> デフォルト: 'utf8'
  • withFileTypes <ブール値> デフォルト: false
  • recursive <ブール値> true の場合、ディレクトリの内容を再帰的に読み込みます。再帰モードでは、すべてのファイル、サブファイル、およびディレクトリがリストされます。 デフォルト: false
• callback <関数>
  • err <Error>
  • files <文字列[]> | <Buffer[]> | <fs.Dirent[]>

ディレクトリの内容を読み取ります。コールバックは (err, files) の 2 つの引数を受け取ります。files は、ディレクトリ内のファイルの名前の配列であり、'.' および '..' は除外されます。

詳細については、POSIX readdir(3) ドキュメントを参照してください。

オプションの options 引数は、エンコードを指定する文字列、またはコールバックに渡されるファイル名に使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。encoding が 'buffer' に設定されている場合、返されるファイル名は <Buffer> オブジェクトとして渡されます。

options.withFileTypes が true に設定されている場合、files 配列には <fs.Dirent> オブジェクトが含まれます。

fs.readFile(path[, options], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK ではなく ERR_INVALID_ARG_TYPE がスローされるようになりました。
v16.0.0	複数のエラーが返された場合、返されるエラーは AggregateError になる場合があります。
v15.2.0, v14.17.0	options 引数に、進行中の readFile リクエストを中止するための AbortSignal を含めることができます。
v10.0.0	callback パラメーターは必須ではなくなりました。渡さないと、実行時に TypeError がスローされます。
v7.6.0	path パラメーターは、file: プロトコルを使用した WHATWG URL オブジェクトにすることができます。
v7.0.0	callback パラメーターは必須ではなくなりました。渡さないと、ID DEP0013 の非推奨警告が発行されます。
v5.1.0	成功した場合、callback は常に error パラメーターとして null を使用して呼び出されます。
v5.0.0	path パラメーターがファイル記述子になるようになりました。
v0.1.29	v0.1.29 で追加されました

• path <string> | <Buffer> | <URL> | <integer> ファイル名またはファイル記述子

• options <Object> | <string>

  • encoding <string> | <null> 既定値: null
  • flag <string> ファイルシステムの flags のサポート を参照してください。 既定値: 'r'。
  • signal <AbortSignal> 進行中の readFile を中止できます

• callback <Function>

  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

ファイルの全内容を非同期で読み取ります。

import { readFile } from 'node:fs'

readFile('/etc/passwd', (err, data) => {
  if (err) throw err
  console.log(data)
})

コールバックには、data がファイルの内容である 2 つの引数 (err, data) が渡されます。

エンコーディングが指定されていない場合は、生のバッファが返されます。

options が文字列の場合、エンコーディングを指定します。

import { readFile } from 'node:fs'

readFile('/etc/passwd', 'utf8', callback)

パスがディレクトリの場合、fs.readFile() と fs.readFileSync() の動作はプラットフォーム固有です。 macOS、Linux、および Windows では、エラーが返されます。 FreeBSD では、ディレクトリの内容の表現が返されます。

import { readFile } from 'node:fs'

// macOS、Linux、および Windows
readFile('<ディレクトリ>', (err, data) => {
  // => [Error: EISDIR: ディレクトリでの不正な操作、読み取り <ディレクトリ>]
})

// FreeBSD
readFile('<ディレクトリ>', (err, data) => {
  // => null、<データ>
})

AbortSignal を使用して、進行中のリクエストを中止できます。リクエストが中止されると、コールバックは AbortError で呼び出されます。

import { readFile } from 'node:fs'

const controller = new AbortController()
const signal = controller.signal
readFile(fileInfo[0].name, { signal }, (err, buf) => {
  // ...
})
// リクエストを中止する場合
controller.abort()

fs.readFile() 関数はファイル全体をバッファリングします。メモリコストを最小限に抑えるために、可能な場合は fs.createReadStream() を介したストリーミングを優先してください。

進行中のリクエストを中止しても、個々のオペレーティングシステムリクエストは中止されません。そうではなく、fs.readFile が実行する内部バッファリングが中止されます。

ファイル記述子

パフォーマンスに関する考慮事項

fs.readFile() メソッドは、ファイルのコンテンツを一度に 1 つのチャンクずつ非同期的にメモリに読み込み、各チャンク間でイベントループが切り替わるようにします。これにより、読み込み操作が基盤となる libuv スレッドプールを使用している可能性のある他のアクティビティへの影響を少なくできますが、完全なファイルをメモリに読み込むのに時間がかかることを意味します。

追加の読み込みオーバーヘッドは、システムによって大きく異なり、読み込まれるファイルの種類によって異なります。ファイルの種類が通常のファイル（たとえばパイプ）ではなく、Node.js が実際のファイルサイズを特定できない場合、各読み込み操作で 64 KiB のデータがロードされます。通常のファイルの場合、各読み込みで 512 KiB のデータが処理されます。

可能な限り高速なファイルコンテンツの読み込みが必要なアプリケーションの場合は、fs.read() を直接使用し、アプリケーションコードがファイルの内容全体を自分で読み込むように管理する方が良いでしょう。

Node.js GitHub の issue #25741 に、異なる Node.js バージョンでの複数のファイルサイズに対する fs.readFile() のパフォーマンスに関する詳細な分析と、より多くの情報が提供されています。

fs.readlink(path[, options], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.0.0	callback パラメータはオプションではなくなりました。これを渡さないと、実行時に TypeError がスローされます。
v7.6.0	path パラメータには、file: プロトコルを使用する WHATWG URL オブジェクトを使用できます。
v7.0.0	callback パラメータはオプションではなくなりました。これを渡さないと、id DEP0013 の非推奨警告が発行されます。
v0.1.31	v0.1.31 で追加

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'

• callback <Function>

  • err <Error>
  • linkString <string> | <Buffer>

path で参照されるシンボリックリンクの内容を読み取ります。コールバックは 2 つの引数 (err, linkString) を受け取ります。

詳細については、POSIX readlink(2) ドキュメントを参照してください。

オプションの options 引数は、エンコーディングを指定する文字列か、コールバックに渡されるリンクパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。encoding が 'buffer' に設定されている場合、返されるリンクパスは <Buffer> オブジェクトとして渡されます。

fs.readv(fd, buffers[, position], callback)

[履歴]

バージョン	変更
v18.0.0	callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v13.13.0, v12.17.0	追加: v13.13.0, v12.17.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> デフォルト: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffers <ArrayBufferView[]>

fdで指定されたファイルから読み込み、readv()を使用してArrayBufferViewの配列に書き込みます。

positionは、データの読み込みを開始するファイルの先頭からのオフセットです。 typeof position !== 'number'の場合、データは現在の位置から読み込まれます。

コールバックには、err、bytesRead、およびbuffersの 3 つの引数が与えられます。bytesReadは、ファイルから読み取られたバイト数です。

このメソッドがutil.promisify()されたバージョンとして呼び出された場合、bytesReadおよびbuffersプロパティを持つObjectの Promise を返します。

fs.realpath(path[, options], callback)

[履歴]

バージョン	変更
v18.0.0	callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v10.0.0	callbackパラメータはオプションではなくなりました。渡さないと実行時にTypeErrorがスローされます。
v8.0.0	パイプ/ソケットの解決サポートが追加されました。
v7.6.0	pathパラメータは、file:プロトコルを使用する WHATWG URLオブジェクトにすることができます。
v7.0.0	callbackパラメータはオプションではなくなりました。渡さないと、ID DEP0013 の非推奨警告が発生します。
v6.4.0	realpathの呼び出しが Windows 上のさまざまなエッジケースで再び機能するようになりました。
v6.0.0	cacheパラメータが削除されました。
v0.1.31	追加: v0.1.31

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> デフォルト: 'utf8'
• callback <Function>
  • err <Error>
  • resolvedPath <string> | <Buffer>

.、..、シンボリックリンクを解決することにより、正規のパス名を非同期的に計算します。

正規のパス名は必ずしも一意ではありません。ハードリンクとバインドマウントは、多くのパス名を通じてファイルシステムエンティティを公開できます。

この関数はrealpath(3)と同様に動作しますが、いくつかの例外があります。

callbackは 2 つの引数(err, resolvedPath)を取得します。相対パスを解決するためにprocess.cwdを使用する場合があります。

UTF8 文字列に変換できるパスのみがサポートされています。

オプションのoptions引数は、エンコーディングを指定する文字列、またはコールバックに渡されるパスに使用する文字エンコーディングを指定するencodingプロパティを持つオブジェクトにすることができます。encodingが'buffer'に設定されている場合、返されるパスは<Buffer>オブジェクトとして渡されます。

pathがソケットまたはパイプに解決される場合、この関数はそのオブジェクトのシステム依存の名前を返します。

存在しないパスは ENOENT エラーになります。error.pathは絶対ファイルパスです。

fs.realpath.native(path[, options], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v9.2.0	追加: v9.2.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> 既定値: 'utf8'

• callback <Function>

  • err <Error>
  • resolvedPath <string> | <Buffer>

非同期の realpath(3)。

callback は 2 つの引数 (err, resolvedPath) を受け取ります。

UTF8 文字列に変換できるパスのみがサポートされています。

オプションの options 引数は、エンコーディングを指定する文字列、またはコールバックに渡されるパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。 encoding が 'buffer' に設定されている場合、返されるパスは <Buffer> オブジェクトとして渡されます。

Linux では、Node.js が musl libc にリンクされている場合、この関数が機能するためには、procfs ファイルシステムが /proc にマウントされている必要があります。 Glibc にはこの制限はありません。

fs.rename(oldPath, newPath, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.0.0	callback パラメータはオプションではなくなりました。渡さないと、実行時に TypeError がスローされます。
v7.6.0	oldPath および newPath パラメータは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。 現在、サポートはまだ 実験的 です。
v7.0.0	callback パラメータはオプションではなくなりました。渡さないと、ID DEP0013 の非推奨警告が出力されます。
v0.0.2	追加: v0.0.2

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

oldPath にあるファイルの名前を、newPath として提供されたパス名に非同期で変更します。 newPath が既に存在する場合、上書きされます。 newPath にディレクトリがある場合は、代わりにエラーが発生します。完了コールバックには、可能な例外以外の引数は与えられません。

以下も参照してください: rename(2)。

import { rename } from 'node:fs'

rename('oldFile.txt', 'newFile.txt', err => {
  if (err) throw err
  console.log('Rename complete!')
})

fs.rmdir(path[, options], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v16.0.0	ファイルである path に対して fs.rmdir(path, { recursive: true }) を使用することは許可されなくなり、Windows では ENOENT エラー、POSIX では ENOTDIR エラーが発生するようになりました。
v16.0.0	存在しない path に対して fs.rmdir(path, { recursive: true }) を使用することは許可されなくなり、ENOENT エラーが発生するようになりました。
v16.0.0	recursive オプションは非推奨となり、使用すると非推奨警告が発生します。
v14.14.0	recursive オプションは非推奨です。代わりに fs.rm を使用してください。
v13.3.0, v12.16.0	maxBusyTries オプションは maxRetries に名前が変更され、デフォルトは 0 になりました。emfileWait オプションは削除され、EMFILE エラーは他のエラーと同じリトライロジックを使用します。retryDelay オプションがサポートされるようになりました。ENFILE エラーがリトライされるようになりました。
v12.10.0	recursive、maxBusyTries、および emfileWait オプションがサポートされるようになりました。
v10.0.0	callback パラメーターは必須になりました。渡さないと、実行時に TypeError がスローされます。
v7.6.0	path パラメーターは file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v7.0.0	callback パラメーターは必須になりました。渡さないと、ID DEP0013 の非推奨警告が発行されます。
v0.0.2	追加: v0.0.2

• path <string> | <Buffer> | <URL>

• options <Object>

  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、または EPERM エラーが発生した場合、Node.js は各試行で retryDelay ミリ秒ずつ長く線形バックオフ待機で操作を再試行します。このオプションはリトライの回数を表します。recursive オプションが true でない場合、このオプションは無視されます。デフォルト: 0。
  • recursive <boolean> true の場合、再帰的なディレクトリ削除を実行します。再帰モードでは、失敗時に操作が再試行されます。デフォルト: false。非推奨。
  • retryDelay <integer> リトライ間の待機時間（ミリ秒単位）。recursive オプションが true でない場合、このオプションは無視されます。デフォルト: 100。

• callback <Function>

  • err <Error>

非同期の rmdir(2)。完了コールバックには、発生しうる例外以外の引数は渡されません。

ファイル（ディレクトリではない）に対して fs.rmdir() を使用すると、Windows では ENOENT エラー、POSIX では ENOTDIR エラーが発生します。

rm -rf Unix コマンドと同様の動作を得るには、fs.rm() を { recursive: true, force: true } オプション付きで使用してください。

fs.rm(path[, options], callback)

[履歴]

バージョン	変更
v17.3.0, v16.14.0	path パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v14.14.0	追加: v14.14.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • force <boolean> trueの場合、pathが存在しない場合、例外は無視されます。 デフォルト: false。
  • maxRetries <integer> EBUSY, EMFILE, ENFILE, ENOTEMPTY, または EPERM エラーが発生した場合、Node.js は各試行でretryDelayミリ秒長い線形バックオフ待機で操作を再試行します。このオプションは再試行回数を表します。このオプションは、recursiveオプションがtrueでない場合は無視されます。 デフォルト: 0。
  • recursive <boolean> trueの場合、再帰的な削除を実行します。再帰モードでは、失敗した場合に操作が再試行されます。 デフォルト: false。
  • retryDelay <integer> 再試行間の待機時間（ミリ秒単位）。このオプションは、recursiveオプションがtrueでない場合は無視されます。 デフォルト: 100。

• callback <Function>

  • err <Error>

ファイルとディレクトリを非同期で削除します（標準の POSIX rmユーティリティをモデルにしています）。完了コールバックには、例外が発生する可能性を除き、引数は渡されません。

fs.stat(path[, options], callback)

[履歴]

バージョン	変更
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.5.0	返される数値が bigint であるかどうかを指定する追加の options オブジェクトを受け入れるようになりました。
v10.0.0	callback パラメータはオプションではなくなりました。渡さないと、実行時に TypeError がスローされます。
v7.6.0	path パラメータは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v7.0.0	callback パラメータはオプションではなくなりました。渡さないと、ID DEP0013 の非推奨警告が発せられます。
v0.0.2	v0.0.2 で追加されました。

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるかどうか。デフォルト: false。

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

非同期 stat(2)。コールバックは 2 つの引数 (err, stats) を受け取ります。stats は <fs.Stats> オブジェクトです。

エラーが発生した場合、err.code は 一般的なシステムエラー のいずれかになります。

fs.stat() はシンボリックリンクに従います。リンク自体を見るには、fs.lstat() を使用します。

fs.open()、fs.readFile()、または fs.writeFile() を呼び出す前に、ファイルの存在を確認するために fs.stat() を使用することは推奨されません。代わりに、ユーザーコードはファイルを直接開く/読み取る/書き込む必要があり、ファイルが利用できない場合は発生したエラーを処理する必要があります。

その後操作することなくファイルが存在するかどうかを確認するには、fs.access() が推奨されます。

たとえば、次のディレクトリ構造を考えてみましょう。

- txtDir
-- file.txt
- app.js

次のプログラムは、指定されたパスの統計情報をチェックします。

import { stat } from 'node:fs'

const pathsToCheck = ['./txtDir', './txtDir/file.txt']

for (let i = 0; i < pathsToCheck.length; i++) {
  stat(pathsToCheck[i], (err, stats) => {
    console.log(stats.isDirectory())
    console.log(stats)
  })
}

結果の出力は次のようになります。

true
Stats {
  dev: 16777220,
  mode: 16877,
  nlink: 3,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214262,
  size: 96,
  blocks: 0,
  atimeMs: 1561174653071.963,
  mtimeMs: 1561174614583.3518,
  ctimeMs: 1561174626623.5366,
  birthtimeMs: 1561174126937.2893,
  atime: 2019-06-22T03:37:33.072Z,
  mtime: 2019-06-22T03:36:54.583Z,
  ctime: 2019-06-22T03:37:06.624Z,
  birthtime: 2019-06-22T03:28:46.937Z
}
false
Stats {
  dev: 16777220,
  mode: 33188,
  nlink: 1,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214074,
  size: 8,
  blocks: 8,
  atimeMs: 1561174616618.8555,
  mtimeMs: 1561174614584,
  ctimeMs: 1561174614583.8145,
  birthtimeMs: 1561174007710.7478,
  atime: 2019-06-22T03:36:56.619Z,
  mtime: 2019-06-22T03:36:54.584Z,
  ctime: 2019-06-22T03:36:54.584Z,
  birthtime: 2019-06-22T03:26:47.711Z
}

fs.statfs(path[, options], callback)

追加: v19.6.0, v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> 返される<fs.StatFs>オブジェクトの数値がbigintであるかどうか。デフォルト: false。

• callback <Function>

  • err <Error>
  • stats <fs.StatFs>

非同期のstatfs(2)。pathを含むマウントされたファイルシステムに関する情報を返します。コールバックは 2 つの引数(err, stats)を受け取り、statsは<fs.StatFs>オブジェクトです。

エラーの場合、err.codeは共通システムエラーのいずれかになります。

fs.symlink(target, path[, type], callback)

[履歴]

バージョン	変更点
v18.0.0	callback引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKの代わりにERR_INVALID_ARG_TYPEがスローされるようになりました。
v12.0.0	type引数が未定義のままの場合、Node はtargetの型を自動検出し、自動的にdirまたはfileを選択します。
v7.6.0	targetおよびpathパラメータは、file:プロトコルを使用した WHATWG URLオブジェクトを使用できます。サポートは現在も実験的です。
v0.1.31	追加: v0.1.31

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> デフォルト: null
• callback <Function>
  • err <Error>

targetを指すpathというリンクを作成します。完了コールバックには、例外の可能性を除き、引数は渡されません。

詳細については、POSIX symlink(2)のドキュメントを参照してください。

type引数は Windows でのみ使用可能で、他のプラットフォームでは無視されます。 'dir'、'file'、または'junction'に設定できます。type引数がnullの場合、Node.js はtargetの型を自動検出し、'file'または'dir'を使用します。targetが存在しない場合は、'file'が使用されます。Windows のジャンクションポイントは、宛先パスが絶対パスである必要があります。'junction'を使用すると、target引数は自動的に絶対パスに正規化されます。NTFS ボリュームのジャンクションポイントは、ディレクトリのみを指すことができます。

相対ターゲットは、リンクの親ディレクトリからの相対パスです。

import { symlink } from 'node:fs'

symlink('./mew', './mewtwo', callback)

上記の例では、同じディレクトリ内のmewを指すシンボリックリンクmewtwoを作成します。

$ tree .
.
├── mew
└── mewtwo -> ./mew

fs.truncate(path[, len], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v16.0.0	複数のエラーが返された場合、返されるエラーは AggregateError になる場合があります。
v10.0.0	callback パラメーターはオプションではなくなりました。これを渡さないと、実行時に TypeError がスローされます。
v7.0.0	callback パラメーターはオプションではなくなりました。これを渡さないと、ID DEP0013 の非推奨警告が発行されます。
v0.8.6	v0.8.6 で追加

• path <string> | <Buffer> | <URL>
• len <integer> デフォルト: 0
• callback <Function>
  • err <Error> | <AggregateError>

ファイルを切り詰めます。完了コールバックには、起こりうる例外以外の引数は渡されません。ファイル記述子を最初の引数として渡すこともできます。この場合、fs.ftruncate() が呼び出されます。

ESM

import { truncate } from 'node:fs'
// 'path/file.txt' が通常のファイルであると仮定します。
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt was truncated')
})

CJS

const { truncate } = require('node:fs')
// 'path/file.txt' が通常のファイルであると仮定します。
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt was truncated')
})

ファイル記述子を渡すことは非推奨であり、将来的にエラーがスローされる可能性があります。

詳細については、POSIX truncate(2) ドキュメントを参照してください。

fs.unlink(path, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v10.0.0	callback パラメータは必須ではなくなりました。これを渡さないと、実行時に TypeError がスローされます。
v7.6.0	path パラメータは、file: プロトコルを使用する WHATWG URL オブジェクトにできます。
v7.0.0	callback パラメータは必須ではなくなりました。これを渡さないと、id DEP0013 の非推奨警告が発行されます。
v0.0.2	v0.0.2 で追加。

• path <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

ファイルまたはシンボリックリンクを非同期的に削除します。完了コールバックには、可能性のある例外以外の引数は渡されません。

import { unlink } from 'node:fs'
// 'path/file.txt' が通常のファイルであると仮定します。
unlink('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt が削除されました')
})

fs.unlink() はディレクトリ（空であるかどうかに関わらず）では機能しません。ディレクトリを削除するには、fs.rmdir()を使用してください。

詳細については、POSIX の unlink(2) ドキュメントを参照してください。

fs.unwatchFile(filename[, listener])

追加: v0.1.31

• filename <string> | <Buffer> | <URL>
• listener <Function> オプション、以前に fs.watchFile() を使用してアタッチされたリスナー。

filename の変更の監視を停止します。listener が指定されている場合は、その特定のリスナーのみが削除されます。それ以外の場合は、すべて のリスナーが削除され、filename の監視が事実上停止します。

監視されていないファイル名で fs.unwatchFile() を呼び出すことは、エラーではなく、何も起こりません。

fs.watch() を使用する方が、fs.watchFile() や fs.unwatchFile() よりも効率的です。可能な場合は、fs.watchFile() や fs.unwatchFile() の代わりに fs.watch() を使用する必要があります。

fs.utimes(path, atime, mtime, callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v10.0.0	callback パラメーターはオプションではなくなりました。渡さないと実行時に TypeError がスローされます。
v8.0.0	NaN、Infinity、および -Infinity は有効な時間指定子ではなくなりました。
v7.6.0	path パラメーターは file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v7.0.0	callback パラメーターはオプションではなくなりました。渡さないと、id DEP0013 の非推奨警告が発行されます。
v4.1.0	数値文字列、NaN、および Infinity が時間指定子として許可されるようになりました。
v0.4.2	追加: v0.4.2

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

path によって参照されるオブジェクトのファイルシステムのタイムスタンプを変更します。

atime および mtime 引数は、以下の規則に従います。

• 値は、Unix エポック時間を秒単位で表す数値、Date、または '123456789.0' のような数値文字列のいずれかになります。
• 値を数値に変換できない場合、または NaN、Infinity、または -Infinity の場合は、Error がスローされます。

fs.watch(filename[, options][, listener])

[History]

Version	Changes
v19.1.0	Linux、AIX、IBMi での再帰的なサポートが追加されました。
v15.9.0, v14.17.0	AbortSignal でウォッチャーを閉じるサポートが追加されました。
v7.6.0	filename パラメータは file: プロトコルを使用する WHATWG URL オブジェクトにできます。
v7.0.0	渡された options オブジェクトが変更されることはありません。
v0.5.10	v0.5.10 で追加されました。

• filename <string> | <Buffer> | <URL>

• options <string> | <Object>

  • persistent <boolean> ファイルが監視されている限り、プロセスが実行を継続するかどうかを示します。デフォルト: true。
  • recursive <boolean> すべてのサブディレクトリを監視するか、現在のディレクトリのみを監視するかを示します。これはディレクトリが指定されている場合に適用され、サポートされているプラットフォームでのみ適用されます（注意点を参照）。デフォルト: false。
  • encoding <string> リスナーに渡されるファイル名に使用する文字エンコーディングを指定します。デフォルト: 'utf8'。
  • signal <AbortSignal> AbortSignal でウォッチャーを閉じることを許可します。

• listener <Function> | <undefined> デフォルト: undefined

  • eventType <string>
  • filename <string> | <Buffer> | <null>

• 戻り値: <fs.FSWatcher>

filename（ファイルまたはディレクトリ）の変更を監視します。

2 番目の引数はオプションです。options が文字列として提供されている場合、それは encoding を指定します。それ以外の場合、options はオブジェクトとして渡す必要があります。

リスナーコールバックは 2 つの引数 (eventType, filename) を受け取ります。eventType は 'rename' または 'change' のいずれかで、filename はイベントをトリガーしたファイルの名前です。

ほとんどのプラットフォームでは、ファイル名がディレクトリに表示または消滅するたびに 'rename' が発行されます。

リスナーコールバックは、<fs.FSWatcher> によって発行される 'change' イベントにアタッチされますが、eventType の 'change' 値と同じものではありません。

signal が渡された場合、対応する AbortController を中止すると、返された <fs.FSWatcher> が閉じられます。

注意点

fs.watch API はプラットフォーム間で 100%一貫しているわけではなく、一部の状況では利用できません。

Windows では、監視対象のディレクトリが移動または名前変更された場合、イベントは発行されません。監視対象のディレクトリが削除されると、EPERMエラーが報告されます。

利用可能性

この機能は、ファイルシステムの変更を通知する方法を提供する基盤となるオペレーティングシステムに依存します。

• Linux システムでは、inotify(7)を使用します。
• BSD システムでは、kqueue(2)を使用します。
• macOS では、ファイルにはkqueue(2)を使用し、ディレクトリにはFSEventsを使用します。
• SunOS システム（Solaris および SmartOS を含む）では、event portsを使用します。
• Windows システムでは、この機能はReadDirectoryChangesWに依存します。
• AIX システムでは、この機能はAHAFSに依存しており、有効にする必要があります。
• IBM i システムでは、この機能はサポートされていません。

何らかの理由で基盤となる機能が利用できない場合、fs.watch()は機能せず、例外をスローする可能性があります。たとえば、ネットワークファイルシステム（NFS、SMB など）や、Vagrant や Docker などの仮想化ソフトウェアを使用している場合のホストファイルシステムでは、ファイルまたはディレクトリの監視が信頼できない場合や、不可能になる場合があります。

fs.watchFile()を使用することもできます。これは stat ポーリングを使用しますが、この方法は遅く、信頼性が低くなります。

Inode

Linux および macOS システムでは、fs.watch()はパスをinodeに解決し、inode を監視します。監視対象のパスが削除されて再作成された場合、新しい inode が割り当てられます。監視は削除のイベントを発行しますが、元のinode を監視し続けます。新しい inode のイベントは発行されません。これは予期される動作です。

AIX ファイルは、ファイルの存続期間中、同じ inode を保持します。AIX で監視対象のファイルを保存して閉じると、2 つの通知（新しいコンテンツの追加の 1 つと、切り捨ての 1 つ）が発生します。

Filename 引数

コールバックで filename 引数を提供することは、Linux、macOS、Windows、および AIX でのみサポートされています。サポートされているプラットフォームでも、filename が常に提供されるとは限りません。したがって、コールバックで filename 引数が常に提供されると仮定しないでください。null の場合のフォールバックロジックを用意してください。

import { watch } from 'node:fs'
watch('somedir', (eventType, filename) => {
  console.log(`event type is: ${eventType}`)
  if (filename) {
    console.log(`filename provided: ${filename}`)
  } else {
    console.log('filename not provided')
  }
})

fs.watchFile(filename[, options], listener)

[履歴]

バージョン	変更
v10.5.0	bigint オプションがサポートされるようになりました。
v7.6.0	filename パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v0.1.31	v0.1.31 で追加

• filename <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> デフォルト: false
  • persistent <boolean> デフォルト: true
  • interval <integer> デフォルト: 5007
• listener <Function>
  • current <fs.Stats>
  • previous <fs.Stats>
• 戻り値: <fs.StatWatcher>

filename の変更を監視します。コールバック listener は、ファイルがアクセスされるたびに呼び出されます。

options 引数は省略できます。指定する場合はオブジェクトである必要があります。options オブジェクトには、ファイルが監視されている限りプロセスを実行し続けるかどうかを示すブール値 persistent を含めることができます。options オブジェクトは、ターゲットをポーリングする頻度をミリ秒単位で示す interval プロパティを指定できます。

listener は、現在の stat オブジェクトと前の stat オブジェクトの 2 つの引数を受け取ります。

import { watchFile } from 'node:fs'

watchFile('message.text', (curr, prev) => {
  console.log(`the current mtime is: ${curr.mtime}`)
  console.log(`the previous mtime was: ${prev.mtime}`)
})

これらの stat オブジェクトは fs.Stat のインスタンスです。bigint オプションが true の場合、これらのオブジェクトの数値は BigInt として指定されます。

ファイルがアクセスされただけでなく、変更されたときに通知を受けるには、curr.mtimeMs と prev.mtimeMs を比較する必要があります。

fs.watchFile 操作の結果が ENOENT エラーになる場合、リスナーは 1 回だけ呼び出され、すべてのフィールドがゼロ（または日付の場合は Unix エポック）になります。その後ファイルが作成されると、リスナーは最新の stat オブジェクトで再度呼び出されます。これは v0.10 以降の機能の変更です。

fs.watch() を使用する方が、fs.watchFile および fs.unwatchFile より効率的です。可能な場合は、fs.watchFile および fs.unwatchFile の代わりに fs.watch を使用する必要があります。

fs.watchFile() で監視されているファイルが消えて再び表示されると、2 番目のコールバックイベント（ファイルの再表示）の previous の内容は、最初のコールバックイベント（ファイルの消失）の previous の内容と同じになります。

これは次の場合に発生します。

• ファイルが削除され、その後復元される場合
• ファイルの名前が変更され、その後元の名前に再度名前が変更される場合

fs.write(fd, buffer, offset[, length[, position]], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v14.0.0	buffer パラメータは、サポートされていない入力を文字列に強制変換しなくなりました。
v10.10.0	buffer パラメータは、任意の TypedArray または DataView にできるようになりました。
v10.0.0	callback パラメータはオプションではなくなりました。渡さないと、実行時に TypeError がスローされます。
v7.4.0	buffer パラメータは、Uint8Array にできるようになりました。
v7.2.0	offset および length パラメータはオプションになりました。
v7.0.0	callback パラメータはオプションではなくなりました。渡さないと、id DEP0013 の非推奨警告が出力されます。
v0.0.2	v0.0.2 で追加されました。

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> 既定値: 0
• length <integer> 既定値: buffer.byteLength - offset
• position <integer> | <null> 既定値: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

buffer を fd で指定されたファイルに書き込みます。

offset は書き込むバッファの一部を決定し、length は書き込むバイト数を指定する整数です。

position は、このデータを書き込むファイルの先頭からのオフセットを指します。 typeof position !== 'number' の場合、データは現在の位置に書き込まれます。pwrite(2) を参照してください。

コールバックには、3 つの引数 (err, bytesWritten, buffer) が与えられます。ここで bytesWritten は、buffer から書き込まれた バイト数 を指定します。

このメソッドが util.promisify() 化されたバージョンとして呼び出された場合、bytesWritten と buffer プロパティを持つ Object の Promise を返します。

コールバックを待たずに、同じファイルで fs.write() を複数回使用するのは安全ではありません。このシナリオでは、fs.createWriteStream() が推奨されます。

Linux では、ファイルが追加モードで開かれている場合、位置指定書き込みは機能しません。カーネルは position 引数を無視し、常にファイルの最後にデータを追加します。

fs.write(fd, buffer[, options], callback)

追加: v18.3.0, v16.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> デフォルト: 0
  • length <integer> デフォルト: buffer.byteLength - offset
  • position <integer> デフォルト: null

• callback <Function>

  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <TypedArray> | <DataView>

buffer を fd で指定されたファイルに書き込みます。

上記の fs.write 関数と同様に、このバージョンではオプションの options オブジェクトを受け取ります。 options オブジェクトが指定されていない場合、上記のデフォルト値が使用されます。

fs.write(fd, string[, position[, encoding]], callback)

[履歴]

バージョン	変更点
v19.0.0	独自の toString 関数を持つオブジェクトを string パラメータに渡すことはサポートされなくなりました。
v17.8.0	独自の toString 関数を持つオブジェクトを string パラメータに渡すことは非推奨となりました。
v14.12.0	string パラメータは、明示的な toString 関数を持つオブジェクトを文字列化します。
v14.0.0	string パラメータは、サポートされていない入力を文字列に強制変換しなくなりました。
v10.0.0	callback パラメータはオプションではなくなりました。これを渡さないと、実行時に TypeError がスローされます。
v7.2.0	position パラメータがオプションになりました。
v7.0.0	callback パラメータはオプションではなくなりました。これを渡さないと、ID DEP0013 の非推奨警告が発行されます。
v0.11.5	追加: v0.11.5

• fd <integer>
• string <string>
• position <integer> | <null> デフォルト: null
• encoding <string> デフォルト: 'utf8'
• callback <Function>
  • err <Error>
  • written <integer>
  • string <string>

string を fd で指定されたファイルに書き込みます。 string が文字列でない場合は、例外がスローされます。

position は、このデータを書き込む必要のあるファイルの先頭からのオフセットを指します。 typeof position !== 'number' の場合、データは現在の位置に書き込まれます。 pwrite(2) を参照してください。

encoding は、予期される文字列エンコーディングです。

コールバックは引数 (err, written, string) を受け取ります。 written は、渡された文字列の書き込みに必要な バイト 数を指定します。 書き込まれたバイト数は、書き込まれた文字列の文字数と必ずしも同じではありません。 Buffer.byteLength を参照してください。

コールバックを待たずに、同じファイルに対して fs.write() を複数回使用するのは安全ではありません。 このシナリオでは、fs.createWriteStream() を推奨します。

Linux では、ファイルが追記モードで開かれている場合、位置指定書き込みは機能しません。 カーネルは位置引数を無視し、常にデータの末尾に追加します。

Windows では、ファイル記述子がコンソール（例： fd == 1 または stdout）に接続されている場合、使用されているエンコーディングに関係なく、非 ASCII 文字を含む文字列はデフォルトでは正しくレンダリングされません。 chcp 65001 コマンドでアクティブなコードページを変更することにより、コンソールが UTF-8 を正しくレンダリングするように構成することができます。 詳細については、chcp ドキュメントを参照してください。

fs.writeFile(file, data[, options], callback)

[履歴]

バージョン	変更点
v21.0.0, v20.10.0	flushオプションがサポートされるようになりました。
v19.0.0	独自のtoString関数を持つオブジェクトをstringパラメータに渡すことはサポートされなくなりました。
v18.0.0	無効なコールバックをcallback引数に渡すと、ERR_INVALID_CALLBACKではなくERR_INVALID_ARG_TYPEがスローされるようになりました。
v17.8.0	独自のtoString関数を持つオブジェクトをstringパラメータに渡すことは非推奨になりました。
v16.0.0	複数のエラーが返された場合、返されるエラーはAggregateErrorになる可能性があります。
v15.2.0, v14.17.0	オプション引数に、進行中の writeFile リクエストを中断するための AbortSignal を含めることができるようになりました。
v14.12.0	dataパラメータは、明示的なtoString関数を持つオブジェクトを文字列化します。
v14.0.0	dataパラメータは、サポートされていない入力を文字列に強制変換しなくなりました。
v10.10.0	dataパラメータは、任意のTypedArrayまたはDataViewにすることができるようになりました。
v10.0.0	callbackパラメータは必須になりました。渡さないと、実行時にTypeErrorがスローされます。
v7.4.0	dataパラメータはUint8Arrayにすることができるようになりました。
v7.0.0	callbackパラメータは必須ではなくなりました。渡さないと、ID DEP0013 の非推奨警告が発行されます。
v5.0.0	fileパラメータはファイル記述子にすることができるようになりました。
v0.1.29	v0.1.29 で追加されました。

• file <string> | <Buffer> | <URL> | <integer> ファイル名またはファイル記述子
• data <string> | <Buffer> | <TypedArray> | <DataView>
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <integer> デフォルト: 0o666
  • flag <string> ファイルシステムのflagsのサポートを参照してください。 デフォルト: 'w'。
  • flush <boolean> すべてのデータがファイルに正常に書き込まれ、flushがtrueの場合、fs.fsync()を使用してデータをフラッシュします。デフォルト: false。
  • signal <AbortSignal> 進行中の writeFile を中止できるようにします。
• callback <Function>
  • err <Error> | <AggregateError>

fileがファイル名の場合、データをファイルに非同期的に書き込み、ファイルがすでに存在する場合は上書きします。dataは文字列またはバッファにすることができます。

fileがファイル記述子の場合、動作はfs.write()を直接呼び出すのと似ています（推奨）。ファイル記述子の使用に関する以下の注記を参照してください。

dataがバッファの場合、encodingオプションは無視されます。

modeオプションは、新しく作成されたファイルにのみ影響します。詳細については、fs.open()を参照してください。

import { writeFile } from 'node:fs'
import { Buffer } from 'node:buffer'

const data = new Uint8Array(Buffer.from('Hello Node.js'))
writeFile('message.txt', data, err => {
  if (err) throw err
  console.log('The file has been saved!')
})

optionsが文字列の場合、エンコーディングを指定します。

import { writeFile } from 'node:fs'

writeFile('message.txt', 'Hello Node.js', 'utf8', callback)

コールバックを待たずに同じファイルに対してfs.writeFile()を複数回使用するのは安全ではありません。このシナリオでは、fs.createWriteStream()が推奨されます。

fs.readFileと同様に、fs.writeFileは、渡されたバッファを書き込むために内部で複数のwrite呼び出しを実行する便利なメソッドです。パフォーマンスが重要なコードについては、fs.createWriteStream()の使用を検討してください。

<AbortSignal>を使用してfs.writeFile()をキャンセルできます。キャンセルは「ベストエフォート」であり、ある程度のデータは書き込まれる可能性があります。

import { writeFile } from 'node:fs'
import { Buffer } from 'node:buffer'

const controller = new AbortController()
const { signal } = controller
const data = new Uint8Array(Buffer.from('Hello Node.js'))
writeFile('message.txt', data, { signal }, err => {
  // リクエストが中止された場合、コールバックはAbortErrorで呼び出されます
})
// リクエストを中止する必要がある場合
controller.abort()

進行中のリクエストを中止しても、個々のオペレーティングシステムのリクエストが中止されるわけではなく、fs.writeFileが実行する内部バッファリングが中止されます。

ファイル記述子を使用した fs.writeFile()

file がファイル記述子の場合、その動作は fs.write() を直接呼び出す場合とほぼ同じです。以下のように記述できます。

import { write } from 'node:fs'
import { Buffer } from 'node:buffer'

write(fd, Buffer.from(data, options.encoding), callback)

fs.write() を直接呼び出す場合との違いは、いくつかの特殊な状況下で、fs.write() がバッファの一部だけを書き込み、残りのデータを書き込むために再試行する必要があるのに対し、fs.writeFile() はデータが完全に書き込まれる（またはエラーが発生する）まで再試行することです。

この影響は、混乱の一般的な原因となっています。ファイル記述子の場合、ファイルは置き換えられません！データは必ずしもファイルの先頭に書き込まれるわけではなく、ファイルの元のデータは、新しく書き込まれたデータの前後、または両方に残る可能性があります。

例えば、fs.writeFile() を連続して 2 回呼び出し、最初に文字列 'Hello' を書き込み、次に文字列 ', World' を書き込んだ場合、ファイルには 'Hello, World' が含まれ、元のファイルデータの一部が含まれている可能性があります（元のファイルのサイズと、ファイル記述子の位置に依存します）。ファイル記述子の代わりにファイル名が使用された場合、ファイルには ', World' のみ含まれることが保証されます。

fs.writev(fd, buffers[, position], callback)

[履歴]

バージョン	変更点
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v12.9.0	v12.9.0 で追加されました。

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> 既定値: null
• callback <Function>
  • err <Error>
  • bytesWritten <integer>
  • buffers <ArrayBufferView[]>

writev() を使用して、ArrayBufferView の配列を fd で指定されたファイルに書き込みます。

position は、このデータを書き込むファイルの先頭からのオフセットです。typeof position !== 'number' の場合、データは現在の位置に書き込まれます。

コールバックには、3 つの引数 err、bytesWritten、および buffers が与えられます。bytesWritten は、buffers から書き込まれたバイト数です。

このメソッドが util.promisify() されると、bytesWritten プロパティと buffers プロパティを持つ Object の Promise を返します。

コールバックを待たずに同じファイルに対して fs.writev() を複数回使用するのは安全ではありません。このシナリオでは、fs.createWriteStream() を使用してください。

Linux では、ファイルが追加モードで開かれている場合、位置指定書き込みは機能しません。カーネルは position 引数を無視し、常にファイルの末尾にデータを追加します。

同期 API

同期 API は、すべての操作を同期的に実行し、操作が完了または失敗するまでイベントループをブロックします。

fs.accessSync(path[, mode])

[履歴]

バージョン	変更点
v7.6.0	path パラメータは file: プロトコルを使用する WHATWG URL オブジェクトにできます。
v0.11.15	v0.11.15 で追加

• path <string> | <Buffer> | <URL>
• mode <integer> デフォルト: fs.constants.F_OK

path で指定されたファイルまたはディレクトリに対するユーザーの権限を同期的にテストします。mode 引数は、実行するアクセシビリティチェックを指定するオプションの整数です。mode は、値 fs.constants.F_OK または fs.constants.R_OK、fs.constants.W_OK、および fs.constants.X_OK のいずれかのビット単位の OR で構成されるマスクである必要があります（例：fs.constants.W_OK | fs.constants.R_OK）。 mode の可能な値については、ファイルアクセス定数を確認してください。

いずれかのアクセシビリティチェックが失敗した場合、Error がスローされます。それ以外の場合、メソッドは undefined を返します。

import { accessSync, constants } from 'node:fs'

try {
  accessSync('etc/passwd', constants.R_OK | constants.W_OK)
  console.log('can read/write')
} catch (err) {
  console.error('no access!')
}

fs.appendFileSync(path, data[, options])

[履歴]

バージョン	変更点
v21.1.0, v20.10.0	flush オプションがサポートされるようになりました。
v7.0.0	渡された options オブジェクトは変更されなくなります。
v5.0.0	file パラメータはファイル記述子にできます。
v0.6.7	v0.6.7 で追加

• path <string> | <Buffer> | <URL> | <number> ファイル名またはファイル記述子
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <integer> デフォルト: 0o666
  • flag <string> ファイルシステム フラグ のサポート を参照してください。デフォルト: 'a'。
  • flush <boolean> true の場合、基になるファイル記述子は、閉じる前にフラッシュされます。 デフォルト: false。

ファイルにデータを同期的に追加し、まだ存在しない場合はファイルを作成します。 data は文字列または<Buffer>にできます。

mode オプションは、新しく作成されたファイルにのみ影響します。詳細については、fs.open()を参照してください。

import { appendFileSync } from 'node:fs'

try {
  appendFileSync('message.txt', 'data to append')
  console.log('The "data to append" was appended to file!')
} catch (err) {
  /* エラーを処理 */
}

options が文字列の場合、エンコーディングを指定します。

import { appendFileSync } from 'node:fs'

appendFileSync('message.txt', 'data to append', 'utf8')

path は、追加用に開かれた数値ファイル記述子（fs.open() または fs.openSync() を使用）として指定できます。ファイル記述子は自動的に閉じられません。

import { openSync, closeSync, appendFileSync } from 'node:fs'

let fd

try {
  fd = openSync('message.txt', 'a')
  appendFileSync(fd, 'data to append', 'utf8')
} catch (err) {
  /* エラーを処理 */
} finally {
  if (fd !== undefined) closeSync(fd)
}

fs.chmodSync(path, mode)

[履歴]

バージョン	変更
v7.6.0	path パラメータは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v0.6.7	追加: v0.6.7

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>

詳細については、この API の非同期バージョンのドキュメントを参照してください: fs.chmod()。

詳細については、POSIX chmod(2) ドキュメントを参照してください。

fs.chownSync(path, uid, gid)

[履歴]

バージョン	変更
v7.6.0	path パラメータは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v0.1.97	追加: v0.1.97

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

ファイル所有者とグループを同期的に変更します。undefined を返します。これは、fs.chown() の同期バージョンです。

詳細については、POSIX chown(2) ドキュメントを参照してください。

fs.closeSync(fd)

追加: v0.1.21

• fd <integer>

ファイル記述子を閉じます。undefined を返します。

他の fs 操作で現在使用中のファイル記述子 (fd) に対して fs.closeSync() を呼び出すと、未定義の動作につながる可能性があります。

詳細については、POSIX close(2) ドキュメントを参照してください。

fs.copyFileSync(src, dest[, mode])

[履歴]

バージョン	変更
v14.0.0	flags 引数を mode に変更し、より厳密な型検証を課しました。
v8.5.0	v8.5.0 で追加されました。

• src <string> | <Buffer> | <URL> コピー元のファイル名
• dest <string> | <Buffer> | <URL> コピー先のファイル名
• mode <integer> コピー操作の修飾子。デフォルト: 0。

src を dest に同期的にコピーします。 デフォルトでは、dest がすでに存在する場合、上書きされます。 undefined を返します。 Node.js は、コピー操作の原子性については保証しません。 書き込みのためにコピー先のファイルを開いた後にエラーが発生した場合、Node.js はコピー先を削除しようとします。

mode は、コピー操作の動作を指定するオプションの整数です。 2 つ以上の値のビット単位の OR で構成されるマスクを作成できます（例：fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE）。

• fs.constants.COPYFILE_EXCL: dest が既に存在する場合、コピー操作は失敗します。
• fs.constants.COPYFILE_FICLONE: コピー操作は、コピーオンライトのリファレンスを作成しようとします。プラットフォームがコピーオンライトをサポートしていない場合、フォールバックコピーメカニズムが使用されます。
• fs.constants.COPYFILE_FICLONE_FORCE: コピー操作は、コピーオンライトのリファレンスを作成しようとします。プラットフォームがコピーオンライトをサポートしていない場合、操作は失敗します。

import { copyFileSync, constants } from 'node:fs'

// destination.txt はデフォルトで作成または上書きされます。
copyFileSync('source.txt', 'destination.txt')
console.log('source.txt が destination.txt にコピーされました')

// COPYFILE_EXCL を使用すると、destination.txt が存在する場合、操作は失敗します。
copyFileSync('source.txt', 'destination.txt', constants.COPYFILE_EXCL)

fs.cpSync(src, dest[, options])

[履歴]

バージョン	変更
v22.3.0	この API は実験的ではなくなりました。
v20.1.0, v18.17.0	fs.copyFile() の mode 引数としてコピーの動作を指定する追加の mode オプションを受け入れるようになりました。
v17.6.0, v16.15.0	シンボリックリンクのパス解決を実行するかどうかを指定する追加の verbatimSymlinks オプションを受け入れるようになりました。
v16.7.0	追加: v16.7.0

• src <string> | <URL> コピー元のパス。

• dest <string> | <URL> コピー先のパス。

• options <Object>

  • dereference <boolean> シンボリックリンクを非参照化します。デフォルト: false。

  • errorOnExist <boolean> force が false で、コピー先にファイルまたはディレクトリが存在する場合、エラーをスローします。デフォルト: false。

  • filter <Function> コピーするファイル/ディレクトリをフィルターする関数。アイテムをコピーする場合は true、無視する場合は false を返します。ディレクトリを無視すると、そのすべての内容もスキップされます。デフォルト: undefined

  • src <string> コピー元のパス。

  • dest <string> コピー先のパス。

  • 戻り値: <boolean> boolean に強制できる Promise 以外の値。

  • force <boolean> 既存のファイルまたはディレクトリを上書きします。これが false に設定され、コピー先が存在する場合、コピー操作はエラーを無視します。この動作を変更するには、errorOnExist オプションを使用してください。デフォルト: true。

  • mode <integer> コピー操作の修飾子。デフォルト: 0。fs.copyFileSync() の mode フラグを参照してください。

  • preserveTimestamps <boolean> true の場合、src のタイムスタンプが保持されます。デフォルト: false。

  • recursive <boolean> ディレクトリを再帰的にコピーします。デフォルト: false

  • verbatimSymlinks <boolean> true の場合、シンボリックリンクのパス解決はスキップされます。デフォルト: false

サブディレクトリとファイルを含む、ディレクトリ構造全体を src から dest に同期的にコピーします。

ディレクトリを別のディレクトリにコピーする場合、グロブはサポートされておらず、動作は cp dir1/ dir2/ と同様です。

fs.existsSync(path)

[履歴]

バージョン	変更点
v7.6.0	path パラメーターは file: プロトコルを使用する WHATWG URL オブジェクトを指定できます。
v0.1.21	v0.1.21 で追加されました。

• path <string> | <Buffer> | <URL>
• 戻り値: <boolean>

パスが存在する場合は true、そうでない場合は false を返します。

詳細については、この API の非同期バージョンのドキュメント fs.exists() を参照してください。

fs.exists() は非推奨ですが、fs.existsSync() は非推奨ではありません。fs.exists() の callback パラメーターは、他の Node.js のコールバックと矛盾するパラメーターを受け入れます。fs.existsSync() はコールバックを使用しません。

import { existsSync } from 'node:fs'

if (existsSync('/etc/passwd')) console.log('The path exists.')

fs.fchmodSync(fd, mode)

追加: v0.4.7

• fd <integer>
• mode <string> | <integer>

ファイルのアクセス許可を設定します。undefined を返します。

詳細については、POSIX の fchmod(2) ドキュメントを参照してください。

fs.fchownSync(fd, uid, gid)

追加: v0.4.7

• fd <integer>
• uid <integer> ファイルの新しい所有者のユーザー ID。
• gid <integer> ファイルの新しいグループのグループ ID。

ファイルの所有者を設定します。undefined を返します。

詳細については、POSIX の fchown(2) ドキュメントを参照してください。

fs.fdatasyncSync(fd)

追加: v0.1.96

• fd <integer>

ファイルに関連付けられた現在キューに入っているすべての I/O 操作を、オペレーティングシステムの同期された I/O 完了状態に強制します。詳細については、POSIX のfdatasync(2)ドキュメントを参照してください。undefinedを返します。

fs.fstatSync(fd[, options])

[履歴]

バージョン	変更
v10.5.0	返される数値が bigint であるかどうかを指定するために、追加の options オブジェクトを受け入れるようになりました。
v0.1.95	追加: v0.1.95

• fd <integer>

• options <Object>

  • bigint <boolean> 返される<fs.Stats>オブジェクトの数値がbigintであるべきかどうか。デフォルト: false。

• 戻り値: <fs.Stats>

ファイル記述子の<fs.Stats>を取得します。

詳細については、POSIX のfstat(2)ドキュメントを参照してください。

fs.fsyncSync(fd)

追加: v0.1.96

• fd <integer>

オープンされたファイル記述子のすべてのデータがストレージデバイスにフラッシュされることを要求します。具体的な実装は、オペレーティングシステムとデバイスに固有です。詳細については、POSIX のfsync(2)ドキュメントを参照してください。undefinedを返します。

fs.ftruncateSync(fd[, len])

追加: v0.8.6

• fd <integer>
• len <integer> デフォルト: 0

ファイル記述子を切り捨てます。undefinedを返します。

詳細については、この API の非同期バージョンのドキュメントを参照してください。fs.ftruncate()。

fs.futimesSync(fd, atime, mtime)

[履歴]

バージョン	変更点
v4.1.0	数値の文字列、NaN、および Infinity が時間指定子として許可されるようになりました。
v0.4.2	追加: v0.4.2

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

fs.futimes() の同期バージョン。undefined を返します。

fs.globSync(pattern[, options])

[履歴]

バージョン	変更点
v22.2.0	withFileTypes をオプションとしてサポート。
v22.0.0	追加: v22.0.0

[安定版: 1 - 実験的]

安定版: 1 安定度: 1 - 実験的

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> 現在の作業ディレクトリ。デフォルト: process.cwd()
  • exclude <Function> ファイル/ディレクトリを除外するための関数。項目を除外する場合は true を、含める場合は false を返します。デフォルト: undefined。
  • withFileTypes <boolean> グロブがパスを Dirent として返す場合は true、そうでない場合は false。デフォルト: false。

• 戻り値: <string[]> パターンに一致するファイルのパス。

ESM

import { globSync } from 'node:fs'

console.log(globSync('**/*.js'))

CJS

const { globSync } = require('node:fs')

console.log(globSync('**/*.js'))

fs.lchmodSync(path, mode)

非推奨: v0.4.7 以降

• path <string> | <Buffer> | <URL>
• mode <integer>

シンボリックリンクの権限を変更します。undefined を返します。

このメソッドは macOS でのみ実装されています。

詳細については、POSIX の lchmod(2) ドキュメントを参照してください。

fs.lchownSync(path, uid, gid)

[履歴]

バージョン	変更
v10.6.0	この API は非推奨ではなくなりました。
v0.4.7	ドキュメントのみの非推奨。

• path <string> | <Buffer> | <URL>
• uid <integer> ファイルの新しい所有者のユーザー ID。
• gid <integer> ファイルの新しいグループのグループ ID。

パスの所有者を設定します。undefined を返します。

詳細については、POSIX の lchown(2) ドキュメントを参照してください。

fs.lutimesSync(path, atime, mtime)

追加: v14.5.0, v12.19.0

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

path で参照されるシンボリックリンクのファイルシステムのタイムスタンプを変更します。undefined を返します。または、パラメータが不正な場合や操作が失敗した場合は例外をスローします。これは fs.lutimes() の同期バージョンです。

fs.linkSync(existingPath, newPath)

[履歴]

バージョン	変更点
v7.6.0	existingPath および newPath パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにできます。サポートは現在も 実験的 です。
v0.1.31	追加: v0.1.31

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

existingPath から newPath への新しいリンクを作成します。詳細については、POSIX の link(2) ドキュメントを参照してください。undefined を返します。

fs.lstatSync(path[, options])

[履歴]

バージョン	変更点
v15.3.0, v14.17.0	エントリーが存在しない場合に例外をスローするかどうかを指定する throwIfNoEntry オプションを受け入れるようになりました。
v10.5.0	返される数値が bigint であるかどうかを指定するための追加の options オブジェクトを受け入れるようになりました。
v7.6.0	path パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにできます。
v0.1.30	追加: v0.1.30

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> 返される <fs.Stats> オブジェクトの数値が bigint であるかどうか。デフォルト: false。
  • throwIfNoEntry <boolean> ファイルシステムのエントリが存在しない場合に undefined を返すのではなく例外がスローされるかどうか。デフォルト: true。

• 戻り値: <fs.Stats>

path によって参照されるシンボリックリンクの <fs.Stats> を取得します。

詳細については、POSIX の lstat(2) ドキュメントを参照してください。

fs.mkdirSync(path[, options])

[履歴]

バージョン	変更点
v13.11.0, v12.17.0	recursive モードで、最初に作成されたパスが返されるようになりました。
v10.12.0	2 番目の引数に recursive および mode プロパティを持つ options オブジェクトを使用できるようになりました。
v7.6.0	path パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v0.1.21	追加: v0.1.21

• path <string> | <Buffer> | <URL>

• options <Object> | <integer>

  • recursive <boolean> デフォルト: false
  • mode <string> | <integer> Windows ではサポートされていません。 デフォルト: 0o777。

• 戻り値: <string> | <undefined>

ディレクトリを同期的に作成します。undefined を返します。または、recursive が true の場合は、最初に作成されたディレクトリパスを返します。これは fs.mkdir() の同期バージョンです。

詳細については、POSIX mkdir(2) のドキュメントを参照してください。

fs.mkdtempSync(prefix[, options])

[履歴]

バージョン	変更点
v20.6.0, v18.19.0	prefix パラメーターがバッファーと URL を受け入れるようになりました。
v16.5.0, v14.18.0	prefix パラメーターが空の文字列を受け入れるようになりました。
v5.10.0	追加: v5.10.0

• prefix <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'

• 戻り値: <string>

作成されたディレクトリパスを返します。

詳細については、この API の非同期バージョンのドキュメント fs.mkdtemp() を参照してください。

オプションの options 引数は、エンコーディングを指定する文字列、または使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトにすることができます。

fs.opendirSync(path[, options])

[履歴]

バージョン	変更点
v20.1.0, v18.17.0	recursive オプションが追加されました。
v13.1.0, v12.16.0	bufferSize オプションが導入されました。
v12.12.0	v12.12.0 で追加されました。

• path <string> | <Buffer> | <URL>

• options <Object>

  • encoding <string> | <null> デフォルト: 'utf8'
  • bufferSize <number> ディレクトリから読み取る際に内部でバッファリングされるディレクトリエントリの数。値を大きくするとパフォーマンスが向上しますが、メモリ使用量も増加します。デフォルト: 32
  • recursive <boolean> デフォルト: false

• 戻り値: <fs.Dir>

ディレクトリを同期的に開きます。opendir(3) を参照してください。

<fs.Dir> を作成します。これには、ディレクトリからの読み取りとクリーンアップのためのすべての追加関数が含まれています。

encoding オプションは、ディレクトリを開くときと後続の読み取り操作で path のエンコーディングを設定します。

fs.openSync(path[, flags[, mode]])

[履歴]

バージョン	変更点
v11.1.0	flags 引数がオプションになり、デフォルトは 'r' になりました。
v9.9.0	as および as+ フラグがサポートされるようになりました。
v7.6.0	path パラメーターは file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v0.1.21	v0.1.21 で追加されました。

• path <string> | <Buffer> | <URL>
• flags <string> | <number> デフォルト: 'r'。ファイルシステム flags のサポート を参照してください。
• mode <string> | <integer> デフォルト: 0o666
• 戻り値: <number>

ファイル記述子を表す整数を返します。

詳細については、この API の非同期バージョンのドキュメント fs.open() を参照してください。

fs.readdirSync(path[, options])

[履歴]

バージョン	変更点
v20.1.0, v18.17.0	recursive オプションが追加されました。
v10.10.0	新しいオプション withFileTypes が追加されました。
v7.6.0	path パラメーターは file: プロトコルを使用する WHATWG URL オブジェクトにできます。
v0.1.21	追加: v0.1.21

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'
  • withFileTypes <boolean> デフォルト: false
  • recursive <boolean> true の場合、ディレクトリの内容を再帰的に読み込みます。再帰モードでは、すべてのファイル、サブファイル、およびディレクトリが一覧表示されます。 デフォルト: false。

• 戻り値: <string[]> | <Buffer[]> | <fs.Dirent[]>

ディレクトリの内容を読み取ります。

詳細については、POSIX の readdir(3) ドキュメントを参照してください。

オプションの options 引数には、エンコーディングを指定する文字列、または返されるファイル名に使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。 encoding が 'buffer' に設定されている場合、返されるファイル名は <Buffer> オブジェクトとして渡されます。

options.withFileTypes が true に設定されている場合、結果には <fs.Dirent> オブジェクトが含まれます。

fs.readFileSync(path[, options])

[History]

バージョン	変更点
v7.6.0	path パラメータは file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v5.0.0	path パラメータはファイル記述子にできるようになりました。
v0.1.8	追加: v0.1.8

• path <string> | <Buffer> | <URL> | <integer> ファイル名またはファイル記述子

• options <Object> | <string>

  • encoding <string> | <null> デフォルト: null
  • flag <string> ファイルシステムの flags のサポート を参照してください。 デフォルト: 'r'。

• 戻り値: <string> | <Buffer>

path の内容を返します。

詳細については、この API の非同期バージョンのドキュメント fs.readFile() を参照してください。

encoding オプションが指定されている場合、この関数は文字列を返します。それ以外の場合は、バッファを返します。

fs.readFile() と同様に、パスがディレクトリの場合、fs.readFileSync() の動作はプラットフォーム固有です。

import { readFileSync } from 'node:fs'

// macOS、Linux、および Windows
readFileSync('<directory>')
// => [Error: EISDIR: ディレクトリに対する不正な操作、読み取り <directory>]

//  FreeBSD
readFileSync('<directory>') // => <data>

fs.readlinkSync(path[, options])

[履歴]

バージョン	変更点
v7.6.0	path パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにできます。
v0.1.31	追加: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'

• 戻り値: <string> | <Buffer>

シンボリックリンクの文字列値を返します。

詳細については、POSIX readlink(2) のドキュメントを参照してください。

オプションの options 引数には、エンコーディングを指定する文字列、または返されるリンクパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。encoding が 'buffer' に設定されている場合、返されるリンクパスは <Buffer> オブジェクトとして渡されます。

fs.readSync(fd, buffer, offset, length[, position])

[履歴]

バージョン	変更点
v10.10.0	buffer パラメーターは、任意の TypedArray または DataView にできるようになりました。
v6.0.0	length パラメーターは 0 にできるようになりました。
v0.1.21	追加: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer>
• length <integer>
• position <integer> | <bigint> | <null> デフォルト: null
• 戻り値: <number>

bytesRead の数を返します。

詳細については、この API の非同期バージョンのドキュメントfs.read()を参照してください。

fs.readSync(fd, buffer[, options])

[履歴]

バージョン	変更点
v13.13.0, v12.17.0	オプションオブジェクトを渡して、offset、length、および position をオプションにできます。
v13.13.0, v12.17.0	追加: v13.13.0, v12.17.0

• fd <integer>

• buffer <Buffer> | <TypedArray> | <DataView>

• options <Object>

  • offset <integer> デフォルト: 0
  • length <integer> デフォルト: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> デフォルト: null

• 戻り値: <number>

bytesRead の数を返します。

上記の fs.readSync 関数と同様に、このバージョンはオプションの options オブジェクトを受け取ります。 options オブジェクトが指定されていない場合は、上記のデフォルト値が使用されます。

詳細については、この API の非同期バージョンのドキュメント fs.read() を参照してください。

fs.readvSync(fd, buffers[, position])

追加: v13.13.0, v12.17.0

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> デフォルト: null
• 戻り値: <number> 読み取られたバイト数。

詳細については、この API の非同期バージョンのドキュメント fs.readv() を参照してください。

fs.realpathSync(path[, options])

[履歴]

バージョン	変更
v8.0.0	パイプ/ソケットの解決のサポートが追加されました。
v7.6.0	path パラメーターは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v6.4.0	realpathSync の呼び出しは、Windows 上のさまざまなエッジケースで再び動作するようになりました。
v6.0.0	cache パラメーターが削除されました。
v0.1.31	追加: v0.1.31

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'

• 戻り値: <string> | <Buffer>

解決されたパス名を返します。

詳細については、この API の非同期バージョンのドキュメントを参照してください: fs.realpath()。

fs.realpathSync.native(path[, options])

追加: v9.2.0

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> デフォルト: 'utf8'

• 戻り値: <string> | <Buffer>

同期的な realpath(3)。

UTF8 文字列に変換できるパスのみがサポートされています。

オプションの options 引数には、エンコーディングを指定する文字列、または返されるパスに使用する文字エンコーディングを指定する encoding プロパティを持つオブジェクトを指定できます。encoding が 'buffer' に設定されている場合、返されるパスは <Buffer> オブジェクトとして渡されます。

Linux では、Node.js が musl libc にリンクされている場合、この関数が動作するためには、procfs ファイルシステムが /proc にマウントされている必要があります。Glibc にはこの制限はありません。

fs.renameSync(oldPath, newPath)

[履歴]

バージョン	変更点
v7.6.0	oldPathとnewPathのパラメータは、file:プロトコルを使用する WHATWG URLオブジェクトにすることができます。現在、サポートはまだ実験的です。
v0.1.21	追加: v0.1.21

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

oldPathからnewPathへファイルの名前を変更します。undefinedを返します。

詳細については、POSIX のrename(2)ドキュメントを参照してください。

fs.rmdirSync(path[, options])

[履歴]

バージョン	変更点
v16.0.0	ファイルであるpathに対してfs.rmdirSync(path, { recursive: true })を使用することは許可されなくなり、Windows ではENOENTエラー、POSIX ではENOTDIRエラーが発生します。
v16.0.0	存在しないpathに対してfs.rmdirSync(path, { recursive: true })を使用することは許可されなくなり、ENOENTエラーが発生します。
v16.0.0	recursiveオプションは非推奨であり、使用すると非推奨警告がトリガーされます。
v14.14.0	recursiveオプションは非推奨です。代わりにfs.rmSyncを使用してください。
v13.3.0, v12.16.0	maxBusyTriesオプションの名前がmaxRetriesに変更され、デフォルトは 0 になりました。emfileWaitオプションは削除され、EMFILEエラーは他のエラーと同じ再試行ロジックを使用します。retryDelayオプションがサポートされるようになりました。ENFILEエラーは再試行されるようになりました。
v12.10.0	recursive、maxBusyTries、およびemfileWaitオプションがサポートされるようになりました。
v7.6.0	pathパラメータは、file:プロトコルを使用する WHATWG URLオブジェクトにすることができます。
v0.1.21	追加: v0.1.21

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、またはEPERMエラーが発生した場合、Node.js は試行ごとにretryDelayミリ秒長い線形バックオフ待機で操作を再試行します。このオプションは、再試行回数を表します。このオプションは、recursiveオプションがtrueでない場合は無視されます。デフォルト: 0。
  • recursive <boolean> trueの場合、再帰的なディレクトリ削除を実行します。再帰モードでは、操作は失敗時に再試行されます。デフォルト: false。非推奨。
  • retryDelay <integer> 再試行間の待機時間（ミリ秒単位）。このオプションは、recursiveオプションがtrueでない場合は無視されます。デフォルト: 100。

同期的なrmdir(2)。undefinedを返します。

（ディレクトリではなく）ファイルに対してfs.rmdirSync()を使用すると、Windows ではENOENTエラーが発生し、POSIX ではENOTDIRエラーが発生します。

rm -rf Unix コマンドと同様の動作を得るには、オプション{ recursive: true, force: true }を指定してfs.rmSync()を使用します。

fs.rmSync(path[, options])

[履歴]

バージョン	変更点
v17.3.0, v16.14.0	path パラメータは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v14.14.0	v14.14.0 で追加されました。

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <boolean> true の場合、path が存在しない場合、例外は無視されます。デフォルト: false。
  • maxRetries <integer> EBUSY、EMFILE、ENFILE、ENOTEMPTY、または EPERM エラーが発生した場合、Node.js は、試行ごとに retryDelay ミリ秒長い線形バックオフ待機で操作を再試行します。このオプションは再試行回数を表します。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 0。
  • recursive <boolean> true の場合、再帰的なディレクトリ削除を実行します。再帰モードでは、操作は失敗時に再試行されます。デフォルト: false。
  • retryDelay <integer> 再試行間の待機時間（ミリ秒単位）。このオプションは、recursive オプションが true でない場合は無視されます。デフォルト: 100。

ファイルとディレクトリを同期的に削除します（標準の POSIX rm ユーティリティをモデル化）。undefined を返します。

fs.statSync(path[, options])

[履歴]

バージョン	変更点
v15.3.0, v14.17.0	エントリが存在しない場合に例外をスローするかどうかを指定する throwIfNoEntry オプションを受け入れます。
v10.5.0	返される数値が bigint であるかどうかを指定するための追加の options オブジェクトを受け入れます。
v7.6.0	path パラメータは、file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v0.1.21	v0.1.21 で追加されました。

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> 返される <fs.Stats> オブジェクト内の数値が bigint であるかどうか。デフォルト: false。
  • throwIfNoEntry <boolean> ファイルシステムエントリが存在しない場合に、undefined を返すのではなく例外がスローされるかどうか。デフォルト: true。

• 返り値: <fs.Stats>

パスの <fs.Stats> を取得します。

fs.statfsSync(path[, options])

Added in: v19.6.0, v18.15.0

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> 返される<fs.StatFs>オブジェクトの数値がbigintであるかどうか。デフォルト: false。

• 戻り値: <fs.StatFs>

同期的なstatfs(2)。pathを含むマウントされたファイルシステムに関する情報を返します。

エラーが発生した場合、err.codeは一般的なシステムエラーのいずれかになります。

fs.symlinkSync(target, path[, type])

[履歴]

バージョン	変更点
v12.0.0	type引数が未定義の場合、Node はtargetの型を自動検出し、自動的にdirまたはfileを選択します。
v7.6.0	targetおよびpathパラメーターは、file:プロトコルを使用した WHATWG URLオブジェクトにすることができます。このサポートは現在実験的です。
v0.1.31	Added in: v0.1.31

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> デフォルト: null

undefinedを返します。

詳細については、この API の非同期バージョンのドキュメントを参照してください: fs.symlink()。

fs.truncateSync(path[, len])

追加: v0.8.6

• path <string> | <Buffer> | <URL>
• len <integer> デフォルト: 0

ファイルを切り詰めます。undefined を返します。ファイルディスクリプターを最初の引数として渡すこともできます。この場合、fs.ftruncateSync() が呼び出されます。

ファイルディスクリプターを渡すことは非推奨であり、将来的にエラーがスローされる可能性があります。

fs.unlinkSync(path)

[履歴]

バージョン	変更
v7.6.0	path パラメーターは file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v0.1.21	追加: v0.1.21

• path <string> | <Buffer> | <URL>

同期的な unlink(2) です。undefined を返します。

fs.utimesSync(path, atime, mtime)

[履歴]

バージョン	変更
v8.0.0	NaN、Infinity、-Infinity は有効な時間指定子ではなくなりました。
v7.6.0	path パラメーターは file: プロトコルを使用する WHATWG URL オブジェクトにすることができます。
v4.1.0	数値文字列、NaN、および Infinity が時間指定子として許可されるようになりました。
v0.4.2	追加: v0.4.2

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

undefined を返します。

詳細については、この API の非同期バージョンのドキュメントを参照してください: fs.utimes()。

fs.writeFileSync(file, data[, options])

[履歴]

バージョン	変更点
v21.0.0, v20.10.0	flushオプションがサポートされるようになりました。
v19.0.0	dataパラメーターに独自のtoString関数を持つオブジェクトを渡すことは、もはやサポートされていません。
v17.8.0	dataパラメーターに独自のtoString関数を持つオブジェクトを渡すことは、非推奨になりました。
v14.12.0	dataパラメーターは、明示的なtoString関数を持つオブジェクトを文字列化します。
v14.0.0	dataパラメーターは、サポートされていない入力を文字列に強制変換しなくなりました。
v10.10.0	dataパラメーターは、任意のTypedArrayまたはDataViewを使用できるようになりました。
v7.4.0	dataパラメーターは、Uint8Arrayを使用できるようになりました。
v5.0.0	fileパラメーターは、ファイルディスクリプターを使用できるようになりました。
v0.1.29	v0.1.29 で追加されました。

• file <string> | <Buffer> | <URL> | <integer> ファイル名またはファイルディスクリプター
• data <string> | <Buffer> | <TypedArray> | <DataView>
• options <Object> | <string>
  • encoding <string> | <null> デフォルト: 'utf8'
  • mode <integer> デフォルト: 0o666
  • flag <string> ファイルシステムflagのサポートを参照してください。 デフォルト: 'w'。
  • flush <boolean> すべてのデータがファイルに正常に書き込まれ、flushがtrueの場合、fs.fsyncSync()がデータフラッシュに使用されます。

undefinedを返します。

modeオプションは、新規作成されたファイルにのみ影響します。詳細については、fs.open()を参照してください。

詳細については、この API の非同期バージョンのドキュメントを参照してください：fs.writeFile()。

fs.writeSync(fd, buffer, offset[, length[, position]])

[履歴]

バージョン	変更点
v14.0.0	buffer パラメーターは、サポートされていない入力を文字列に強制変換しなくなりました。
v10.10.0	buffer パラメーターは、任意の TypedArray または DataView を指定できるようになりました。
v7.4.0	buffer パラメーターは Uint8Array を指定できるようになりました。
v7.2.0	offset および length パラメーターがオプションになりました。
v0.1.21	追加: v0.1.21

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> デフォルト: 0
• length <integer> デフォルト: buffer.byteLength - offset
• position <integer> | <null> デフォルト: null
• 戻り値: <number> 書き込まれたバイト数。

詳細については、この API の非同期バージョンのドキュメント: fs.write(fd, buffer...) を参照してください。

fs.writeSync(fd, buffer[, options])

追加: v18.3.0, v16.17.0

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView>
• options <Object>
  • offset <integer> デフォルト: 0
  • length <integer> デフォルト: buffer.byteLength - offset
  • position <integer> デフォルト: null
• 戻り値: <number> 書き込まれたバイト数。

詳細については、この API の非同期バージョンのドキュメント: fs.write(fd, buffer...) を参照してください。

fs.writeSync(fd, string[, position[, encoding]])

[履歴]

バージョン	変更点
v14.0.0	string パラメーターは、サポートされていない入力を文字列に強制変換しなくなりました。
v7.2.0	position パラメーターがオプションになりました。
v0.11.5	追加: v0.11.5

• fd <整数>
• string <文字列>
• position <整数> | <null> デフォルト: null
• encoding <文字列> デフォルト: 'utf8'
• 戻り値: <数値> 書き込まれたバイト数。

詳細については、この API の非同期バージョンのドキュメント fs.write(fd, string...) を参照してください。

fs.writevSync(fd, buffers[, position])

追加: v12.9.0

• fd <整数>
• buffers <ArrayBufferView[]>
• position <整数> | <null> デフォルト: null
• 戻り値: <数値> 書き込まれたバイト数。

詳細については、この API の非同期バージョンのドキュメント fs.writev() を参照してください。

共通オブジェクト

共通オブジェクトは、すべてのファイルシステム API バリアント（promise、コールバック、および同期）で共有されます。

クラス: fs.Dir

追加: v12.12.0

ディレクトリ ストリームを表すクラス。

fs.opendir()、fs.opendirSync()、または fsPromises.opendir() によって作成されます。

import { opendir } from 'node:fs/promises'

try {
  const dir = await opendir('./')
  for await (const dirent of dir) console.log(dirent.name)
} catch (err) {
  console.error(err)
}

async iterator を使用すると、<fs.Dir> オブジェクトはイテレータが終了した後、自動的に閉じられます。

dir.close()

追加: v12.12.0

• 戻り値: <Promise>

ディレクトリの基になるリソース ハンドルを非同期的に閉じます。後続の読み取りはエラーになります。

リソースが閉じられた後、履行される Promise が返されます。

dir.close(callback)

[履歴]

バージョン	変更
v18.0.0	callback 引数に無効なコールバックを渡すと、ERR_INVALID_CALLBACK の代わりに ERR_INVALID_ARG_TYPE がスローされるようになりました。
v12.12.0	追加: v12.12.0

• callback <Function>
  • err <Error>

ディレクトリの基になるリソース ハンドルを非同期的に閉じます。後続の読み取りはエラーになります。

リソース ハンドルが閉じられた後、callback が呼び出されます。

dir.closeSync()

追加: v12.12.0

ディレクトリの基になるリソース ハンドルを同期的に閉じます。後続の読み取りはエラーになります。

dir.path

追加: v12.12.0

• <string>

fs.opendir()、fs.opendirSync()、または fsPromises.opendir() に提供された、このディレクトリの読み取り専用パス。

dir.read()

追加: v12.12.0

• 戻り値: <Promise> <fs.Dirent> | <null> で解決される

readdir(3) を介して、次のディレクトリ エントリを非同期に読み込み、<fs.Dirent> として返します。

<fs.Dirent> で解決される Promise が返されます。読み取るディレクトリ エントリが他にない場合は、null が返されます。

この関数によって返されるディレクトリ エントリは、オペレーティング システムの基盤となるディレクトリ メカニズムによって提供されるため、特定の順序には並んでいません。ディレクトリの反復処理中に追加または削除されたエントリは、反復処理の結果に含まれない場合があります。

dir.read(callback)

追加: v12.12.0

• callback <Function>
  • err <Error>
  • dirent <fs.Dirent> | <null>

readdir(3) を介して、次のディレクトリ エントリを非同期に読み込み、<fs.Dirent> として返します。

読み込みが完了すると、callback が <fs.Dirent> で呼び出されます。読み取るディレクトリ エントリが他にない場合は、null が渡されます。

この関数によって返されるディレクトリ エントリは、オペレーティング システムの基盤となるディレクトリ メカニズムによって提供されるため、特定の順序には並んでいません。ディレクトリの反復処理中に追加または削除されたエントリは、反復処理の結果に含まれない場合があります。

dir.readSync()

追加: v12.12.0

• 戻り値: <fs.Dirent> | <null>

次のディレクトリ エントリを同期的に <fs.Dirent> として読み込みます。詳細については、POSIX readdir(3) のドキュメントを参照してください。

読み取るディレクトリ エントリが他にない場合は、null が返されます。

この関数によって返されるディレクトリ エントリは、オペレーティング システムの基盤となるディレクトリ メカニズムによって提供されるため、特定の順序には並んでいません。ディレクトリの反復処理中に追加または削除されたエントリは、反復処理の結果に含まれない場合があります。

dir[Symbol.asyncIterator]()

追加: v12.12.0

• 戻り値: <AsyncIterator> <fs.Dirent> の AsyncIterator

すべてのエントリが読み込まれるまで、ディレクトリを非同期的に反復処理します。詳細については、POSIX の readdir(3) ドキュメントを参照してください。

非同期イテレーターによって返されるエントリは、常に <fs.Dirent> です。dir.read() の null の場合は内部で処理されます。

例については、<fs.Dir> を参照してください。

このイテレーターによって返されるディレクトリ エントリは、オペレーティング システムの基盤となるディレクトリ メカニズムによって提供されるため、特定の順序ではありません。ディレクトリの反復処理中にエントリが追加または削除された場合、反復処理の結果に含まれない場合があります。

クラス: fs.Dirent

追加: v10.10.0

<fs.Dir> からの読み取りによって返される、ディレクトリ内のファイルまたはサブディレクトリであるディレクトリ エントリの表現。ディレクトリ エントリは、ファイル名とファイル タイプのペアの組み合わせです。

さらに、withFileTypes オプションを true に設定して fs.readdir() または fs.readdirSync() が呼び出されると、結果の配列は文字列または <Buffer> ではなく、<fs.Dirent> オブジェクトで満たされます。

dirent.isBlockDevice()

追加: v10.10.0

• 戻り値: <boolean>

<fs.Dirent> オブジェクトがブロック デバイスを記述している場合は true を返します。

dirent.isCharacterDevice()

追加: v10.10.0

• 戻り値: <boolean>

<fs.Dirent> オブジェクトが文字デバイスを記述している場合は true を返します。

dirent.isDirectory()

追加: v10.10.0

• 戻り値: <boolean>

<fs.Dirent> オブジェクトがファイルシステムのディレクトリを表す場合に true を返します。

dirent.isFIFO()

追加: v10.10.0

• 戻り値: <boolean>

<fs.Dirent> オブジェクトが先入れ先出し (FIFO) パイプを表す場合に true を返します。

dirent.isFile()

追加: v10.10.0

• 戻り値: <boolean>

<fs.Dirent> オブジェクトが通常のファイルを表す場合に true を返します。

dirent.isSocket()

追加: v10.10.0

• 戻り値: <boolean>

<fs.Dirent> オブジェクトがソケットを表す場合に true を返します。

dirent.isSymbolicLink()

追加: v10.10.0

• 戻り値: <boolean>

<fs.Dirent> オブジェクトがシンボリックリンクを表す場合に true を返します。

dirent.name

追加: v10.10.0

• <string> | <Buffer>

この<fs.Dirent>オブジェクトが参照するファイル名です。この値の型は、fs.readdir() または fs.readdirSync() に渡される options.encoding によって決定されます。

dirent.parentPath

追加: v21.4.0, v20.12.0, v18.20.0

[安定版: 1 - 実験的]

安定版: 1 安定性: 1 - 実験的

• <string>

この<fs.Dirent>オブジェクトが参照するファイルの親ディレクトリへのパスです。

dirent.path

[履歴]

バージョン	変更点
v23.2.0	このプロパティは読み取り専用ではなくなりました。
v23.0.0	このプロパティにアクセスすると警告が発生します。現在、読み取り専用です。
v21.5.0, v20.12.0, v18.20.0	非推奨: v21.5.0, v20.12.0, v18.20.0 以降
v20.1.0, v18.17.0	追加: v20.1.0, v18.17.0

[安定版: 0 - 非推奨]

安定版: 0 安定度: 0 - 非推奨: 代わりにdirent.parentPathを使用してください。

• <string>

dirent.parentPath のエイリアスです。

クラス: fs.FSWatcher

追加: v0.5.8

• <EventEmitter> を拡張

fs.watch() メソッドの呼び出しが成功すると、新しい<fs.FSWatcher>オブジェクトが返されます。

すべての<fs.FSWatcher>オブジェクトは、監視対象の特定のファイルが変更されるたびに 'change' イベントを発生させます。

イベント: 'change'

追加: v0.5.8

• eventType <string> 発生した変更イベントのタイプ
• filename <string> | <Buffer> 変更されたファイル名（関連/利用可能な場合）

監視対象のディレクトリまたはファイルで何らかの変更があったときに発生します。詳細については、fs.watch()を参照してください。

filename 引数は、オペレーティングシステムのサポートに応じて提供されない場合があります。 filename が提供される場合、fs.watch() が encoding オプションを 'buffer' に設定して呼び出された場合、<Buffer>として提供されます。それ以外の場合、filename は UTF-8 文字列になります。

import { watch } from 'node:fs'
// fs.watch()リスナーで処理される場合の例
watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename)
    // 出力: <Buffer ...>
  }
})

イベント: 'close'

追加: v10.0.0

ウォッチャーが変更の監視を停止したときに発生します。クローズされた<fs.FSWatcher>オブジェクトは、イベントハンドラー内では使用できなくなります。

イベント: 'error'

追加: v0.5.8

• error <Error>

ファイルの監視中にエラーが発生したときに発生します。エラーが発生した<fs.FSWatcher>オブジェクトは、イベントハンドラー内では使用できなくなります。

watcher.close()

追加: v0.5.8

指定された<fs.FSWatcher>での変更の監視を停止します。停止すると、<fs.FSWatcher>オブジェクトは使用できなくなります。

watcher.ref()

追加: v14.3.0, v12.20.0

• 戻り値: <fs.FSWatcher>

呼び出されると、<fs.FSWatcher>がアクティブである限り、Node.js イベントループが終了しないように要求します。watcher.ref()を複数回呼び出しても効果はありません。

デフォルトでは、すべての<fs.FSWatcher>オブジェクトは"ref'ed"になっているため、通常、watcher.unref()が以前に呼び出されていない限り、watcher.ref()を呼び出す必要はありません。

watcher.unref()

追加: v14.3.0, v12.20.0

• 戻り値: <fs.FSWatcher>

呼び出されると、アクティブな<fs.FSWatcher>オブジェクトは、Node.js イベントループがアクティブであり続けることを要求しません。イベントループを実行し続ける他のアクティビティがない場合、<fs.FSWatcher>オブジェクトのコールバックが呼び出される前にプロセスが終了する可能性があります。watcher.unref()を複数回呼び出しても効果はありません。

クラス: fs.StatWatcher

追加: v14.3.0, v12.20.0

• <EventEmitter>を拡張

fs.watchFile()メソッドの呼び出しが成功すると、新しい<fs.StatWatcher>オブジェクトが返されます。

watcher.ref()

追加: v14.3.0, v12.20.0

• 戻り値: <fs.StatWatcher>

呼び出されると、<fs.StatWatcher>がアクティブである限り、Node.js イベントループが終了しないように要求します。watcher.ref()を複数回呼び出しても効果はありません。

デフォルトでは、すべての<fs.StatWatcher>オブジェクトは"ref'ed"になっているため、通常、watcher.unref()が以前に呼び出されていない限り、watcher.ref()を呼び出す必要はありません。

watcher.unref()

追加: v14.3.0, v12.20.0

• 戻り値: <fs.StatWatcher>

呼び出されると、アクティブな<fs.StatWatcher>オブジェクトは、Node.js イベントループがアクティブな状態を維持することを要求しません。イベントループを稼働させる他のアクティビティがない場合、<fs.StatWatcher>オブジェクトのコールバックが呼び出される前にプロセスが終了する可能性があります。watcher.unref()を複数回呼び出しても効果はありません。

クラス: fs.ReadStream

追加: v0.1.93

• 拡張: <stream.Readable>

<fs.ReadStream>のインスタンスは、fs.createReadStream()関数を使用して作成および返されます。

イベント: 'close'

追加: v0.1.93

<fs.ReadStream>の基になるファイル記述子が閉じられたときに発生します。

イベント: 'open'

追加: v0.1.93

• fd <integer> <fs.ReadStream>で使用される整数のファイル記述子。

<fs.ReadStream>のファイル記述子が開かれたときに発生します。

イベント: 'ready'

追加: v9.11.0

<fs.ReadStream>が使用可能になったときに発生します。

'open'の直後に発生します。

readStream.bytesRead

追加: v6.4.0

• <number>

これまでに読み込まれたバイト数。

readStream.path

追加: v0.1.93

• <string> | <Buffer>

fs.createReadStream()の最初の引数で指定された、ストリームが読み込んでいるファイルのパス。pathが文字列として渡された場合、readStream.pathは文字列になります。pathが<Buffer>として渡された場合、readStream.pathは<Buffer>になります。fdが指定されている場合、readStream.pathはundefinedになります。

readStream.pending

追加: v11.2.0, v10.16.0

• <boolean>

このプロパティは、基になるファイルがまだ開かれていない場合、つまり、'ready' イベントが発行される前は true です。

クラス: fs.Stats

[履歴]

バージョン	変更点
v22.0.0, v20.13.0	パブリックコンストラクターは非推奨になりました。
v8.1.0	時間が数値として追加されました。
v0.1.21	追加: v0.1.21

<fs.Stats> オブジェクトは、ファイルに関する情報を提供します。

fs.stat()、fs.lstat()、fs.fstat() およびそれらの同期的な対応物から返されるオブジェクトはこの型です。これらのメソッドに渡される options の bigint が true の場合、数値は number の代わりに bigint になり、オブジェクトには Ns というサフィックスが付いたナノ秒精度のプロパティが追加されます。Stat オブジェクトは、new キーワードを使用して直接作成することはできません。

Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

bigint バージョン:

BigIntStats {
  dev: 2114n,
  ino: 48064969n,
  mode: 33188n,
  nlink: 1n,
  uid: 85n,
  gid: 100n,
  rdev: 0n,
  size: 527n,
  blksize: 4096n,
  blocks: 8n,
  atimeMs: 1318289051000n,
  mtimeMs: 1318289051000n,
  ctimeMs: 1318289051000n,
  birthtimeMs: 1318289051000n,
  atimeNs: 1318289051000000000n,
  mtimeNs: 1318289051000000000n,
  ctimeNs: 1318289051000000000n,
  birthtimeNs: 1318289051000000000n,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

stats.isBlockDevice()

追加: v0.1.10

• 戻り値: <boolean>

<fs.Stats>オブジェクトがブロックデバイスを表す場合に true を返します。

stats.isCharacterDevice()

追加: v0.1.10

• 戻り値: <boolean>

<fs.Stats>オブジェクトがキャラクタデバイスを表す場合に true を返します。

stats.isDirectory()

追加: v0.1.10

• 戻り値: <boolean>

<fs.Stats>オブジェクトがファイルシステムのディレクトリを表す場合に true を返します。

<fs.Stats>オブジェクトが、ディレクトリに解決されるシンボリックリンクに対して fs.lstat() を呼び出すことで取得された場合、このメソッドは false を返します。これは、fs.lstat() が解決先のパスではなく、シンボリックリンク自体に関する情報を返すためです。

stats.isFIFO()

追加: v0.1.10

• 戻り値: <boolean>

<fs.Stats>オブジェクトが先入れ先出し（FIFO）パイプを表す場合に true を返します。

stats.isFile()

追加: v0.1.10

• 戻り値: <boolean>

<fs.Stats>オブジェクトが通常のファイルを表す場合に true を返します。

stats.isSocket()

追加: v0.1.10

• 戻り値: <boolean>

<fs.Stats>オブジェクトがソケットを表す場合に true を返します。

stats.isSymbolicLink()

追加: v0.1.10

• 戻り値: <boolean>

<fs.Stats>オブジェクトがシンボリックリンクを表す場合に true を返します。

このメソッドは、fs.lstat() を使用する場合にのみ有効です。

stats.dev

• <number> | <bigint>

ファイルを含むデバイスの数値識別子。

stats.ino

• <number> | <bigint>

ファイルのファイルシステム固有の「Inode」番号。

stats.mode

• <number> | <bigint>

ファイルの種類とモードを記述するビットフィールド。

stats.nlink

• <number> | <bigint>

ファイルに存在するハードリンクの数。

stats.uid

• <number> | <bigint>

ファイルを所有するユーザーの数値ユーザー識別子（POSIX）。

stats.gid

• <number> | <bigint>

ファイルを所有するグループの数値グループ識別子（POSIX）。

stats.rdev

• <number> | <bigint>

ファイルがデバイスを表す場合の数値デバイス識別子。

stats.size

• <number> | <bigint>

ファイルのサイズ（バイト単位）。

基盤となるファイルシステムがファイルのサイズの取得をサポートしていない場合、これは 0 になります。

stats.blksize

• <number> | <bigint>

I/O 操作のためのファイルシステムブロックサイズ。

stats.blocks

• <number> | <bigint>

このファイルに割り当てられたブロック数。

stats.atimeMs

追加: v8.1.0

• <number> | <bigint>

POSIX エポックからのミリ秒単位で表される、このファイルが最後にアクセスされた時刻を示すタイムスタンプ。

stats.mtimeMs

追加: v8.1.0

• <number> | <bigint>

POSIX エポックからのミリ秒単位で表される、このファイルが最後に変更された時刻を示すタイムスタンプ。

stats.ctimeMs

追加: v8.1.0

• <number> | <bigint>

POSIX エポックからのミリ秒単位で表される、ファイルのステータスが最後に変更された時刻を示すタイムスタンプ。

stats.birthtimeMs

追加: v8.1.0

• <number> | <bigint>

POSIX エポックからのミリ秒単位で表される、このファイルの作成時刻を示すタイムスタンプ。

stats.atimeNs

追加: v12.10.0

• <bigint>

オブジェクトを生成するメソッドに bigint: true が渡された場合にのみ存在します。POSIX エポックからのナノ秒単位で表される、このファイルが最後にアクセスされた時刻を示すタイムスタンプ。

stats.mtimeNs

追加: v12.10.0

• <bigint>

オブジェクトを生成するメソッドに bigint: true が渡された場合にのみ存在します。POSIX エポックからの経過時間をナノ秒で表した、このファイルが最後に変更された時刻を示すタイムスタンプです。

stats.ctimeNs

追加: v12.10.0

• <bigint>

オブジェクトを生成するメソッドに bigint: true が渡された場合にのみ存在します。POSIX エポックからの経過時間をナノ秒で表した、ファイルのステータスが最後に変更された時刻を示すタイムスタンプです。

stats.birthtimeNs

追加: v12.10.0

• <bigint>

オブジェクトを生成するメソッドに bigint: true が渡された場合にのみ存在します。POSIX エポックからの経過時間をナノ秒で表した、このファイルが作成された時刻を示すタイムスタンプです。

stats.atime

追加: v0.11.13

• <Date>

このファイルが最後にアクセスされた時刻を示すタイムスタンプです。

stats.mtime

追加: v0.11.13

• <Date>

このファイルが最後に変更された時刻を示すタイムスタンプです。

stats.ctime

追加: v0.11.13

• <Date>

ファイルのステータスが最後に変更された時刻を示すタイムスタンプです。

stats.birthtime

追加: v0.11.13

• <Date>

このファイルが作成された時刻を示すタイムスタンプです。

Stat の時刻値

atimeMs, mtimeMs, ctimeMs, birthtimeMs プロパティは、対応する時刻をミリ秒単位で保持する数値です。精度はプラットフォーム固有です。オブジェクトを生成するメソッドに bigint: true が渡された場合、プロパティは bigint になり、そうでない場合は number になります。

atimeNs, mtimeNs, ctimeNs, birthtimeNs プロパティは、対応する時刻をナノ秒単位で保持する bigint です。これらは、オブジェクトを生成するメソッドに bigint: true が渡された場合にのみ存在します。精度はプラットフォーム固有です。

atime, mtime, ctime, および birthtime は、さまざまな時刻を Date オブジェクトで代替表現したものです。Date と数値は関連付けられていません。新しい数値を割り当てたり、Date の値を変更したりしても、対応する代替表現には反映されません。

stat オブジェクト内の時刻には、次のセマンティクスがあります。

• atime "アクセス時間": ファイルデータが最後にアクセスされた時刻。mknod(2)、utimes(2)、および read(2) システムコールによって変更されます。
• mtime "変更時間": ファイルデータが最後に変更された時刻。mknod(2)、utimes(2)、および write(2) システムコールによって変更されます。
• ctime "変更時間": ファイルステータスが最後に変更された時刻 (inode データ変更)。chmod(2)、chown(2)、link(2)、mknod(2)、rename(2)、unlink(2)、utimes(2)、read(2)、および write(2) システムコールによって変更されます。
• birthtime "作成時間": ファイルが作成された時刻。ファイルが作成されたときに一度設定されます。birthtime が利用できないファイルシステムでは、このフィールドは代わりに ctime または 1970-01-01T00:00Z (つまり、Unix エポックタイムスタンプ 0) を保持する場合があります。この場合、この値は atime または mtime より大きくなる場合があります。Darwin およびその他の FreeBSD バリアントでは、utimes(2) システムコールを使用して atime を現在の birthtime よりも前の値に明示的に設定した場合も設定されます。

Node.js 0.12 より前では、Windows システムで ctime は birthtime を保持していました。0.12 以降、ctime は「作成時間」ではなく、Unix システムでは決してそうではありませんでした。

クラス: fs.StatFs

追加: v19.6.0, v18.15.0

マウントされたファイルシステムに関する情報を提供します。

fs.statfs()とその同期版から返されるオブジェクトは、この型です。これらのメソッドに渡された options の bigint が true の場合、数値は number の代わりに bigint になります。

StatFs {
  type: 1397114950,
  bsize: 4096,
  blocks: 121938943,
  bfree: 61058895,
  bavail: 61058895,
  files: 999,
  ffree: 1000000
}

bigint バージョン:

StatFs {
  type: 1397114950n,
  bsize: 4096n,
  blocks: 121938943n,
  bfree: 61058895n,
  bavail: 61058895n,
  files: 999n,
  ffree: 1000000n
}

statfs.bavail

追加: v19.6.0, v18.15.0

• <number> | <bigint>

権限のないユーザーが利用できる空きブロック。

statfs.bfree

追加: v19.6.0, v18.15.0

• <number> | <bigint>

ファイルシステム内の空きブロック。

statfs.blocks

追加: v19.6.0, v18.15.0

• <number> | <bigint>

ファイルシステム内のデータブロックの総数。

statfs.bsize

追加: v19.6.0, v18.15.0

• <number> | <bigint>

最適な転送ブロックサイズ。

statfs.ffree

追加: v19.6.0, v18.15.0

• <number> | <bigint>

ファイルシステム内の空きファイルノード。

statfs.files

追加: v19.6.0, v18.15.0

• <number> | <bigint>

ファイルシステム内のファイルノードの総数。

statfs.type

追加: v19.6.0, v18.15.0

• <number> | <bigint>

ファイルシステムのタイプ。

クラス: fs.WriteStream

追加: v0.1.93

• <stream.Writable> を拡張

<fs.WriteStream> のインスタンスは、fs.createWriteStream() 関数を使用して作成および返されます。

イベント: 'close'

追加: v0.1.93

<fs.WriteStream> の基になるファイル記述子が閉じられたときに発生します。

イベント: 'open'

追加: v0.1.93

• fd <integer> <fs.WriteStream> によって使用される整数ファイル記述子。

<fs.WriteStream> のファイルが開かれたときに発生します。

イベント: 'ready'

追加: v9.11.0

<fs.WriteStream> が使用できる状態になったときに発生します。

'open' の直後に発生します。

writeStream.bytesWritten

追加: v0.4.7

これまでに書き込まれたバイト数。書き込みのためにまだキューに入っているデータは含まれません。

writeStream.close([callback])

追加: v0.9.4

• callback <Function>
  • err <Error>

writeStream を閉じます。オプションで、writeStream が閉じられた後に実行されるコールバックを受け入れます。

writeStream.path

追加: v0.1.93

fs.createWriteStream()の最初の引数で指定された、ストリームが書き込んでいるファイルへのパス。pathが文字列として渡された場合、writeStream.pathは文字列になります。pathが<Buffer>として渡された場合、writeStream.pathは<Buffer>になります。

writeStream.pending

追加: v11.2.0

• <boolean>

このプロパティは、基になるファイルがまだ開かれていない場合、つまり 'ready' イベントが発行される前にtrueになります。

fs.constants

• <Object>

ファイルシステム操作で一般的に使用される定数を含むオブジェクトを返します。

FS 定数

次の定数は、fs.constantsとfsPromises.constantsによってエクスポートされます。

すべての定数がすべてのオペレーティングシステムで使用できるわけではありません。これは特に Windows で重要で、POSIX 固有の定義の多くは使用できません。移植可能なアプリケーションでは、使用前にその存在を確認することをお勧めします。

複数の定数を使用するには、ビット単位の OR |演算子を使用します。

例：

import { open, constants } from 'node:fs'

const { O_RDWR, O_CREAT, O_EXCL } = constants

open('/path/to/my/file', O_RDWR | O_CREAT | O_EXCL, (err, fd) => {
  // ...
})

ファイルアクセス定数

次の定数は、fsPromises.access()、fs.access()、およびfs.accessSync()に渡されるmodeパラメータとして使用することを目的としています。

定数	説明
F_OK	ファイルが呼び出しプロセスに表示されることを示すフラグ。これはファイルが存在するかどうかを判断するのに役立ちますが、rwx権限については何も言いません。モードが指定されていない場合のデフォルト。
R_OK	ファイルが呼び出しプロセスによって読み取り可能であることを示すフラグ。
W_OK	ファイルが呼び出しプロセスによって書き込み可能であることを示すフラグ。
X_OK	ファイルが呼び出しプロセスによって実行可能であることを示すフラグ。これは Windows では効果がありません（fs.constants.F_OKのように動作します）。

これらの定義は、Windows でも利用可能です。

ファイルコピー定数

以下の定数は、fs.copyFile() で使用するためのものです。

定数	説明
COPYFILE_EXCL	このフラグが存在する場合、コピー先のパスがすでに存在すると、コピー操作はエラーで失敗します。
COPYFILE_FICLONE	このフラグが存在する場合、コピー操作はコピーオンライトのリファレンスを作成しようとします。基盤となるプラットフォームがコピーオンライトをサポートしていない場合は、フォールバックコピーメカニズムが使用されます。
COPYFILE_FICLONE_FORCE	このフラグが存在する場合、コピー操作はコピーオンライトのリファレンスを作成しようとします。基盤となるプラットフォームがコピーオンライトをサポートしていない場合は、操作はエラーで失敗します。

これらの定義は、Windows でも利用可能です。

ファイルオープン定数

以下の定数は、fs.open() で使用するためのものです。

定数	説明
O_RDONLY	ファイルを読み取り専用アクセスで開くことを示すフラグ。
O_WRONLY	ファイルを書き込み専用アクセスで開くことを示すフラグ。
O_RDWR	ファイルを読み書きアクセスで開くことを示すフラグ。
O_CREAT	ファイルが存在しない場合にファイルを作成することを示すフラグ。
O_EXCL	O_CREAT フラグが設定されていて、ファイルがすでに存在する場合に、ファイルを開くことが失敗することを示すフラグ。
O_NOCTTY	パスが端末デバイスを識別する場合、パスを開いても、（プロセスがまだ持っていない場合）その端末がプロセスの制御端末にならないことを示すフラグ。
O_TRUNC	ファイルが存在し、通常のファイルであり、ファイルが書き込みアクセスで正常に開かれた場合、その長さがゼロに切り捨てられることを示すフラグ。
O_APPEND	データがファイルの末尾に追加されることを示すフラグ。
O_DIRECTORY	パスがディレクトリでない場合に、オープンが失敗することを示すフラグ。
O_NOATIME	ファイルシステムへの読み取りアクセスによって、ファイルに関連付けられた atime 情報が更新されなくなることを示すフラグ。このフラグは Linux オペレーティングシステムでのみ使用できます。
O_NOFOLLOW	パスがシンボリックリンクである場合に、オープンが失敗することを示すフラグ。
O_SYNC	ファイルがファイル整合性を待つ書き込み操作で同期 I/O 用に開かれることを示すフラグ。
O_DSYNC	ファイルがデータ整合性を待つ書き込み操作で同期 I/O 用に開かれることを示すフラグ。
O_SYMLINK	指しているリソースではなく、シンボリックリンク自体を開くことを示すフラグ。
O_DIRECT	設定すると、ファイル I/O のキャッシュ効果を最小限に抑える試みが行われます。
O_NONBLOCK	可能であれば、ファイルをノンブロッキングモードで開くことを示すフラグ。
UV_FS_O_FILEMAP	設定すると、メモリファイルマッピングを使用してファイルにアクセスします。このフラグは Windows オペレーティングシステムでのみ使用できます。他のオペレーティングシステムでは、このフラグは無視されます。

Windows では、O_APPEND、O_CREAT、O_EXCL、O_RDONLY、O_RDWR、O_TRUNC、O_WRONLY、および UV_FS_O_FILEMAP のみが利用可能です。

ファイルタイプ定数

以下の定数は、ファイルのタイプを決定するために<fs.Stats>オブジェクトのmodeプロパティで使用することを目的としています。

定数	説明
S_IFMT	ファイルタイプコードを抽出するために使用されるビットマスク。
S_IFREG	通常ファイルのファイルタイプ定数。
S_IFDIR	ディレクトリのファイルタイプ定数。
S_IFCHR	文字指向デバイスファイルのファイルタイプ定数。
S_IFBLK	ブロック指向デバイスファイルのファイルタイプ定数。
S_IFIFO	FIFO/パイプのファイルタイプ定数。
S_IFLNK	シンボリックリンクのファイルタイプ定数。
S_IFSOCK	ソケットのファイルタイプ定数。

Windows では、S_IFCHR、S_IFDIR、S_IFLNK、S_IFMT、およびS_IFREGのみが利用可能です。

ファイルモード定数

以下の定数は、ファイルへのアクセス許可を決定するために<fs.Stats>オブジェクトのmodeプロパティで使用することを目的としています。

定数	説明
S_IRWXU	オーナーによる読み取り、書き込み、および実行可能を示すファイルモード。
S_IRUSR	オーナーによる読み取り可能を示すファイルモード。
S_IWUSR	オーナーによる書き込み可能を示すファイルモード。
S_IXUSR	オーナーによる実行可能を示すファイルモード。
S_IRWXG	グループによる読み取り、書き込み、および実行可能を示すファイルモード。
S_IRGRP	グループによる読み取り可能を示すファイルモード。
S_IWGRP	グループによる書き込み可能を示すファイルモード。
S_IXGRP	グループによる実行可能を示すファイルモード。
S_IRWXO	他のユーザーによる読み取り、書き込み、および実行可能を示すファイルモード。
S_IROTH	他のユーザーによる読み取り可能を示すファイルモード。
S_IWOTH	他のユーザーによる書き込み可能を示すファイルモード。
S_IXOTH	他のユーザーによる実行可能を示すファイルモード。

Windows では、S_IRUSRとS_IWUSRのみが利用可能です。

注釈

コールバックと Promise ベースの操作の順序

コールバックまたは Promise ベースのメソッドを使用する場合、それらは基盤となるスレッドプールによって非同期的に実行されるため、順序は保証されません。

例えば、次の例では、fs.stat()操作がfs.rename()操作より先に完了する可能性があるため、エラーが発生しやすくなります。

const fs = require('node:fs')

fs.rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  console.log('renamed complete')
})
fs.stat('/tmp/world', (err, stats) => {
  if (err) throw err
  console.log(`stats: ${JSON.stringify(stats)}`)
})

一方の操作の結果を待ってからもう一方の操作を呼び出すことで、操作を正しく順序付けることが重要です。

ESM

import { rename, stat } from 'node:fs/promises'

const oldPath = '/tmp/hello'
const newPath = '/tmp/world'

try {
  await rename(oldPath, newPath)
  const stats = await stat(newPath)
  console.log(`stats: ${JSON.stringify(stats)}`)
} catch (error) {
  console.error('there was an error:', error.message)
}

CJS

const { rename, stat } = require('node:fs/promises')

;(async function (oldPath, newPath) {
  try {
    await rename(oldPath, newPath)
    const stats = await stat(newPath)
    console.log(`stats: ${JSON.stringify(stats)}`)
  } catch (error) {
    console.error('there was an error:', error.message)
  }
})('/tmp/hello', '/tmp/world')

または、コールバック API を使用する場合は、fs.stat() の呼び出しを fs.rename() 操作のコールバックに移動します。

ESM

import { rename, stat } from 'node:fs'

rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  stat('/tmp/world', (err, stats) => {
    if (err) throw err
    console.log(`stats: ${JSON.stringify(stats)}`)
  })
})

CJS

const { rename, stat } = require('node:fs/promises')

rename('/tmp/hello', '/tmp/world', err => {
  if (err) throw err
  stat('/tmp/world', (err, stats) => {
    if (err) throw err
    console.log(`stats: ${JSON.stringify(stats)}`)
  })
})

ファイルパス

ほとんどの fs 操作は、文字列、<Buffer>、または file: プロトコルを使用した<URL>オブジェクトの形式で指定できるファイルパスを受け入れます。

文字列パス

文字列パスは、絶対または相対ファイル名を識別する UTF-8 文字シーケンスとして解釈されます。相対パスは、process.cwd() を呼び出すことによって決定される現在の作業ディレクトリを基準に解決されます。

POSIX での絶対パスを使用した例:

import { open } from 'node:fs/promises'

let fd
try {
  fd = await open('/open/some/file.txt', 'r')
  // ファイルに対する処理
} finally {
  await fd?.close()
}

POSIX での相対パスを使用した例 (process.cwd() を基準):

import { open } from 'node:fs/promises'

let fd
try {
  fd = await open('file.txt', 'r')
  // ファイルに対する処理
} finally {
  await fd?.close()
}

ファイル URL パス

追加: v7.6.0

ほとんどの node:fs モジュール関数では、path または filename 引数は、file: プロトコルを使用した<URL>オブジェクトとして渡すことができます。

import { readFileSync } from 'node:fs'

readFileSync(new URL('file:///tmp/hello'))

file: URL は常に絶対パスです。

プラットフォーム固有の考慮事項

Windows では、ホスト名を持つ file: <URL> は UNC パスに変換され、ドライブ文字を持つ file: <URL> はローカルの絶対パスに変換されます。ホスト名もドライブ文字もない file: <URL> はエラーになります。

import { readFileSync } from 'node:fs'
// Windows の場合:

// - ホスト名を持つ WHATWG ファイル URL は UNC パスに変換されます
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
readFileSync(new URL('file://hostname/p/a/t/h/file'))

// - ドライブ文字を持つ WHATWG ファイル URL は絶対パスに変換されます
// file:///C:/tmp/hello => C:\tmp\hello
readFileSync(new URL('file:///C:/tmp/hello'))

// - ホスト名のない WHATWG ファイル URL にはドライブ文字が必要です
readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'))
readFileSync(new URL('file:///c/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: ファイル URL パスは絶対パスでなければなりません

ドライブ文字を持つ file: <URL> は、ドライブ文字の直後の区切り文字として : を使用する必要があります。別の区切り文字を使用すると、エラーが発生します。

他のすべてのプラットフォームでは、ホスト名を持つ file: <URL> はサポートされておらず、エラーになります。

import { readFileSync } from 'node:fs'
// その他のプラットフォームの場合:

// - ホスト名を持つ WHATWG ファイル URL はサポートされていません
// file://hostname/p/a/t/h/file => throw!
readFileSync(new URL('file://hostname/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: 絶対パスでなければなりません

// - WHATWG ファイル URL は絶対パスに変換されます
// file:///tmp/hello => /tmp/hello
readFileSync(new URL('file:///tmp/hello'))

エンコードされたスラッシュ文字を持つ file: <URL> は、すべてのプラットフォームでエラーになります。

import { readFileSync } from 'node:fs'

// Windows の場合
readFileSync(new URL('file:///C:/p/a/t/h/%2F'))
readFileSync(new URL('file:///C:/p/a/t/h/%2f'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: ファイル URL パスには、エンコードされた
\ または / 文字を含めることはできません */

// POSIX の場合
readFileSync(new URL('file:///p/a/t/h/%2F'))
readFileSync(new URL('file:///p/a/t/h/%2f'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: ファイル URL パスには、エンコードされた
/ 文字を含めることはできません */

Windows では、エンコードされたバックスラッシュを持つ file: <URL> はエラーになります。

import { readFileSync } from 'node:fs'

// Windows の場合
readFileSync(new URL('file:///C:/path/%5C'))
readFileSync(new URL('file:///C:/path/%5c'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: ファイル URL パスには、エンコードされた
\ または / 文字を含めることはできません */

Buffer パス

<Buffer> を使用して指定されたパスは、主にファイルパスを不透明なバイトシーケンスとして扱う特定の POSIX オペレーティングシステムで役立ちます。このようなシステムでは、単一のファイルパスに複数の文字エンコーディングを使用するサブシーケンスを含めることが可能です。文字列パスと同様に、<Buffer> パスは相対パスまたは絶対パスにすることができます。

POSIX での絶対パスを使用する例:

import { open } from 'node:fs/promises'
import { Buffer } from 'node:buffer'

let fd
try {
  fd = await open(Buffer.from('/open/some/file.txt'), 'r')
  // ファイルに対して何かを行う
} finally {
  await fd?.close()
}

Windows でのドライブごとの作業ディレクトリ

Windows では、Node.js はドライブごとの作業ディレクトリの概念に従います。この動作は、バックスラッシュなしでドライブパスを使用すると観察できます。たとえば、fs.readdirSync('C:\\') は、fs.readdirSync('C:') とは異なる結果を返す可能性があります。詳細については、この MSDN ページ を参照してください。

ファイル記述子

POSIX システムでは、すべてのプロセスについて、カーネルは現在開いているファイルとリソースのテーブルを維持します。各オープンファイルには、ファイル記述子 と呼ばれる単純な数値識別子が割り当てられます。システムレベルでは、すべてのファイルシステム操作は、これらのファイル記述子を使用して、特定の各ファイルを識別および追跡します。Windows システムでは、リソースを追跡するために異なるが概念的に類似したメカニズムを使用します。ユーザーの便宜を図るため、Node.js はオペレーティングシステム間の違いを抽象化し、すべてのオープンファイルに数値ファイル記述子を割り当てます。

コールバックベースの fs.open() と同期 fs.openSync() メソッドは、ファイルを開き、新しいファイル記述子を割り当てます。割り当てられたファイル記述子は、ファイルからのデータの読み取り、ファイルへのデータの書き込み、またはファイルに関する情報の要求に使用できます。

オペレーティングシステムは、任意の時点で開くことができるファイル記述子の数を制限しているため、操作が完了したら記述子を閉じることが重要です。そうしないと、最終的にアプリケーションがクラッシュするメモリリークが発生します。

import { open, close, fstat } from 'node:fs'

function closeFd(fd) {
  close(fd, err => {
    if (err) throw err
  })
}

open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err
  try {
    fstat(fd, (err, stat) => {
      if (err) {
        closeFd(fd)
        throw err
      }

      // stat を使用する

      closeFd(fd)
    })
  } catch (err) {
    closeFd(fd)
    throw err
  }
})

Promise ベースの API は、数値ファイル記述子の代わりに<FileHandle> オブジェクトを使用します。これらのオブジェクトは、リソースがリークしないようにシステムによってより適切に管理されます。ただし、操作が完了したらそれらを閉じる必要は依然としてあります。

import { open } from 'node:fs/promises'

let file
try {
  file = await open('/open/some/file.txt', 'r')
  const stat = await file.stat()
  // stat を使用する
} finally {
  await file.close()
}

スレッドプールの使用法

すべてのコールバックおよび Promise ベースのファイルシステム API（fs.FSWatcher()を除く）は、libuv のスレッドプールを使用します。これは一部のアプリケーションにとって、驚くべき、そして負のパフォーマンス上の影響を及ぼす可能性があります。詳細については、UV_THREADPOOL_SIZE のドキュメントを参照してください。

ファイルシステムフラグ

次のフラグは、flagオプションが文字列を取る場所で使用できます。

• 'a': 追記のためにファイルを開きます。ファイルが存在しない場合は作成されます。
• 'ax': 'a'と同様ですが、パスが存在する場合は失敗します。
• 'a+': 読み取りと追記のためにファイルを開きます。ファイルが存在しない場合は作成されます。
• 'ax+': 'a+'と同様ですが、パスが存在する場合は失敗します。
• 'as': 同期モードで追記するためにファイルを開きます。ファイルが存在しない場合は作成されます。
• 'as+': 同期モードで読み取りと追記のためにファイルを開きます。ファイルが存在しない場合は作成されます。
• 'r': 読み取りのためにファイルを開きます。ファイルが存在しない場合は例外が発生します。
• 'rs': 同期モードで読み取りのためにファイルを開きます。ファイルが存在しない場合は例外が発生します。
• 'r+': 読み取りと書き込みのためにファイルを開きます。ファイルが存在しない場合は例外が発生します。
• 'rs+': 同期モードで読み取りと書き込みのためにファイルを開きます。ローカルファイルシステムキャッシュをバイパスするようにオペレーティングシステムに指示します。これは主に、NFS マウント上のファイルを開く場合に、潜在的に古いローカルキャッシュをスキップできるため便利です。これは I/O パフォーマンスに非常に大きな影響を与えるため、必要な場合を除いてこのフラグを使用することはお勧めしません。これにより、fs.open()またはfsPromises.open()が同期的なブロッキング呼び出しになるわけではありません。同期操作が必要な場合は、fs.openSync()のようなものを使用する必要があります。
• 'w': 書き込みのためにファイルを開きます。ファイルは（存在しない場合は）作成され、（存在する場合は）切り詰められます。
• 'wx': 'w'と同様ですが、パスが存在する場合は失敗します。
• 'w+': 読み取りと書き込みのためにファイルを開きます。ファイルは（存在しない場合は）作成され、（存在する場合は）切り詰められます。
• 'wx+': 'w+'と同様ですが、パスが存在する場合は失敗します。

flagは、open(2) に記載されているように数値にすることもできます。一般的に使用される定数は fs.constants から入手できます。Windows では、フラグは該当する場合に同等のものに変換されます。例えば、O_WRONLYはFILE_GENERIC_WRITEに、またはO_EXCL|O_CREATはCreateFileWに受け入れられるようにCREATE_NEWに変換されます。

排他的フラグ 'x'（open(2) のO_EXCLフラグ）は、パスが既に存在する場合に操作がエラーを返すようにします。POSIX では、パスがシンボリックリンクの場合、O_EXCLを使用すると、リンク先が存在しない場合でもエラーが返されます。排他的フラグは、ネットワークファイルシステムでは機能しない場合があります。

Linux では、ファイルが追記モードで開かれている場合、位置指定書き込みは機能しません。カーネルは位置引数を無視し、常にデータの末尾に追記します。

ファイルを置換するのではなく変更する場合は、flagオプションをデフォルトの'w'ではなく'r+'に設定する必要がある場合があります。

一部のフラグの動作はプラットフォーム固有です。そのため、以下の例のように、macOS および Linux で'a+'フラグを使用してディレクトリを開くと、エラーが返されます。対照的に、Windows および FreeBSD では、ファイル記述子またはFileHandleが返されます。

// macOS および Linux
fs.open('<directory>', 'a+', (err, fd) => {
  // => [Error: EISDIR: ディレクトリに対する不正な操作, open <directory>]
})

// Windows および FreeBSD
fs.open('<directory>', 'a+', (err, fd) => {
  // => null, <fd>
})

Windows では、'w'フラグを使用して（fs.open()、fs.writeFile()、またはfsPromises.open()のいずれかを介して）既存の隠しファイルを開くと、EPERMで失敗します。既存の隠しファイルは'r+'フラグを使用して書き込み用に開くことができます。

fs.ftruncate()またはfilehandle.truncate()の呼び出しを使用して、ファイルの内容をリセットできます。