파일 시스템

[안정적: 2 - 안정적]

안정적: 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) {
  // handle the error
}

CJS

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

try {
  unlinkSync('/tmp/hello')
  console.log('successfully deleted /tmp/hello')
} catch (err) {
  // handle the error
}

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 threadpool을 사용하여 이벤트 루프 스레드에서 파일 시스템 작업을 수행합니다. 이러한 작업은 동기화되지 않거나 스레드로 안전하지 않습니다. 동일한 파일에서 여러 개의 동시 수정 작업을 수행할 때는 주의해야 합니다. 그렇지 않으면 데이터 손상이 발생할 수 있습니다.

클래스: FileHandle

추가됨: v10.0.0

<FileHandle> 객체는 숫자 파일 디스크립터에 대한 객체 래퍼입니다.

<FileHandle> 객체의 인스턴스는 fsPromises.open() 메서드에 의해 생성됩니다.

모든 <FileHandle> 객체는 <EventEmitter>입니다.

<FileHandle>이 filehandle.close() 메서드를 사용하여 닫히지 않으면 파일 디스크립터를 자동으로 닫고 프로세스 경고를 발생시켜 메모리 누수를 방지하는 데 도움이 됩니다. 하지만 이 동작은 신뢰할 수 없고 파일이 닫히지 않을 수 있으므로 이 동작에 의존해서는 안 됩니다. 대신 항상 <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)

추가됨: v10.0.0

• mode <정수> 파일 모드 비트 마스크.
• 반환값: <Promise> 성공 시 undefined를 반환합니다.

파일의 권한을 수정합니다. chmod(2) 참조.

filehandle.chown(uid, gid)

추가됨: v10.0.0

• uid <정수> 파일의 새로운 소유자 사용자 ID.
• gid <정수> 파일의 새로운 그룹 그룹 ID.
• 반환값: <Promise> 성공 시 undefined를 반환합니다.

파일의 소유권을 변경합니다. chown(2)에 대한 래퍼입니다.

filehandle.close()

추가됨: 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])

추가됨: v16.11.0

• options <객체>

  • encoding <문자열> 기본값: null
  • autoClose <불리언> 기본값: true
  • emitClose <불리언> 기본값: true
  • start <정수>
  • end <정수> 기본값: Infinity
  • highWaterMark <정수> 기본값: 64 * 1024
  • signal <AbortSignal> | <정의되지 않음> 기본값: 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> 성공 시 두 개의 속성을 가진 객체를 이행합니다.
  • 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이 0보다 큰 정수이면 현재 파일 위치는 변경되지 않습니다. 기본값: null

• 반환값: <Promise> 두 개의 속성을 가진 객체로 성공 시 이행됨:

  • bytesRead <integer> 읽은 바이트 수
  • buffer <Buffer> | <TypedArray> | <DataView> 전달된 buffer 인수에 대한 참조.

파일에서 데이터를 읽어 지정된 버퍼에 저장합니다.

파일이 동시에 수정되지 않으면 읽은 바이트 수가 0일 때 파일 끝에 도달합니다.

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 <정수> 채우기를 시작할 버퍼의 위치. 기본값: 0
  • length <정수> 읽을 바이트 수. 기본값: buffer.byteLength - offset
  • position <정수> | <bigint> | <null> 파일에서 데이터 읽기를 시작할 위치. null 또는 -1이면 현재 파일 위치에서 데이터를 읽고 위치가 업데이트됩니다. position이 0보다 큰 정수이면 현재 파일 위치는 변경되지 않습니다. 기본값: null

• 반환값: <Promise> 두 개의 속성을 가진 객체로 성공 시 이행됨:

  • bytesRead <정수> 읽은 바이트 수
  • buffer <Buffer> | <TypedArray> | <DataView> 전달된 buffer 인수에 대한 참조.

파일에서 데이터를 읽어 지정된 버퍼에 저장합니다.

파일이 동시에 수정되지 않으면 읽은 바이트 수가 0일 때 파일 끝에 도달합니다.

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>은 읽기를 지원해야 합니다.

하나 이상의 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이 숫자가 아니면 현재 위치에서 데이터를 읽습니다. 기본값: null
• 반환값: <Promise> 성공 시 두 가지 속성을 포함하는 객체를 이행합니다.
  • bytesRead <integer> 읽은 바이트 수
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> buffers 입력에 대한 참조를 포함하는 속성입니다.

<ArrayBufferView> 배열에 파일에서 읽고 씁니다.

filehandle.stat([options])

[히스토리]

버전	변경 사항
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 <숫자> | <문자열> | <Date>
• mtime <숫자> | <문자열> | <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 <정수> 쓰기 시작할 데이터가 있는 buffer 내의 시작 위치입니다.
• length <정수> buffer에서 쓸 바이트 수입니다. 기본값: buffer.byteLength - offset
• position <정수> | <null> buffer의 데이터를 쓸 파일의 처음부터 오프셋입니다. position이 숫자가 아니면 데이터는 현재 위치에 쓰여집니다. 자세한 내용은 POSIX pwrite(2) 문서를 참조하십시오. 기본값: null
• 반환값: <Promise>

buffer를 파일에 씁니다.

Promise는 두 가지 속성을 포함하는 객체로 이행됩니다.

• bytesWritten <정수> 쓰여진 바이트 수
• buffer <Buffer> | <TypedArray> | <DataView> 쓰여진 buffer에 대한 참조입니다.

Promise가 이행(또는 거부)될 때까지 기다리지 않고 동일한 파일에 여러 번 filehandle.write()를 사용하는 것은 안전하지 않습니다. 이 시나리오에서는 filehandle.createWriteStream()을 사용하십시오.

Linux에서는 파일이 추가 모드로 열리면 위치 지정 쓰기가 작동하지 않습니다. 커널은 위치 인수를 무시하고 항상 데이터를 파일 끝에 추가합니다.

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이 숫자가 아니면 데이터는 현재 위치에 쓰여집니다. 자세한 내용은 POSIX pwrite(2) 문서를 참조하십시오. 기본값: null
• encoding <string> 예상되는 문자열 인코딩입니다. 기본값: 'utf8'
• 반환값: <Promise>

string을 파일에 씁니다. string이 문자열이 아니면 promise는 오류와 함께 거부됩니다.

promise는 두 개의 속성을 포함하는 객체로 이행됩니다.

• bytesWritten <integer> 쓰여진 바이트 수
• buffer <string> 쓰여진 string에 대한 참조

promise가 이행(또는 거부)될 때까지 기다리지 않고 동일한 파일에 여러 번 filehandle.write()를 사용하는 것은 안전하지 않습니다. 이러한 시나리오에서는 filehandle.createWriteStream()을 사용하십시오.

Linux에서는 파일이 추가 모드로 열릴 때 위치 지정 쓰기가 작동하지 않습니다. 커널은 위치 인수를 무시하고 항상 데이터를 파일 끝에 추가합니다.

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()를 사용하는 것은 안전하지 않습니다.

하나 이상의 filehandle.write() 호출이 파일 핸들에서 이루어진 다음 filehandle.writeFile() 호출이 이루어지면 데이터는 현재 위치부터 파일 끝까지 기록됩니다. 항상 파일의 처음부터 쓰는 것은 아닙니다.

filehandle.writev(buffers[, position])

추가됨: v12.9.0

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> buffers의 데이터를 쓸 파일의 시작 부분으로부터의 오프셋입니다. position이 숫자가 아니면, 데이터는 현재 위치에 쓰여집니다. 기본값: null
• 반환값: <Promise>

<ArrayBufferView>들의 배열을 파일에 씁니다.

Promise는 두 개의 속성을 포함하는 객체로 이행됩니다.

• bytesWritten <integer> 쓰여진 바이트 수
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> buffers 입력에 대한 참조

Promise가 이행(또는 거부)될 때까지 기다리지 않고 같은 파일에 여러 번 writev()를 호출하는 것은 안전하지 않습니다.

Linux에서는 파일이 추가 모드로 열릴 때 위치 지정 쓰기가 작동하지 않습니다. 커널은 위치 인수를 무시하고 항상 데이터를 파일 끝에 추가합니다.

filehandle[Symbol.asyncDispose]()

추가됨: v20.4.0, v18.18.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

filehandle.close()의 별칭입니다.

fsPromises.access(path[, mode])

추가됨: v10.0.0

• path <string> | <Buffer> | <URL>
• mode <integer> 기본값: fs.constants.F_OK
• 반환값: <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()를 사용하는 것은 권장하지 않습니다. 이렇게 하면 두 호출 사이에 다른 프로세스가 파일의 상태를 변경할 수 있으므로 경합 상태가 발생합니다. 대신, 사용자 코드는 파일을 직접 열어 읽거나 쓰고 파일이 접근 불가능한 경우 발생하는 오류를 처리해야 합니다.

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

[히스토리]

버전	변경 사항
v21.1.0, v20.10.0	flush 옵션이 지원됩니다.
v10.0.0	추가됨: v10.0.0

• path <string> | <Buffer> | <URL> | <FileHandle> 파일 이름 또는 <FileHandle>

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> 기본값: 'utf8'
  • mode <integer> 기본값: 0o666
  • flag <string> 파일 시스템 flags 지원을 참조하십시오. 기본값: 'a'.
  • flush <boolean> true이면 기본 파일 디스크립터는 닫기 전에 플러시됩니다. 기본값: false.

• 반환값: <Promise> 성공 시 undefined로 이행됩니다.

데이터를 비동기적으로 파일에 추가하고, 파일이 아직 존재하지 않으면 파일을 만듭니다. data는 문자열 또는 <Buffer>일 수 있습니다.

options가 문자열이면 encoding을 지정합니다.

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> 복사 작업의 동작을 지정하는 선택적 수정자입니다. 두 개 이상의 값의 비트별 OR로 구성된 마스크를 만들 수 있습니다(예: fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE). 기본값: 0.

  • fs.constants.COPYFILE_EXCL: dest가 이미 존재하는 경우 복사 작업이 실패합니다.
  • fs.constants.COPYFILE_FICLONE: 복사 작업은 복사본 작성 reflink를 만들려고 시도합니다. 플랫폼이 복사본 작성을 지원하지 않는 경우 대체 복사 메커니즘이 사용됩니다.
  • fs.constants.COPYFILE_FICLONE_FORCE: 복사 작업은 복사본 작성 reflink를 만들려고 시도합니다. 플랫폼이 복사본 작성을 지원하지 않는 경우 작업이 실패합니다.

• 반환값: <Promise> 성공 시 undefined를 반환합니다.

src를 dest로 비동기적으로 복사합니다. 기본적으로 dest는 이미 존재하는 경우 덮어씁니다.

복사 작업의 원자성에 대한 보장은 없습니다. 대상 파일을 쓰기 위해 열린 후 오류가 발생하면 대상을 제거하려고 시도합니다.

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

try {
  await copyFile('source.txt', 'destination.txt')
  console.log('source.txt가 destination.txt로 복사되었습니다.')
} catch {
  console.error('파일을 복사할 수 없습니다.')
}

// COPYFILE_EXCL을 사용하면 destination.txt가 존재하는 경우 작업이 실패합니다.
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL)
  console.log('source.txt가 destination.txt로 복사되었습니다.')
} catch {
  console.error('파일을 복사할 수 없습니다.')
}

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])

[히스토리]

버전	변경 사항
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.

• 반환값: <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>
• 반환값: <Promise> 성공 시 undefined를 이행합니다.

심볼릭 링크의 권한을 변경합니다.

이 메서드는 macOS에서만 구현됩니다.

fsPromises.lchown(path, uid, gid)

[히스토리]

버전	변경 사항
v10.6.0	더 이상 이 API는 deprecated되지 않습니다.
v10.0.0	추가됨: v10.0.0

• path <문자열> | <버퍼> | <URL>
• uid <정수>
• gid <정수>
• 반환값: <Promise> 성공 시 undefined를 이행합니다.

심볼릭 링크의 소유권을 변경합니다.

fsPromises.lutimes(path, atime, mtime)

추가됨: v14.5.0, v12.19.0

• path <문자열> | <버퍼> | <URL>
• atime <숫자> | <문자열> | <날짜>
• mtime <숫자> | <문자열> | <날짜>
• 반환값: <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()과 동일하며, 심볼릭 링크를 참조하는 경우 링크 자체의 상태가 확인되고, 링크가 참조하는 파일의 상태는 확인되지 않습니다. 자세한 내용은 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가 이미 존재하는 디렉토리이고 recursive가 false인 경우 fsPromises.mkdir() 호출은 거부됩니다.

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])

[History]

버전	변경 사항
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 <문자열> | <버퍼> | <URL>
• flags <문자열> | <숫자> 파일 시스템 flags 지원 참조[/api/fs#file-system-flags]. 기본값: 'r'.
• mode <문자열> | <정수> 파일이 생성되는 경우 파일 모드(권한 및 고정 비트)를 설정합니다. 기본값: 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 <문자열> | <버퍼> | <URL>

• options <객체>

  • encoding <문자열> | <널> 기본값: 'utf8'
  • bufferSize <숫자> 디렉토리에서 읽을 때 내부적으로 버퍼링되는 디렉토리 항목 수입니다. 값이 높을수록 성능이 향상되지만 메모리 사용량도 증가합니다. 기본값: 32
  • recursive <부울> 확인된 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) 문서를 참조하십시오. 성공 시 약속은 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에 연결된 경우 이 함수가 작동하려면 /proc에 procfs 파일 시스템이 마운트되어야 합니다. 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 오류와 함께 Promise가 거부됩니다.

rm -rf Unix 명령과 유사한 동작을 얻으려면, { recursive: true, force: true } 옵션을 사용하여 fsPromises.rm()을 사용하십시오.

fsPromises.rm(path[, options])

추가됨: v14.14.0

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

• options <Object>

  • force <boolean> path가 존재하지 않을 경우 예외를 무시합니다. 기본값: false.
  • maxRetries <integer> EBUSY, EMFILE, ENFILE, ENOTEMPTY, 또는 EPERM 오류가 발생하면, Node.js는 retryDelay 밀리초만큼 선형 백오프 대기 시간을 더하여 작업을 다시 시도합니다. 이 옵션은 다시 시도 횟수를 나타냅니다. recursive 옵션이 true가 아닌 경우 무시됩니다. 기본값: 0.
  • recursive <boolean> true이면 재귀적으로 디렉터리를 제거합니다. 재귀 모드에서는 작업 실패 시 다시 시도됩니다. 기본값: false.
  • retryDelay <integer> 다시 시도 사이에 대기할 시간(밀리초)입니다. recursive 옵션이 true가 아닌 경우 무시됩니다. 기본값: 100.

• 반환값: <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.

• 반환값: <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.

• 반환값: <Promise> 주어진 path에 대한 <fs.StatFs> 객체로 이행됩니다.

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
• 반환값: <Promise> 성공 시 undefined로 이행됩니다.

심볼릭 링크를 만듭니다.

type 인수는 Windows 플랫폼에서만 사용되며 'dir', 'file', 또는 'junction' 중 하나일 수 있습니다. type 인수가 null이면 Node.js는 target 유형을 자동으로 감지하고 'file' 또는 'dir'을 사용합니다. target이 존재하지 않으면 'file'이 사용됩니다. Windows junction 포인트는 대상 경로가 절대 경로여야 합니다. 'junction'을 사용할 때 target 인수는 자동으로 절대 경로로 정규화됩니다. NTFS 볼륨의 Junction 포인트는 디렉토리만 가리킬 수 있습니다.

fsPromises.truncate(path[, len])

추가됨: v10.0.0

• path <string> | <Buffer> | <URL>
• len <integer> 기본값: 0
• 반환값: <Promise> 성공 시 undefined를 반환합니다.

path의 콘텐츠 길이를 len 바이트로 잘라냅니다(또는 길이를 늘립니다).

fsPromises.unlink(path)

추가됨: v10.0.0

• path <string> | <Buffer> | <URL>
• 반환값: <Promise> 성공 시 undefined를 반환합니다.

path가 심볼릭 링크를 참조하는 경우, 링크가 제거되지만 링크가 참조하는 파일이나 디렉토리에는 영향을 미치지 않습니다. path가 심볼릭 링크가 아닌 파일 경로를 참조하는 경우, 파일이 삭제됩니다. 자세한 내용은 POSIX unlink(2) 설명서를 참조하십시오.

fsPromises.utimes(path, atime, mtime)

추가됨: 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가 throw됩니다.

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	options 인수에 진행 중인 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를 throw합니다.
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 ? '이 존재하지 않습니다' : '이 존재합니다'}`)
})

// 파일이 읽기 가능한지 확인합니다.
access(file, constants.R_OK, err => {
  console.log(`${file} ${err ? '은 읽을 수 없습니다' : '은 읽을 수 있습니다'}`)
})

// 파일이 쓰기 가능한지 확인합니다.
access(file, constants.W_OK, err => {
  console.log(`${file} ${err ? '은 쓸 수 없습니다' : '은 쓸 수 있습니다'}`)
})

// 파일이 읽기 및 쓰기 가능한지 확인합니다.
access(file, constants.R_OK | constants.W_OK, err => {
  console.log(`${file} ${err ? '은' : '은'} 읽기 및 쓰기 가능합니다`)
})

fs.open(), fs.readFile() 또는 fs.writeFile()를 호출하기 전에 파일의 접근성을 확인하기 위해 fs.access()를 사용하지 마십시오. 그렇게 하면 두 호출 사이에 다른 프로세스가 파일의 상태를 변경할 수 있으므로 경합 상태가 발생합니다. 대신 사용자 코드는 파일을 직접 열고/읽고/쓰고 파일을 액세스할 수 없는 경우 발생하는 오류를 처리해야 합니다.

쓰기(권장하지 않음)

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

access('myfile', err => {
  if (!err) {
    console.error('myfile은 이미 존재합니다')
    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은 이미 존재합니다')
      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이 존재하지 않습니다')
      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이 존재하지 않습니다')
      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가 throw됩니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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', 'data to append', err => {
  if (err) throw err
  console.log('The "data to append" was appended to file!')
})

options가 문자열이면 인코딩을 지정합니다.

import { appendFile } from 'node:fs'

appendFile('message.txt', 'data to append', '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, 'data to append', '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를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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('The permissions for file "my_file.txt" have been changed!')
})

파일 모드

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를 구성하는 더 쉬운 방법은 세 개의 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)

[History]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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])

[History]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v15.9.0, v14.17.0	콜백이 제공되지 않으면 이제 기본 콜백이 사용됩니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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를 throw합니다.
v14.0.0	flags 인수를 mode로 변경하고 보다 엄격한 형식 유효성 검사를 적용했습니다.
v8.5.0	추가됨: v8.5.0

• src <문자열> | <버퍼> | <URL> 복사할 소스 파일 이름
• dest <문자열> | <버퍼> | <URL> 복사 작업의 대상 파일 이름
• mode <정수> 복사 작업에 대한 수정자. 기본값: 0.
• callback <함수>
  • err <오류>

src를 dest로 비동기적으로 복사합니다. 기본적으로 dest가 이미 존재하는 경우 덮어씁니다. 콜백 함수에는 가능한 예외를 제외하고는 다른 인수가 제공되지 않습니다. Node.js는 복사 작업의 원자성에 대해 보장하지 않습니다. 대상 파일을 쓰기 위해 열린 후 오류가 발생하면 Node.js는 대상을 제거하려고 시도합니다.

mode는 복사 작업의 동작을 지정하는 선택적 정수입니다. 두 개 이상의 값의 비트 단위 OR로 구성된 마스크를 만들 수 있습니다(예: fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: dest가 이미 존재하는 경우 복사 작업이 실패합니다.
• fs.constants.COPYFILE_FICLONE: 복사 작업은 쓰기 시 복사 reflink를 만들려고 시도합니다. 플랫폼이 쓰기 시 복사를 지원하지 않는 경우 대체 복사 메커니즘이 사용됩니다.
• fs.constants.COPYFILE_FICLONE_FORCE: 복사 작업은 쓰기 시 복사 reflink를 만들려고 시도합니다. 플랫폼이 쓰기 시 복사를 지원하지 않는 경우 작업이 실패합니다.

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를 throw합니다.
v17.6.0, v16.15.0	심볼릭 링크에 대한 경로 확인 여부를 지정하는 추가 verbatimSymlinks 옵션을 허용합니다.
v16.7.0	추가됨: v16.7.0

• src <문자열> | <URL> 복사할 소스 경로.

• dest <문자열> | <URL> 복사할 대상 경로.

• options <객체>

  • dereference <불리언> 심볼릭 링크를 역참조합니다. 기본값: false.

  • errorOnExist <불리언> force가 false이고 대상이 이미 존재하는 경우, 에러를 throw합니다. 기본값: false.

  • filter <함수> 복사할 파일/디렉토리를 필터링하는 함수. 항목을 복사하려면 true를, 무시하려면 false를 반환합니다. 디렉토리를 무시하면 해당 디렉토리의 모든 내용도 건너뜁니다. true 또는 false로 해결되는 Promise를 반환할 수도 있습니다. 기본값: undefined.

  • src <문자열> 복사할 소스 경로.

  • dest <문자열> 복사할 대상 경로.

  • 반환값: <불리언> | <Promise> boolean으로 강제 변환될 수 있는 값 또는 그러한 값으로 이행되는 Promise.

  • force <불리언> 기존 파일 또는 디렉토리를 덮어씁니다. 이 옵션을 false로 설정하고 대상이 이미 존재하는 경우 복사 작업은 에러를 무시합니다. errorOnExist 옵션을 사용하여 이 동작을 변경할 수 있습니다. 기본값: true.

  • mode <정수> 복사 작업에 대한 수정자. 기본값: 0. fs.copyFile()의 mode 플래그를 참조하십시오.

  • preserveTimestamps <불리언> true인 경우 src의 타임스탬프가 유지됩니다. 기본값: false.

  • recursive <불리언> 디렉토리를 재귀적으로 복사합니다. 기본값: false

  • verbatimSymlinks <불리언> true인 경우 심볼릭 링크에 대한 경로 확인을 건너뜁니다. 기본값: false

• callback <함수>

  • err <Error>

하위 디렉토리와 파일을 포함하여 src에서 dest로 전체 디렉토리 구조를 비동기적으로 복사합니다.

디렉토리를 다른 디렉토리에 복사할 때는 glob이 지원되지 않으며 cp dir1/ dir2/와 유사한 동작을 합니다.

fs.createReadStream(path[, options])

[히스토리]

버전	변경 사항
v16.10.0	fs 옵션은 fd가 제공된 경우 open 메서드가 필요하지 않습니다.
v16.10.0	fs 옵션은 autoClose가 false인 경우 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] 범위 내에 있습니다. 파일을 바꾸는 대신 수정하려면 기본값인 w 대신 flags 옵션을 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를 throw합니다.
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 <문자열> | <버퍼> | <URL>
• callback <함수>
  • exists <불리언>

파일 시스템을 확인하여 주어진 path에 있는 요소가 존재하는지 여부를 테스트합니다. 그런 다음 true 또는 false를 사용하여 callback 인수를 호출합니다.

import { exists } from 'node:fs'

exists('/etc/passwd', e => {
  console.log(e ? 'it exists' : 'no passwd!')
})

이 콜백의 매개변수는 다른 Node.js 콜백과 일치하지 않습니다. 일반적으로 Node.js 콜백의 첫 번째 매개변수는 err 매개변수이며, 필요에 따라 다른 매개변수가 뒤따릅니다. fs.exists() 콜백에는 불리언 매개변수 하나만 있습니다. 이것이 fs.access()를 fs.exists() 대신 권장하는 한 가지 이유입니다.

path가 심볼릭 링크인 경우, 이 링크를 따라갑니다. 따라서 path가 존재하지만 존재하지 않는 요소를 가리키는 경우 콜백은 false 값을 받습니다.

fs.open(), fs.readFile() 또는 fs.writeFile()를 호출하기 전에 파일의 존재 여부를 확인하기 위해 fs.exists()를 사용하는 것은 권장하지 않습니다. 두 호출 사이에 다른 프로세스가 파일의 상태를 변경할 수 있으므로 경합 조건이 발생합니다. 대신 사용자 코드는 파일을 직접 열고/읽고/쓰고 파일이 존재하지 않는 경우 발생하는 오류를 처리해야 합니다.

쓰기 (권장하지 않음)

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

exists('myfile', e => {
  if (e) {
    console.error('myfile already exists')
  } 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 already exists')
      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 does not exist')
  }
})

읽기 (권장)

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
    })
  }
})

위의 "권장하지 않음" 예제는 존재 여부를 확인한 다음 파일을 사용합니다. "권장" 예제는 파일을 직접 사용하고 오류가 있는 경우 처리하므로 더 좋습니다.

일반적으로 파일을 직접 사용하지 않는 경우에만 파일의 존재 여부를 확인하십시오. 예를 들어 다른 프로세스의 신호인 경우입니다.

fs.fchmod(fd, mode, callback)

[History]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수는 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수는 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID DEP0013으로 사용 중지 경고가 발생합니다.
v0.4.7	추가됨: v0.4.7

• fd <정수>
• mode <문자열> | <정수>
• callback <함수>
  • err <Error>

파일의 권한을 설정합니다. 완료 콜백에는 가능한 예외 외에는 다른 인수가 제공되지 않습니다.

자세한 내용은 POSIX fchmod(2) 문서를 참조하십시오.

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

[History]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수는 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수는 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID DEP0013으로 사용 중지 경고가 발생합니다.
v0.4.7	추가됨: v0.4.7

• fd <정수>
• uid <정수>
• gid <정수>
• callback <함수>
  • err <Error>

파일의 소유자를 설정합니다. 완료 콜백에는 가능한 예외 외에는 다른 인수가 제공되지 않습니다.

자세한 내용은 POSIX fchown(2) 문서를 참조하십시오.

fs.fdatasync(fd, callback)

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 사용 중단 경고가 발생합니다.
v0.1.96	추가됨: v0.1.96

• fd <정수>
• callback <함수>
  • err <오류>

파일과 연관된 현재 대기 중인 모든 I/O 작업을 운영 체제의 동기화된 I/O 완료 상태로 강제합니다. 자세한 내용은 POSIX fdatasync(2) 설명서를 참조하십시오. 완료 콜백에는 가능한 예외 외에는 인수가 제공되지 않습니다.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.5.0	반환되는 숫자 값이 bigint인지 여부를 지정하는 추가 options 객체를 허용합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 사용 중단 경고가 발생합니다.
v0.1.95	추가됨: v0.1.95

• fd <정수>

• options <객체>

  • bigint <불리언> 반환된 <fs.Stats> 객체의 숫자 값이 bigint이어야 하는지 여부입니다. 기본값: false.

• callback <함수>

  • err <오류>
  • stats <fs.Stats>

파일 디스크립터에 대한 <fs.Stats>를 사용하여 콜백을 호출합니다.

자세한 내용은 POSIX fstat(2) 설명서를 참조하십시오.

fs.fsync(fd, callback)

[History]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 사용 중단 경고가 발생합니다.
v0.1.96	추가됨: v0.1.96

• fd <정수>
• callback <함수>
  • err <Error>

열린 파일 디스크립터의 모든 데이터가 저장 장치에 플러시되도록 요청합니다. 구체적인 구현은 운영 체제 및 장치에 따라 다릅니다. 자세한 내용은 POSIX fsync(2) 문서를 참조하십시오. 완료 콜백에는 가능한 예외 외에는 인수가 제공되지 않습니다.

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

[History]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 사용 중단 경고가 발생합니다.
v0.8.6	추가됨: v0.8.6

• fd <정수>
• len <정수> 기본값: 0
• callback <함수>
  • err <Error>

파일 디스크립터를 잘라냅니다. 완료 콜백에는 가능한 예외 외에는 인수가 제공되지 않습니다.

자세한 내용은 POSIX ftruncate(2) 문서를 참조하십시오.

파일 디스크립터가 참조하는 파일이 len 바이트보다 큰 경우 파일의 처음 len 바이트만 유지됩니다.

예를 들어 다음 프로그램은 파일의 처음 네 바이트만 유지합니다.

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 바이트보다 짧았던 경우 확장되고 확장된 부분은 null 바이트('\0')로 채워집니다.

len이 음수이면 0이 사용됩니다.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 사용 중단 경고가 발생합니다.
v4.1.0	숫자 문자열, NaN 및 Infinity가 이제 허용되는 시간 지정자입니다.
v0.4.2	추가됨: v0.4.2

• fd <정수>
• atime <숫자> | <문자열> | <Date>
• mtime <숫자> | <문자열> | <Date>
• callback <함수>
  • err <Error>

제공된 파일 디스크립터가 참조하는 객체의 파일 시스템 타임스탬프를 변경합니다. fs.utimes()를 참조하십시오.

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

[히스토리]

버전	변경 사항
v22.2.0	withFileTypes를 옵션으로 지원합니다.
v22.0.0	추가됨: v22.0.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

• pattern <문자열> | <문자열[]>

• options <객체>

  • cwd <문자열> 현재 작업 디렉토리. 기본값: process.cwd()
  • exclude <함수> 파일/디렉토리를 필터링하는 함수. 항목을 제외하려면 true를 반환하고, 포함하려면 false를 반환합니다. 기본값: undefined.
  • withFileTypes <불리언> glob이 경로를 Dirent로 반환해야 하는 경우 true, 그렇지 않으면 false. 기본값: false.

• callback <함수>

  • 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를 throw합니다.
v16.0.0	두 개 이상의 오류가 반환되는 경우 반환되는 오류가 AggregateError일 수 있습니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 사용 중지 경고가 발생합니다.
v0.4.7	사용 중지됨: v0.4.7

• path <문자열> | <버퍼> | <URL>
• mode <정수>
• callback <함수>
  • err <오류> | <AggregateError>

심볼릭 링크의 권한을 변경합니다. 완료 콜백에는 가능한 예외를 제외하고 다른 인수가 제공되지 않습니다.

이 메서드는 macOS에서만 구현됩니다.

자세한 내용은 POSIX lchmod(2) 설명서를 참조하십시오.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.6.0	이 API는 더 이상 사용되지 않습니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 사용 중지 경고가 발생합니다.
v0.4.7	설명서에서만 사용 중지됨.

• path <문자열> | <버퍼> | <URL>
• uid <정수>
• gid <정수>
• callback <함수>
  • err <오류>

심볼릭 링크의 소유자를 설정합니다. 완료 콜백에는 가능한 예외를 제외하고 다른 인수가 제공되지 않습니다.

자세한 내용은 POSIX lchown(2) 설명서를 참조하십시오.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v14.5.0, v12.19.0	추가됨: v14.5.0, v12.19.0

• path <문자열> | <버퍼> | <URL>
• atime <숫자> | <문자열> | <날짜>
• mtime <숫자> | <문자열> | <날짜>
• callback <함수>
  • err <오류>

fs.utimes()[/api/fs#fsutimespath-atime-mtime-callback]와 같은 방식으로 파일의 접근 시간과 수정 시간을 변경하지만, 경로가 심볼릭 링크를 참조하는 경우 심볼릭 링크 자체의 타임스탬프가 변경됩니다. 심볼릭 링크가 해제되지 않습니다.

완료 콜백에는 가능한 예외 외에는 인수가 제공되지 않습니다.

fs.link(existingPath, newPath, callback)

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.6.0	existingPath 및 newPath 매개변수는 file: 프로토콜을 사용하는 WHATWG URL 객체일 수 있습니다. 현재 지원은 여전히 실험적입니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 사용 중단 경고가 발생합니다.
v0.1.31	추가됨: v0.1.31

• existingPath <문자열> | <버퍼> | <URL>
• newPath <문자열> | <버퍼> | <URL>
• callback <함수>
  • err <오류>

existingPath에서 newPath로 새로운 링크를 만듭니다. 자세한 내용은 POSIX link(2) 설명서를 참조하십시오. 완료 콜백에는 가능한 예외 외에는 인수가 제공되지 않습니다.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.5.0	반환된 숫자 값이 bigint인지 여부를 지정하는 추가 options 객체를 허용합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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)라는 두 개의 인수를 가져오는데, 여기서 stats는 <fs.Stats> 객체입니다. lstat()은 stat()과 동일하지만, path가 심볼릭 링크인 경우 링크 자체가 stat되고, 참조하는 파일이 stat되지 않습니다.

자세한 내용은 POSIX lstat(2) 설명서를 참조하십시오.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v13.11.0, v12.17.0	recursive 모드에서 콜백은 이제 처음 생성된 경로를 인수로 받습니다.
v10.12.0	두 번째 인수는 이제 recursive 및 mode 속성이 있는 options 객체가 될 수 있습니다.
v10.0.0	callback 매개변수는 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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로 설정된 경우 디렉토리가 생성되면 나타납니다. 디렉토리가 생성되지 않은 경우(예: 이전에 생성된 경우)에도 undefined일 수 있습니다.

비동기적으로 디렉토리를 생성합니다.

콜백에는 가능한 예외가 제공되고, recursive가 true인 경우 처음 생성된 디렉토리 경로 (err[, path])가 제공됩니다. recursive가 true이고 디렉토리가 생성되지 않은 경우(예: 이전에 생성된 경우) path는 여전히 undefined일 수 있습니다.

선택적 options 인수는 mode(권한 및 고정 비트)를 지정하는 정수 또는 mode 속성과 상위 디렉토리를 생성할지 여부를 나타내는 recursive 속성이 있는 객체가 될 수 있습니다. path가 이미 존재하는 디렉토리이고 recursive가 false인 경우 fs.mkdir()를 호출하면 오류가 발생합니다. 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를 throw합니다.
v16.5.0, v14.18.0	prefix 매개변수가 이제 빈 문자열을 허용합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 사용 중단 경고가 발생합니다.
v6.2.1	callback 매개변수가 이제 선택 사항입니다.
v5.10.0	추가됨: v5.10.0

• prefix <문자열> | <버퍼> | <URL>

• options <문자열> | <객체>

  • encoding <문자열> 기본값: 'utf8'

• callback <함수>

  • err <오류>
  • directory <문자열>

고유한 임시 디렉토리를 만듭니다.

고유한 임시 디렉토리를 만들기 위해 필요한 prefix 뒤에 추가될 6자의 임의 문자를 생성합니다. 플랫폼의 일관성이 없으므로 prefix의 후행 X 문자는 피하십시오. 특히 BSD와 같은 일부 플랫폼에서는 6자 이상의 임의 문자를 반환하고 prefix의 후행 X 문자를 임의 문자로 바꿀 수 있습니다.

만들어진 디렉토리 경로는 문자열로 콜백의 두 번째 매개변수로 전달됩니다.

선택적 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)
  // /tmp/foo-itXde2 또는 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를 throw합니다.
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 지원 참조 [/api/fs#file-system-flags]. 기본값: 'r'.
• mode <string> | <integer> 기본값: 0o666 (읽기 및 쓰기 가능)
• callback <Function>
  • err <Error>
  • fd <integer>

비동기 파일 열기. 자세한 내용은 POSIX open(2) 문서를 참조하십시오.

mode는 파일 모드(권한 및 고정 비트)를 설정하지만 파일이 생성된 경우에만 설정됩니다. Windows에서는 쓰기 권한만 조작할 수 있습니다. fs.chmod() 참조하십시오.

콜백은 두 개의 인수 (err, fd)를 가져옵니다.

일부 문자(\< \> : " / \ | ? *)는 파일, 경로 및 네임스페이스 명명에 설명된 대로 Windows에서 예약되어 있습니다. NTFS에서 파일 이름에 콜론이 포함된 경우 Node.js는 이 MSDN 페이지에 설명된 대로 파일 시스템 스트림을 엽니다.

fs.open()을 기반으로 하는 함수도 이 동작을 나타냅니다. fs.writeFile(), fs.readFile() 등.

fs.openAsBlob(path[, options])

추가됨: v19.8.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

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

• options <Object>

  • type <string> Blob의 선택적 MIME 유형.

• 반환값: <Promise> 성공 시 <Blob>을 반환합니다.

주어진 파일을 백업 데이터로 하는 <Blob>을 반환합니다.

<Blob>이 생성된 후에는 파일을 수정하면 안 됩니다. 수정하면 <Blob> 데이터 읽기가 실패하고 DOMException 오류가 발생합니다. Blob 생성 시 및 각 읽기 전에 파일 데이터가 디스크에서 수정되었는지 감지하기 위해 파일에서 동기적 상태 연산을 수행합니다.

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를 throw합니다.
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를 throw합니다.
v10.10.0	buffer 매개변수는 이제 모든 TypedArray 또는 DataView가 될 수 있습니다.
v7.4.0	buffer 매개변수는 이제 Uint8Array가 될 수 있습니다.
v6.0.0	length 매개변수는 이제 0이 될 수 있습니다.
v0.0.2	추가됨: v0.0.2

• fd <정수>
• buffer <Buffer> | <TypedArray> | <DataView> 데이터가 쓰여질 버퍼입니다.
• offset <정수> 데이터를 쓸 buffer의 위치입니다.
• length <정수> 읽을 바이트 수입니다.
• position <정수> | <bigint> | <null> 파일에서 읽기를 시작할 위치를 지정합니다. position이 null 또는 -1이면 현재 파일 위치에서 데이터를 읽고 파일 위치가 업데이트됩니다. position이 0보다 큰 정수이면 파일 위치는 변경되지 않습니다.
• callback <함수>
  • err <Error>
  • bytesRead <정수>
  • buffer <Buffer>

fd로 지정된 파일에서 데이터를 읽습니다.

콜백에는 (err, bytesRead, buffer)의 세 가지 인수가 제공됩니다.

파일이 동시에 수정되지 않으면 읽은 바이트 수가 0일 때 파일 끝에 도달합니다.

이 메서드가 util.promisify()된 버전으로 호출되면 bytesRead 및 buffer 속성이 있는 Object에 대한 promise를 반환합니다.

fs.read() 메서드는 파일 디스크립터(fd)로 지정된 파일에서 데이터를 읽습니다. length 인수는 Node.js가 커널에서 읽으려고 시도하는 최대 바이트 수를 나타냅니다. 그러나 실제로 읽은 바이트 수(bytesRead)는 다양한 이유로 지정된 length보다 작을 수 있습니다.

예를 들어:

• 파일이 지정된 length보다 짧으면 bytesRead는 실제로 읽은 바이트 수로 설정됩니다.
• 버퍼를 채우기 전에 파일이 EOF(파일 끝)를 만나면 Node.js는 EOF를 만날 때까지 사용 가능한 모든 바이트를 읽고 콜백의 bytesRead 매개변수는 실제로 읽은 바이트 수(지정된 length보다 작을 수 있음)를 나타냅니다.
• 파일이 느린 네트워크 파일 시스템에 있거나 읽는 동안 다른 문제가 발생하면 bytesRead는 지정된 length보다 작을 수 있습니다.

따라서 fs.read()를 사용할 때는 bytesRead 값을 확인하여 실제로 파일에서 읽은 바이트 수를 확인하는 것이 중요합니다. 애플리케이션 로직에 따라 최소 바이트 수가 필요한 경우 읽기 호출을 루프로 래핑하는 등 bytesRead가 지정된 length보다 작은 경우를 처리해야 할 수 있습니다.

이 동작은 POSIX preadv2 함수와 유사합니다.

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

[히스토리]

버전	변경 사항
v13.11.0, v12.17.0	버퍼, 오프셋, 길이 및 위치를 선택적으로 지정할 수 있도록 옵션 객체를 전달할 수 있습니다.
v13.11.0, v12.17.0	추가됨: v13.11.0, v12.17.0

• fd <정수>

• options <객체>

  • buffer <Buffer> | <TypedArray> | <DataView> 기본값: Buffer.alloc(16384)
  • offset <정수> 기본값: 0
  • length <정수> 기본값: buffer.byteLength - offset
  • position <정수> | <bigint> | <null> 기본값: null

• callback <함수>

  • err <Error>
  • bytesRead <정수>
  • 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()(/api/fs#fsreadfd-buffer-offset-length-position-callback) 함수와 유사하게, 이 버전은 선택적 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를 throw합니다.
v10.10.0	새로운 옵션 withFileTypes 추가
v10.0.0	callback 매개변수가 더 이상 선택적이지 않습니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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)의 두 개의 인수를 가져오는데, 여기서 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를 throw합니다.
v16.0.0	두 개 이상의 오류가 반환되면 반환되는 오류가 AggregateError일 수 있습니다.
v15.2.0, v14.17.0	options 인수에 진행 중인 readFile 요청을 중단하기 위한 AbortSignal을 포함할 수 있습니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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 <문자열> | <버퍼> | <URL> | <정수> 파일 이름 또는 파일 디스크립터

• options <객체> | <문자열>

  • encoding <문자열> | <널> 기본값: null
  • flag <문자열> 파일 시스템 flags 지원을 참조하십시오. 기본값: 'r'
  • signal <AbortSignal> 진행 중인 readFile을 중단할 수 있습니다.

• callback <함수>

  • err <오류> | <AggregateError>
  • data <문자열> | <버퍼>

파일의 전체 내용을 비동기적으로 읽습니다.

import { readFile } from 'node:fs'

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

콜백에는 data가 파일의 내용인 두 개의 인수 (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('<directory>', (err, data) => {
  // => [Error: EISDIR: 디렉터리에 대한 불법 작업, <directory> 읽기]
})

// FreeBSD
readFile('<directory>', (err, data) => {
  // => null, <data>
})

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() 메서드는 파일의 내용을 한 번에 한 청크씩 메모리에 비동기적으로 읽어들이므로 이벤트 루프가 각 청크 사이에 전환될 수 있습니다. 이를 통해 읽기 작업이 기본 libuv 스레드 풀을 사용할 수 있는 다른 작업에 미치는 영향을 줄일 수 있지만 전체 파일을 메모리에 읽는 데 시간이 더 오래 걸립니다.

추가적인 읽기 오버헤드는 서로 다른 시스템에서 크게 다를 수 있으며 읽는 파일의 유형에 따라 달라집니다. 파일 유형이 일반 파일이 아니고(예: 파이프) Node.js가 실제 파일 크기를 확인할 수 없는 경우 각 읽기 작업은 64KiB의 데이터를 로드합니다. 일반 파일의 경우 각 읽기는 512KiB의 데이터를 처리합니다.

가능한 한 빠르게 파일 내용을 읽어야 하는 애플리케이션의 경우 fs.read()를 직접 사용하고 애플리케이션 코드에서 파일의 전체 내용을 직접 읽는 것을 관리하는 것이 좋습니다.

Node.js GitHub 이슈 #25741은 다양한 Node.js 버전에서 여러 파일 크기에 대한 fs.readFile()의 성능에 대한 자세한 정보와 분석을 제공합니다.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError를 throw합니다.
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가 참조하는 심볼릭 링크의 내용을 읽습니다. 콜백은 두 개의 인수 (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를 throw합니다.
v13.13.0, v12.17.0	추가됨: v13.13.0, v12.17.0

• fd <정수>
• buffers <ArrayBufferView[]>
• position <정수> | <null> 기본값: null
• callback <함수>
  • err <오류>
  • bytesRead <정수>
  • buffers <ArrayBufferView[]>

fd로 지정된 파일에서 읽고 readv()를 사용하여 ArrayBufferView 배열에 씁니다.

position은 데이터를 읽을 파일의 시작 부분으로부터의 오프셋입니다. typeof position !== 'number'이면 현재 위치에서 데이터를 읽습니다.

콜백에는 err, bytesRead, buffers의 세 가지 인수가 제공됩니다. bytesRead는 파일에서 읽은 바이트 수입니다.

이 메서드가 util.promisify()된 버전으로 호출되면 bytesRead 및 buffers 속성이 있는 Object에 대한 promise를 반환합니다.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v8.0.0	파이프/소켓 확인 지원이 추가되었습니다.
v7.6.0	path 매개변수는 file: 프로토콜을 사용하는 WHATWG URL 객체일 수 있습니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID DEP0013으로 사용 중단 경고가 발생합니다.
v6.4.0	Windows의 다양한 에지 케이스에 대해 realpath 호출이 다시 작동합니다.
v6.0.0	cache 매개변수가 제거되었습니다.
v0.1.31	추가됨: v0.1.31

• path <문자열> | <버퍼> | <URL>

• options <문자열> | <객체>

  • encoding <문자열> 기본값: 'utf8'

• callback <함수>

  • err <오류>
  • resolvedPath <문자열> | <버퍼>

비동기적으로 ., .., 및 심볼릭 링크를 확인하여 정식 경로명을 계산합니다.

정식 경로명은 반드시 고유한 것은 아닙니다. 하드 링크와 바인드 마운트는 여러 경로명을 통해 파일 시스템 엔터티를 노출할 수 있습니다.

이 함수는 일부 예외를 제외하고 realpath(3)과 같이 동작합니다.

callback은 두 개의 인수 (err, resolvedPath)를 가져옵니다. 상대 경로를 확인하는 데 process.cwd를 사용할 수 있습니다.

UTF8 문자열로 변환할 수 있는 경로만 지원됩니다.

선택적 options 인수는 인코딩을 지정하는 문자열이거나 콜백에 전달되는 경로에 사용할 문자 인코딩을 지정하는 encoding 속성이 있는 객체일 수 있습니다. encoding이 'buffer'로 설정되면 반환된 경로는 <버퍼> 객체로 전달됩니다.

path가 소켓이나 파이프로 확인되면 함수는 해당 객체에 대한 시스템 종속 이름을 반환합니다.

존재하지 않는 경로는 ENOENT 오류를 발생시킵니다. error.path는 절대 파일 경로입니다.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
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은 두 개의 인수 (err, resolvedPath)를 받습니다.

UTF8 문자열로 변환할 수 있는 경로만 지원됩니다.

선택적 options 인수는 인코딩을 지정하는 문자열이거나 콜백에 전달된 경로에 사용할 문자 인코딩을 지정하는 encoding 속성이 있는 객체일 수 있습니다. encoding이 'buffer'로 설정되면 반환된 경로는 <Buffer> 객체로 전달됩니다.

Linux에서 Node.js가 musl libc에 링크되어 있으면 이 함수가 작동하려면 /proc에 procfs 파일 시스템을 마운트해야 합니다. Glibc에는 이러한 제한이 없습니다.

fs.rename(oldPath, newPath, callback)

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택적이지 않습니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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를 throw합니다.
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가 throw됩니다.
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 명령과 유사한 동작을 얻으려면 { recursive: true, force: true } 옵션을 사용하여 fs.rm()을 사용하십시오.

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

[히스토리]

버전	변경 사항
v17.3.0, v16.14.0	path 매개변수는 file: 프로토콜을 사용하는 WHATWG URL 객체가 될 수 있습니다.
v14.14.0	추가됨: v14.14.0

• path <문자열> | <버퍼> | <URL>

• options <객체>

  • force <부울> true이면 path가 존재하지 않아도 예외가 무시됩니다. 기본값: false.
  • maxRetries <정수> EBUSY, EMFILE, ENFILE, ENOTEMPTY, 또는 EPERM 오류가 발생하면 Node.js는 각 시도마다 retryDelay 밀리초만큼 선형 백오프 대기 시간을 두고 작업을 다시 시도합니다. 이 옵션은 재시도 횟수를 나타냅니다. recursive 옵션이 true가 아니면 이 옵션은 무시됩니다. 기본값: 0.
  • recursive <부울> true이면 재귀적 제거를 수행합니다. 재귀 모드에서 작업은 실패 시 다시 시도됩니다. 기본값: false.
  • retryDelay <정수> 재시도 사이에 대기할 시간(밀리초)입니다. recursive 옵션이 true가 아니면 이 옵션은 무시됩니다. 기본값: 100.

• callback <함수>

  • err <오류>

비동기적으로 파일과 디렉토리를 제거합니다(표준 POSIX rm 유틸리티를 모델로 함). 완료 콜백에는 가능한 예외 외에는 인수가 제공되지 않습니다.

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

[이력]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.5.0	반환되는 숫자 값이 bigint인지 여부를 지정하는 추가 options 객체를 허용합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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). 콜백은 (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가 포함된 마운트된 파일 시스템에 대한 정보를 반환합니다. 콜백은 stats가 <fs.StatFs> 객체인 (err, stats) 두 개의 인수를 가져옵니다.

오류가 발생하는 경우 err.code는 일반 시스템 오류 중 하나가 됩니다.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE가 throw됩니다.
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 포인트는 대상 경로가 절대 경로여야 합니다. 'junction'을 사용하는 경우 target 인수는 자동으로 절대 경로로 정규화됩니다. NTFS 볼륨의 Junction 포인트는 디렉토리만 가리킬 수 있습니다.

상대 대상은 링크의 상위 디렉토리를 기준으로 합니다.

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를 throw합니다.
v16.0.0	두 개 이상의 오류가 반환되면 반환되는 오류가 AggregateError일 수 있습니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID DEP0013으로 사용 중단 경고가 발생합니다.
v0.8.6	추가됨: v0.8.6

• path <문자열> | <버퍼> | <URL>
• len <정수> 기본값: 0
• callback <함수>
  • err <오류> | <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')
})

파일 디스크립터를 전달하는 것은 사용되지 않으며 나중에 오류가 throw될 수 있습니다.

자세한 내용은 POSIX truncate(2) 문서를 참조하십시오.

fs.unlink(path, callback)

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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 was deleted')
})

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를 throw합니다.
v10.0.0	callback 매개변수가 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
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 <문자열> | <버퍼> | <URL>
• atime <숫자> | <문자열> | <날짜>
• mtime <숫자> | <문자열> | <날짜>
• callback <함수>
  • err <오류>

path가 참조하는 객체의 파일 시스템 타임스탬프를 변경합니다.

atime 및 mtime 인수는 다음 규칙을 따릅니다.

• 값은 초 단위의 Unix 에포크 시간을 나타내는 숫자, Date 또는 '123456789.0'과 같은 숫자 문자열일 수 있습니다.
• 값을 숫자로 변환할 수 없거나 NaN, Infinity 또는 -Infinity인 경우 Error가 throw됩니다.

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

[히스토리]

버전	변경 사항
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 <문자열> | <버퍼> | <URL>

• options <문자열> | <객체>

  • persistent <불리언> 파일이 감시되는 동안 프로세스가 계속 실행될지 여부를 나타냅니다. 기본값: true.
  • recursive <불리언> 모든 하위 디렉토리를 감시할지 아니면 현재 디렉토리만 감시할지 여부를 나타냅니다. 디렉토리가 지정된 경우에만 적용되며, 지원되는 플랫폼에서만 적용됩니다(주의 사항). 기본값: false.
  • encoding <문자열> 리스너에 전달되는 파일 이름에 사용할 문자 인코딩을 지정합니다. 기본값: 'utf8'.
  • signal <AbortSignal> AbortSignal을 사용하여 감시자를 닫을 수 있습니다.

• listener <함수> | <정의되지 않음> 기본값: undefined

  • eventType <문자열>
  • filename <문자열> | <버퍼> | <널>

• 반환값: <fs.FSWatcher>

filename에서 변경 사항을 감시합니다. 여기서 filename은 파일 또는 디렉토리입니다.

두 번째 인수는 선택 사항입니다. options가 문자열로 제공되면 encoding을 지정합니다. 그렇지 않으면 options를 객체로 전달해야 합니다.

리스너 콜백은 두 개의 인수 (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 포함)에서는 이벤트 포트를 사용합니다.
• Windows 시스템에서는 ReadDirectoryChangesW에 따라 달라집니다.
• AIX 시스템에서는 사용하도록 설정해야 하는 AHAFS에 따라 달라집니다.
• IBM i 시스템에서는 이 기능을 지원하지 않습니다.

기본 기능을 사용할 수 없는 경우 fs.watch()가 작동하지 않고 예외를 throw할 수 있습니다. 예를 들어, Vagrant 또는 Docker와 같은 가상화 소프트웨어를 사용할 때 네트워크 파일 시스템(NFS, SMB 등) 또는 호스트 파일 시스템에서 파일이나 디렉토리를 감시하는 것은 신뢰할 수 없고, 어떤 경우에는 불가능할 수 있습니다.

stat 폴링을 사용하는 fs.watchFile()을 사용할 수는 있지만, 이 방법은 느리고 신뢰성이 떨어집니다.

inode

Linux 및 macOS 시스템에서 fs.watch()는 경로를 inode로 확인하고 inode를 감시합니다. 감시 대상 경로가 삭제되고 다시 생성되면 새 inode가 할당됩니다. 감시는 삭제에 대한 이벤트를 방출하지만 원래 inode를 계속 감시합니다. 새 inode에 대한 이벤트는 방출되지 않습니다. 이것은 예상되는 동작입니다.

AIX 파일은 파일의 수명 동안 동일한 inode를 유지합니다. AIX에서 감시되는 파일을 저장하고 닫으면 두 개의 알림(새 콘텐츠 추가에 대한 알림 하나, 잘림에 대한 알림 하나)이 발생합니다.

파일 이름 인수

콜백에서 filename 인수를 제공하는 것은 Linux, macOS, Windows 및 AIX에서만 지원됩니다. 지원되는 플랫폼에서도 filename이 항상 제공된다는 보장은 없습니다. 따라서 콜백에서 filename 인수가 항상 제공된다고 가정하지 말고, null인 경우 대비하여 대체 로직을 구현해야 합니다.

import { watch } from 'node:fs'
watch('somedir', (eventType, filename) => {
  console.log(`이벤트 유형은: ${eventType}`)
  if (filename) {
    console.log(`파일 이름 제공됨: ${filename}`)
  } else {
    console.log('파일 이름 제공되지 않음')
  }
})

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는 현재 상태 객체와 이전 상태 객체라는 두 개의 인수를 받습니다.

import { watchFile } from 'node:fs'

watchFile('message.text', (curr, prev) => {
  console.log(`현재 mtime은: ${curr.mtime}`)
  console.log(`이전 mtime은: ${prev.mtime}`)
})

이러한 상태 객체는 fs.Stat의 인스턴스입니다. bigint 옵션이 true이면 이러한 객체의 숫자 값은 BigInt로 지정됩니다.

파일이 액세스된 것이 아니라 수정되었을 때 알림을 받으려면 curr.mtimeMs와 prev.mtimeMs를 비교해야 합니다.

fs.watchFile 작업으로 ENOENT 오류가 발생하면 모든 필드가 0으로 설정된(또는 날짜의 경우 Unix Epoch) 상태로 리스너가 한 번 호출됩니다. 나중에 파일이 생성되면 최신 상태 객체를 사용하여 리스너가 다시 호출됩니다. 이는 v0.10 이후의 기능 변경 사항입니다.

fs.watch()를 사용하는 것이 fs.watchFile 및 fs.unwatchFile보다 효율적입니다. 가능하면 fs.watchFile 및 fs.unwatchFile 대신 fs.watch를 사용해야 합니다.

fs.watchFile()에서 관찰 중인 파일이 사라졌다가 다시 나타나면 두 번째 콜백 이벤트(파일의 재등장)의 previous 내용은 첫 번째 콜백 이벤트(사라짐)의 previous 내용과 같습니다.

이는 다음과 같은 경우에 발생합니다.

• 파일이 삭제된 후 복원됨
• 파일의 이름이 변경된 후 원래 이름으로 다시 변경됨

fs.write(fd, buffer, offset[, length[, position]], callback)

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v14.0.0	buffer 매개변수는 더 이상 지원되지 않는 입력을 문자열로 강제 변환하지 않습니다.
v10.10.0	buffer 매개변수는 이제 모든 TypedArray 또는 DataView가 될 수 있습니다.
v10.0.0	callback 매개변수는 더 이상 선택 사항이 아닙니다. 전달하지 않으면 런타임에 TypeError가 throw됩니다.
v7.4.0	buffer 매개변수는 이제 Uint8Array가 될 수 있습니다.
v7.2.0	offset 및 length 매개변수는 이제 선택 사항입니다.
v7.0.0	callback 매개변수는 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 사용 중단 경고가 발생합니다.
v0.0.2	추가됨: v0.0.2

• fd <정수>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <정수> 기본값: 0
• length <정수> 기본값: buffer.byteLength - offset
• position <정수> | <null> 기본값: null
• callback <함수>
  • err <Error>
  • bytesWritten <정수>
  • buffer <Buffer> | <TypedArray> | <DataView>

fd로 지정된 파일에 buffer를 씁니다.

offset은 쓰려는 버퍼의 부분을 결정하고, length는 쓸 바이트 수를 지정하는 정수입니다.

position은 이 데이터를 쓸 파일의 시작 부분으로부터의 오프셋을 나타냅니다. typeof position !== 'number'이면 데이터는 현재 위치에 쓰여집니다. pwrite(2)를 참조하십시오.

콜백에는 (err, bytesWritten, buffer)의 세 가지 인수가 제공되며, 여기서 bytesWritten은 buffer에서 쓰여진 바이트 수를 지정합니다.

이 메서드가 util.promisify()된 버전으로 호출되면 bytesWritten 및 buffer 속성이 있는 Object에 대한 Promise를 반환합니다.

콜백을 기다리지 않고 동일한 파일에 여러 번 fs.write()를 사용하는 것은 안전하지 않습니다. 이 시나리오의 경우 fs.createWriteStream()을 권장합니다.

Linux에서 파일이 추가 모드로 열리면 위치 지정 쓰기가 작동하지 않습니다. 커널은 위치 인수를 무시하고 항상 데이터를 파일 끝에 추가합니다.

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

추가됨: v18.3.0, v16.17.0

• fd <정수>

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

• options <객체>

  • offset <정수> 기본값: 0
  • length <정수> 기본값: buffer.byteLength - offset
  • position <정수> 기본값: null

• callback <함수>

  • err <Error>
  • bytesWritten <정수>
  • buffer <Buffer> | <TypedArray> | <DataView>

fd로 지정된 파일에 buffer를 씁니다.

위의 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 <정수>
• string <문자열>
• position <정수> | <null> 기본값: null
• encoding <문자열> 기본값: 'utf8'
• callback <함수>
  • err <Error>
  • written <정수>
  • string <문자열>

fd로 지정된 파일에 string을 씁니다. 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가 throw됩니다.
v17.8.0	자체 toString 함수를 가진 객체를 string 매개변수에 전달하는 것이 deprecated되었습니다.
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가 throw됩니다.
v7.4.0	data 매개변수는 이제 Uint8Array일 수 있습니다.
v7.0.0	callback 매개변수는 더 이상 선택 사항이 아닙니다. 전달하지 않으면 ID가 DEP0013인 deprecation 경고가 발생합니다.
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()을 고려하십시오.

fs.writeFile()을 취소하기 위해 <AbortSignal>을 사용할 수 있습니다. 취소는 "최선을 다하는" 것이며, 어느 정도의 데이터는 여전히 기록될 가능성이 높습니다.

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()를 연속해서 두 번 호출하여 먼저 문자열 'Hello'를 기록한 다음 문자열 ', World'를 기록하면 파일에는 'Hello, World'가 포함되며 파일의 원래 데이터 중 일부가 포함될 수 있습니다(원래 파일의 크기와 파일 디스크립터의 위치에 따라 다름). 디스크립터 대신 파일 이름을 사용했다면 파일에는 ', World'만 포함되는 것이 보장됩니다.

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

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 이제 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
v12.9.0	추가됨: v12.9.0

• fd <정수>
• buffers <ArrayBufferView[]>
• position <정수> | <null> 기본값: null
• callback <함수>
  • err <오류>
  • bytesWritten <정수>
  • buffers <ArrayBufferView[]>

writev()를 사용하여 fd로 지정된 파일에 ArrayBufferView 배열을 기록합니다.

position은 이 데이터를 기록할 파일 시작 부분으로부터의 오프셋입니다. typeof position !== 'number'이면 데이터는 현재 위치에 기록됩니다.

콜백에는 err, bytesWritten, buffers의 세 가지 인수가 제공됩니다. bytesWritten은 buffers에서 기록된 바이트 수입니다.

이 메서드가 util.promisify()된 경우 bytesWritten 및 buffers 속성이 있는 Object에 대한 약속을 반환합니다.

콜백을 기다리지 않고 같은 파일에 여러 번 fs.writev()를 사용하는 것은 안전하지 않습니다. 이러한 시나리오에서는 fs.createWriteStream()을 사용하십시오.

Linux에서는 파일이 추가 모드로 열려 있으면 위치 기반 쓰기가 작동하지 않습니다. 커널은 위치 인수를 무시하고 항상 데이터를 파일 끝에 추가합니다.

동기 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가 throw됩니다. 그렇지 않으면 메서드는 undefined를 반환합니다.

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

try {
  accessSync('etc/passwd', constants.R_OK | constants.W_OK)
  console.log('읽기/쓰기 가능')
} catch (err) {
  console.error('접근 불가!')
}

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> 파일 시스템 flags 지원을 참조하십시오. 기본값: 'a'.
  • flush <boolean> true이면 기본 파일 디스크립터는 닫기 전에 플러시됩니다. 기본값: false.

파일 끝에 데이터를 동기적으로 추가하고, 파일이 아직 존재하지 않으면 파일을 만듭니다. data는 문자열 또는 <Buffer>일 수 있습니다.

mode 옵션은 새로 생성된 파일에만 영향을 미칩니다. 자세한 내용은 fs.open()을 참조하십시오.

import { appendFileSync } from 'node:fs'

try {
  appendFileSync('message.txt', 'data to append')
  console.log('파일 끝에 "data to append"가 추가되었습니다!')
} 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 <문자열> | <버퍼> | <URL>
• mode <문자열> | <정수>

자세한 내용은 이 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 <문자열> | <버퍼> | <URL>
• uid <정수>
• gid <정수>

동기적으로 파일의 소유자와 그룹을 변경합니다. undefined를 반환합니다. 이것은 fs.chown()의 동기 버전입니다.

자세한 내용은 POSIX chown(2) 설명서를 참조하십시오.

fs.closeSync(fd)

추가됨: v0.1.21

• fd <정수>

파일 디스크립터를 닫습니다. 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 <문자열> | <버퍼> | <URL> 복사할 원본 파일 이름
• dest <문자열> | <버퍼> | <URL> 복사 작업의 대상 파일 이름
• mode <정수> 복사 작업에 대한 수정자. 기본값: 0.

src를 dest로 동기적으로 복사합니다. 기본적으로 dest가 이미 존재하면 덮어씁니다. undefined를 반환합니다. Node.js는 복사 작업의 원자성에 대해 보장하지 않습니다. 대상 파일을 쓰기 위해 열린 후 오류가 발생하면 Node.js는 대상을 제거하려고 시도합니다.

mode는 복사 작업의 동작을 지정하는 선택적 정수입니다. 두 개 이상의 값의 비트 OR로 구성된 마스크를 만들 수 있습니다(예: fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL: dest가 이미 존재하는 경우 복사 작업이 실패합니다.
• fs.constants.COPYFILE_FICLONE: 복사 작업은 복사본 작성 reflink를 만들려고 시도합니다. 플랫폼이 복사본 작성을 지원하지 않는 경우 대체 복사 메커니즘을 사용합니다.
• fs.constants.COPYFILE_FICLONE_FORCE: 복사 작업은 복사본 작성 reflink를 만들려고 시도합니다. 플랫폼이 복사본 작성을 지원하지 않는 경우 작업이 실패합니다.

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 <문자열> | <URL> 복사할 소스 경로.

• dest <문자열> | <URL> 복사할 대상 경로.

• options <객체>

  • dereference <불리언> 심볼릭 링크의 참조를 해제합니다. 기본값: false.

  • errorOnExist <불리언> force가 false이고 대상이 이미 존재하는 경우 오류를 발생시킵니다. 기본값: false.

  • filter <함수> 복사된 파일/디렉토리를 필터링하는 함수입니다. 항목을 복사하려면 true를, 무시하려면 false를 반환합니다. 디렉토리를 무시하면 해당 디렉토리의 모든 내용도 건너뜁니다. 기본값: undefined

  • src <문자열> 복사할 소스 경로.

  • dest <문자열> 복사할 대상 경로.

  • 반환값: <불리언> boolean으로 강제 변환 가능한 비Promise 값.

  • force <불리언> 기존 파일이나 디렉토리를 덮어씁니다. 이 값을 false로 설정하고 대상이 이미 존재하는 경우 복사 작업은 오류를 무시합니다. errorOnExist 옵션을 사용하여 이 동작을 변경할 수 있습니다. 기본값: true.

  • mode <정수> 복사 작업에 대한 수정자. 기본값: 0. fs.copyFileSync()의 mode 플래그를 참조하십시오.

  • preserveTimestamps <불리언> true이면 src의 타임스탬프가 유지됩니다. 기본값: false.

  • recursive <불리언> 디렉토리를 재귀적으로 복사합니다. 기본값: false

  • verbatimSymlinks <불리언> 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('경로가 존재합니다.')

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 <정수>
• atime <숫자> | <문자열> | <Date>
• mtime <숫자> | <문자열> | <Date>

fs.futimes()의 동기 버전입니다. undefined를 반환합니다.

fs.globSync(pattern[, options])

[히스토리]

버전	변경 사항
v22.2.0	withFileTypes를 옵션으로 지원 추가
v22.0.0	추가됨: v22.0.0

[안정성: 1 - 실험적]

안정성: 1 안정성: 1 - 실험적

• pattern <문자열> | <문자열[]>

• options <객체>

  • cwd <문자열> 현재 작업 디렉토리. 기본값: process.cwd()
  • exclude <함수> 파일/디렉토리를 필터링하는 함수. 항목을 제외하려면 true를, 포함하려면 false를 반환합니다. 기본값: undefined.
  • withFileTypes <불리언> glob이 경로를 Dirent로 반환해야 하는 경우 true, 그렇지 않으면 false. 기본값: false.

• 반환값: <문자열[]> 패턴과 일치하는 파일의 경로.

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.

path의 소유자를 설정합니다. 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를 반환하거나 예외를 throw합니다. 이는 fs.lutimes()의 동기 버전입니다.

fs.linkSync(existingPath, newPath)

[히스토리]

버전	변경 사항
v7.6.0	existingPath 및 newPath 매개변수는 file: 프로토콜을 사용하는 WHATWG URL 객체가 될 수 있습니다. 현재 지원은 실험적입니다.
v0.1.31	추가됨: v0.1.31

• existingPath <문자열> | <버퍼> | <URL>
• newPath <문자열> | <버퍼> | <URL>

existingPath에서 newPath로 새로운 링크를 만듭니다. 자세한 내용은 POSIX link(2) 문서를 참조하십시오. undefined를 반환합니다.

fs.lstatSync(path[, options])

[히스토리]

버전	변경 사항
v15.3.0, v14.17.0	항목이 존재하지 않는 경우 예외를 throw할지 여부를 지정하는 throwIfNoEntry 옵션을 허용합니다.
v10.5.0	반환되는 숫자 값이 bigint여야 하는지 여부를 지정하는 추가 options 객체를 허용합니다.
v7.6.0	path 매개변수는 file: 프로토콜을 사용하는 WHATWG URL 객체가 될 수 있습니다.
v0.1.30	추가됨: v0.1.30

• path <문자열> | <버퍼> | <URL>

• options <객체>

  • bigint <불리언> 반환된 <fs.Stats> 객체의 숫자 값이 bigint이어야 하는지 여부입니다. 기본값: false.
  • throwIfNoEntry <불리언> 파일 시스템 항목이 존재하지 않는 경우 undefined를 반환하는 대신 예외를 throw할지 여부입니다. 기본값: true.

• 반환값: <fs.Stats>

path가 참조하는 심볼릭 링크에 대한 <fs.Stats>를 검색합니다.

자세한 내용은 POSIX lstat(2) 문서를 참조하십시오.

fs.mkdirSync(path[, options])

[히스토리]

버전	변경 사항
v13.11.0, v12.17.0	recursive 모드에서 처음 생성된 경로가 반환됩니다.
v10.12.0	두 번째 인수가 recursive 및 mode 속성을 가진 options 객체가 될 수 있습니다.
v7.6.0	path 매개변수는 file: 프로토콜을 사용하는 WHATWG URL 객체가 될 수 있습니다.
v0.1.21	추가됨: v0.1.21

• path <문자열> | <버퍼> | <URL>

• options <객체> | <정수>

  • recursive <부울> 기본값: false
  • mode <문자열> | <정수> Windows에서 지원되지 않습니다. 기본값: 0o777.

• 반환값: <문자열> | <정의되지 않음>

동기적으로 디렉토리를 생성합니다. 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 <문자열> | <버퍼> | <URL>

• options <문자열> | <객체>

  • encoding <문자열> 기본값: 'utf8'

• 반환값: <문자열>

생성된 디렉토리 경로를 반환합니다.

자세한 내용은 이 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])

[히스토리]

버전	변경 사항
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()과 마찬가지로, path가 디렉토리인 경우 fs.readFileSync()의 동작은 플랫폼에 따라 다릅니다.

import { readFileSync } from 'node:fs'

// macOS, Linux 및 Windows
readFileSync('<directory>')
// => [Error: EISDIR: 디렉토리에서 불법적인 작업, <directory> 읽기]

// FreeBSD
readFileSync('<directory>') // => <데이터>

fs.readlinkSync(path[, options])

[History]

버전	변경 사항
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])

[History]

버전	변경 사항
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을 선택적으로 지정할 수 있도록 options 객체를 전달할 수 있습니다.
v13.13.0, v12.17.0	추가됨: v13.13.0, v12.17.0

• fd <정수>

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

• options <객체>

  • offset <정수> 기본값: 0
  • length <정수> 기본값: buffer.byteLength - offset
  • position <정수> | <bigint> | <null> 기본값: null

• 반환값: <숫자>

bytesRead의 수를 반환합니다.

위의 fs.readSync 함수와 유사하게, 이 버전은 선택적 options 객체를 사용합니다. options 객체가 지정되지 않으면 위의 값을 기본값으로 사용합니다.

자세한 내용은 이 API의 비동기 버전에 대한 설명서를 참조하십시오: fs.read().

fs.readvSync(fd, buffers[, position])

추가됨: v13.13.0, v12.17.0

• fd <정수>
• buffers <ArrayBufferView[]>
• position <정수> | <null> 기본값: null
• 반환값: <숫자> 읽은 바이트 수

자세한 내용은 이 API의 비동기 버전에 대한 설명서를 참조하십시오: fs.readv().

fs.realpathSync(path[, options])

[히스토리]

버전	변경 사항
v8.0.0	Pipe/Socket 확인 지원 추가
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에 연결되어 있으면 이 함수가 작동하려면 /proc에 procfs 파일 시스템을 마운트해야 합니다. Glibc에는 이러한 제한이 없습니다.

fs.renameSync(oldPath, newPath)

[히스토리]

버전	변경 사항
v7.6.0	oldPath 및 newPath 매개변수는 file: 프로토콜을 사용하는 WHATWG URL 객체일 수 있습니다. 현재 지원은 여전히 실험적입니다.
v0.1.21	추가됨: v0.1.21

• oldPath <문자열> | <버퍼> | <URL>
• newPath <문자열> | <버퍼> | <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 <문자열> | <버퍼> | <URL>
• options <객체>
  • maxRetries <정수> EBUSY, EMFILE, ENFILE, ENOTEMPTY 또는 EPERM 오류가 발생하면 Node.js는 각 시도마다 retryDelay 밀리초만큼 선형 백오프 대기 시간을 더하여 작업을 재시도합니다. 이 옵션은 재시도 횟수를 나타냅니다. recursive 옵션이 true가 아니면 이 옵션은 무시됩니다. 기본값: 0.
  • recursive <부울> true이면 재귀적 디렉터리 제거를 수행합니다. 재귀 모드에서는 작업이 실패 시 재시도됩니다. 기본값: false. 사용 중단됨.
  • retryDelay <정수> 재시도 사이에 대기할 시간(밀리초). recursive 옵션이 true가 아니면 이 옵션은 무시됩니다. 기본값: 100.

동기식 rmdir(2). undefined를 반환합니다.

파일(디렉터리가 아님)에서 fs.rmdirSync()를 사용하면 Windows에서는 ENOENT 오류가 발생하고 POSIX에서는 ENOTDIR 오류가 발생합니다.

rm -rf 유닉스 명령과 유사한 동작을 얻으려면 { recursive: true, force: true } 옵션을 사용하여 fs.rmSync()를 사용하십시오.

fs.rmSync(path[, options])

[History]

버전	변경 사항
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])

[History]

버전	변경 사항
v15.3.0, v14.17.0	항목이 존재하지 않는 경우 예외를 throw할지 여부를 지정하는 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를 반환하는 대신 예외를 throw할지 여부입니다. 기본값: true.

• 반환값: <fs.Stats>

경로에 대한 <fs.Stats>를 검색합니다.

fs.statfsSync(path[, options])

추가됨: 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	추가됨: 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	자체 toString 함수를 가진 객체를 data 매개변수에 전달하는 것이 더 이상 지원되지 않습니다.
v17.8.0	자체 toString 함수를 가진 객체를 data 매개변수에 전달하는 것이 더 이상 권장되지 않습니다.
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> 파일 시스템 flags 지원 참조. 기본값: '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 <정수>
• buffer <Buffer> | <TypedArray> | <DataView>
• offset <정수> 기본값: 0
• length <정수> 기본값: buffer.byteLength - offset
• position <정수> | <null> 기본값: null
• 반환값: <숫자> 쓰여진 바이트 수

자세한 내용은 이 API의 비동기 버전에 대한 설명서를 참조하십시오: fs.write(fd, buffer...).

fs.writeSync(fd, buffer[, options])

추가됨: v18.3.0, v16.17.0

• fd <정수>

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

• options <객체>

  • offset <정수> 기본값: 0
  • length <정수> 기본값: buffer.byteLength - offset
  • position <정수> 기본값: null

• 반환값: <숫자> 쓰여진 바이트 수

자세한 내용은 이 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)
}

비동기 반복기를 사용할 때, <fs.Dir> 객체는 반복기가 종료된 후 자동으로 닫힙니다.

dir.close()

추가됨: v12.12.0

• 반환값: <Promise>

디렉터리의 기본 리소스 핸들을 비동기적으로 닫습니다. 후속 읽기는 오류를 발생시킵니다.

리소스가 닫힌 후에 이행되는 Promise를 반환합니다.

dir.close(callback)

[히스토리]

버전	변경 사항
v18.0.0	callback 인수에 잘못된 콜백을 전달하면 ERR_INVALID_CALLBACK 대신 ERR_INVALID_ARG_TYPE를 throw합니다.
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>로 이행되거나, 더 이상 읽을 디렉토리 항목이 없으면 null로 이행되는 Promise를 반환합니다.

이 함수가 반환하는 디렉토리 항목은 운영 체제의 기본 디렉토리 메커니즘에서 제공하는 특정 순서가 없습니다. 디렉토리를 반복하는 동안 추가 또는 제거된 항목은 반복 결과에 포함되지 않을 수 있습니다.

dir.read(callback)

추가됨: v12.12.0

• callback <Function>
  • err <Error>
  • dirent <fs.Dirent> | <null>

readdir(3)을 통해 비동기적으로 다음 디렉토리 항목을 <fs.Dirent>로 읽습니다.

읽기가 완료되면 <fs.Dirent> 또는 더 이상 읽을 디렉토리 항목이 없으면 null을 사용하여 callback이 호출됩니다.

이 함수가 반환하는 디렉토리 항목은 운영 체제의 기본 디렉토리 메커니즘에서 제공하는 특정 순서가 없습니다. 디렉토리를 반복하는 동안 추가 또는 제거된 항목은 반복 결과에 포함되지 않을 수 있습니다.

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>에서 읽어서 반환되는 디렉터리 항목(파일 또는 디렉터리 내의 하위 디렉터리일 수 있음)을 나타냅니다. 디렉터리 항목은 파일 이름과 파일 형식 쌍의 조합입니다.

또한 fs.readdir() 또는 fs.readdirSync()가 withFileTypes 옵션을 true로 설정하여 호출되면 결과 배열은 문자열 또는 <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> 객체는 "참조"되므로, 이전에 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> 객체는 "참조"되므로, 이전에 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 <정수> <fs.ReadStream>에서 사용하는 정수 파일 디스크립터.

<fs.ReadStream>의 파일 디스크립터가 열리면 발생합니다.

이벤트: 'ready'

추가됨: v9.11.0

<fs.ReadStream>을 사용할 준비가 되면 발생합니다.

'open' 이후 바로 발생합니다.

readStream.bytesRead

추가됨: v6.4.0

• <숫자>

지금까지 읽은 바이트 수입니다.

readStream.path

추가됨: v0.1.93

• <문자열> | <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

• <숫자> | <bigint>

파일이 포함된 디바이스의 숫자 ID입니다.

stats.ino

• <숫자> | <bigint>

파일의 파일 시스템별 "inode" 번호입니다.

stats.mode

• <숫자> | <bigint>

파일 유형과 모드를 설명하는 비트 필드입니다.

stats.nlink

• <숫자> | <bigint>

파일에 존재하는 하드 링크의 수입니다.

stats.uid

• <숫자> | <bigint>

파일을 소유한 사용자의 숫자 사용자 ID(POSIX)입니다.

stats.gid

• <숫자> | <bigint>

파일을 소유한 그룹의 숫자 그룹 ID(POSIX)입니다.

stats.rdev

• <숫자> | <bigint>

파일이 디바이스를 나타내는 경우 숫자 디바이스 ID입니다.

stats.size

• <숫자> | <bigint>

바이트 단위의 파일 크기입니다.

기본 파일 시스템에서 파일 크기를 가져오는 것을 지원하지 않는 경우 0이 됩니다.

stats.blksize

• <number> | <bigint>

입출력 작업을 위한 파일 시스템 블록 크기입니다.

stats.blocks

• <number> | <bigint>

이 파일에 할당된 블록 수입니다.

stats.atimeMs

추가됨: v8.1.0

• <number> | <bigint>

POSIX Epoch 이후 밀리초 단위로 표현된, 이 파일이 마지막으로 접근된 시각을 나타내는 타임스탬프입니다.

stats.mtimeMs

추가됨: v8.1.0

• <number> | <bigint>

POSIX Epoch 이후 밀리초 단위로 표현된, 이 파일이 마지막으로 수정된 시각을 나타내는 타임스탬프입니다.

stats.ctimeMs

추가됨: v8.1.0

• <number> | <bigint>

POSIX Epoch 이후 밀리초 단위로 표현된, 파일 상태가 마지막으로 변경된 시각을 나타내는 타임스탬프입니다.

stats.birthtimeMs

추가됨: v8.1.0

• <number> | <bigint>

POSIX Epoch 이후 밀리초 단위로 표현된, 이 파일의 생성 시간을 나타내는 타임스탬프입니다.

stats.atimeNs

추가됨: v12.10.0

• <bigint>

bigint: true가 객체를 생성하는 메서드에 전달될 때만 표시됩니다. POSIX Epoch 이후 나노초 단위로 표현된, 이 파일이 마지막으로 접근된 시각을 나타내는 타임스탬프입니다.

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가 되고, 그렇지 않으면 숫자가 됩니다.

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	복사 작업은 복사본 작성 reflink를 생성하려고 시도합니다. 기본 플랫폼이 복사본 작성을 지원하지 않는 경우, 대체 복사 메커니즘이 사용됩니다.
COPYFILE_FICLONE_FORCE	복사 작업은 복사본 작성 reflink를 생성하려고 시도합니다. 기본 플랫폼이 복사본 작성을 지원하지 않는 경우, 작업이 오류와 함께 실패합니다.

Windows에서도 정의가 가능합니다.

파일 열기 상수

다음 상수는 fs.open()과 함께 사용됩니다.

상수	설명
O_RDONLY	읽기 전용 액세스를 위해 파일을 열도록 지정하는 플래그입니다.
O_WRONLY	쓰기 전용 액세스를 위해 파일을 열도록 지정하는 플래그입니다.
O_RDWR	읽기 쓰기 액세스를 위해 파일을 열도록 지정하는 플래그입니다.
O_CREAT	파일이 이미 존재하지 않는 경우 파일을 생성하도록 지정하는 플래그입니다.
O_EXCL	O_CREAT 플래그가 설정되어 있고 파일이 이미 존재하는 경우 파일 열기가 실패하도록 지정하는 플래그입니다.
O_NOCTTY	경로가 터미널 장치를 식별하는 경우, 경로를 여는 것이 프로세스의 제어 터미널이 되지 않도록 지정하는 플래그입니다 (프로세스가 이미 제어 터미널을 가지고 있지 않은 경우).
O_TRUNC	파일이 존재하고 일반 파일이며, 파일이 쓰기 액세스를 위해 성공적으로 열린 경우, 길이가 0으로 잘리도록 지정하는 플래그입니다.
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.rename() 작업의 콜백에 fs.stat() 호출을 이동합니다.

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>를 사용하여 지정된 경로는 파일 경로를 불투명한 바이트 시퀀스로 취급하는 특정 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
  }
})

프로미스 기반 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()
}

스레드풀 사용

fs.FSWatcher()를 제외한 모든 콜백 및 Promise 기반 파일 시스템 API는 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: illegal operation on a directory, 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()를 호출하여 파일 내용을 재설정할 수 있습니다.