Skip to content

Файловая система

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Исходный код: lib/fs.js

Модуль node:fs позволяет взаимодействовать с файловой системой способом, смоделированным на стандартных функциях POSIX.

Для использования API на основе промисов:

js
import * as fs from 'node:fs/promises'
js
const fs = require('node:fs/promises')

Для использования API на основе колбэков и синхронных API:

js
import * as fs from 'node:fs'
js
const fs = require('node:fs')

Все операции с файловой системой имеют синхронные, колбэк-ориентированные и основанные на промисах формы и доступны с использованием как синтаксиса CommonJS, так и модулей ES6 (ESM).

Пример с промисами

Операции на основе промисов возвращают промис, который выполняется, когда асинхронная операция завершена.

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

try {
  await unlink('/tmp/hello')
  console.log('успешно удалено /tmp/hello')
} catch (error) {
  console.error('произошла ошибка:', error.message)
}
js
const { unlink } = require('node:fs/promises')

;(async function (path) {
  try {
    await unlink(path)
    console.log(`успешно удалено ${path}`)
  } catch (error) {
    console.error('произошла ошибка:', error.message)
  }
})('/tmp/hello')

Пример с колбэком

Форма с колбэком принимает функцию обратного вызова в качестве последнего аргумента и асинхронно вызывает операцию. Аргументы, передаваемые в колбэк, зависят от метода, но первый аргумент всегда зарезервирован для исключения. Если операция завершена успешно, то первый аргумент равен null или undefined.

js
import { unlink } from 'node:fs'

unlink('/tmp/hello', err => {
  if (err) throw err
  console.log('успешно удалено /tmp/hello')
})
js
const { unlink } = require('node:fs')

unlink('/tmp/hello', err => {
  if (err) throw err
  console.log('успешно удалено /tmp/hello')
})

Версии API модуля node:fs, основанные на колбэках, предпочтительнее использования API промисов, когда требуется максимальная производительность (как с точки зрения времени выполнения, так и выделения памяти).

Синхронный пример

Синхронные API блокируют цикл событий Node.js и дальнейшее выполнение JavaScript до завершения операции. Исключения генерируются немедленно и могут быть обработаны с помощью try…catch или могут быть оставлены для всплытия.

js
import { unlinkSync } from 'node:fs'

try {
  unlinkSync('/tmp/hello')
  console.log('успешно удалено /tmp/hello')
} catch (err) {
  // обработать ошибку
}
js
const { unlinkSync } = require('node:fs')

try {
  unlinkSync('/tmp/hello')
  console.log('успешно удалено /tmp/hello')
} catch (err) {
  // обработать ошибку
}

API на основе промисов

[История]

ВерсияИзменения
v14.0.0Предоставляется как require('fs/promises').
v11.14.0, v10.17.0Этот API больше не является экспериментальным.
v10.1.0API доступен только через require('fs').promises.
v10.0.0Добавлено в: v10.0.0

API fs/promises предоставляет асинхронные методы файловой системы, которые возвращают промисы.

API промисов используют базовый пул потоков Node.js для выполнения операций файловой системы вне потока цикла событий. Эти операции не являются синхронизированными или потокобезопасными. Необходимо соблюдать осторожность при выполнении нескольких одновременных модификаций одного и того же файла, так как может произойти повреждение данных.

Класс: 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

Псевдоним filehandle.writeFile().

При работе с файловыми дескрипторами режим не может быть изменен по сравнению с тем, который был установлен с помощью fsPromises.open(). Следовательно, это эквивалентно filehandle.writeFile().

filehandle.chmod(mode)

Добавлено в: v10.0.0

  • mode <integer> битовая маска режима файла.
  • Возвращает: <Promise> Выполняется с undefined при успехе.

Изменяет разрешения на файл. См. chmod(2).

filehandle.chown(uid, gid)

Добавлено в: v10.0.0

  • uid <integer> Идентификатор пользователя нового владельца файла.
  • gid <integer> Идентификатор группы новой группы файла.
  • Возвращает: <Promise> Выполняется с undefined при успехе.

Изменяет владельца файла. Обертка для chown(2).

filehandle.close()

Добавлено в: v10.0.0

  • Возвращает: <Promise> Выполняется с undefined при успехе.

Закрывает дескриптор файла после ожидания завершения любых ожидающих операций с дескриптором.

js
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 может включать значения start и end для чтения диапазона байтов из файла вместо всего файла. Оба start и end являются инклюзивными и начинают отсчет с 0, допустимые значения находятся в диапазоне [0, Number.MAX_SAFE_INTEGER]. Если start опущен или имеет значение undefined, filehandle.createReadStream() считывает последовательно с текущей позиции файла. encoding может быть любым из тех, которые принимаются <Buffer>.

Если FileHandle указывает на символьное устройство, которое поддерживает только блокирующие чтения (например, клавиатуру или звуковую карту), операции чтения не завершаются до тех пор, пока не появятся данные. Это может помешать процессу завершиться и естественному закрытию потока.

По умолчанию поток будет генерировать событие 'close' после его уничтожения. Установите для параметра emitClose значение false, чтобы изменить это поведение.

js
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' дескриптор файла будет закрыт автоматически.

Пример чтения последних 10 байтов файла длиной 100 байтов:

js
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]. Для изменения файла, а не его замены, может потребоваться установить опцию flags open в значение r+ вместо значения по умолчанию r. encoding может быть любым из тех, которые принимаются <Buffer>.

Если для autoClose установлено значение true (поведение по умолчанию) при 'error' или 'finish', файловый дескриптор будет закрыт автоматически. Если autoClose имеет значение false, то файловый дескриптор не будет закрыт, даже если возникнет ошибка. Ответственность за его закрытие и предотвращение утечки файловых дескрипторов лежит на приложении.

По умолчанию поток будет генерировать событие 'close' после его уничтожения. Установите для параметра emitClose значение false, чтобы изменить это поведение.

filehandle.datasync()

Добавлено в: v10.0.0

  • Возвращает: <Promise> Выполняется с undefined при успехе.

Принудительно переводит все текущие операции ввода-вывода, связанные с файлом, в синхронизированное состояние завершения ввода-вывода операционной системы. Подробности см. в документации POSIX fdatasync(2).

В отличие от filehandle.sync, этот метод не сбрасывает измененные метаданные.

filehandle.fd

Добавлено в: v10.0.0

  • <number> Числовой дескриптор файла, управляемый объектом <FileHandle>.

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

[История]

ВерсияИзменения
v21.0.0Принимает значения bigint как position.
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> Выполняется при успехе с объектом, имеющим два свойства:

Считывает данные из файла и сохраняет их в заданный буфер.

Если файл не изменяется одновременно, конец файла достигается, когда количество прочитанных байтов равно нулю.

filehandle.read([options])

[История]

ВерсияИзменения
v21.0.0Принимает значения bigint в качестве position.
v13.11.0, v12.17.0Добавлено в: v13.11.0, v12.17.0
  • options <Object>

    • buffer <Buffer> | <TypedArray> | <DataView> Буфер, который будет заполнен прочитанными данными файла. По умолчанию: Buffer.alloc(16384)
    • offset <integer> Местоположение в буфере, с которого начнется заполнение. По умолчанию: 0
    • length <integer> Количество байтов для чтения. По умолчанию: buffer.byteLength - offset
    • position <integer> | <bigint> | <null> Место, с которого начинается чтение данных из файла. Если null или -1, данные будут считываться с текущей позиции файла, и позиция будет обновлена. Если position является неотрицательным целым числом, текущая позиция файла останется неизменной. По умолчанию: null
  • Возвращает: <Promise> Выполняется при успехе с объектом с двумя свойствами:

Читает данные из файла и сохраняет их в заданном буфере.

Если файл не изменяется одновременно, конец файла достигается, когда количество прочитанных байтов равно нулю.

filehandle.read(buffer[, options])

[История]

ВерсияИзменения
v21.0.0Принимает значения bigint в качестве position.
v18.2.0, v16.17.0Добавлено в: v18.2.0, v16.17.0
  • buffer <Buffer> | <TypedArray> | <DataView> Буфер, который будет заполнен прочитанными данными файла.

  • options <Object>

    • offset <integer> Место в буфере, с которого начнется заполнение. По умолчанию: 0
    • length <integer> Количество байтов для чтения. По умолчанию: buffer.byteLength - offset
    • position <integer> | <bigint> | <null> Место, с которого начинать чтение данных из файла. Если null или -1, данные будут считаны с текущей позиции файла, и позиция будет обновлена. Если position является неотрицательным целым числом, текущая позиция файла останется неизменной. По умолчанию:: null
  • Возвращает: <Promise> Выполняется успешно с объектом с двумя свойствами:

Считывает данные из файла и сохраняет их в заданный буфер.

Если файл не изменяется одновременно, конец файла достигается, когда количество прочитанных байтов равно нулю.

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.

js
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()
js
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

Удобный метод для создания интерфейса readline и потоковой передачи файла. Смотрите filehandle.createReadStream() для получения информации об опциях.

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

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

for await (const line of file.readLines()) {
  console.log(line)
}
js
const { open } = require('node:fs/promises')

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

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

filehandle.readv(buffers[, position])

Добавлено в: v13.13.0, v12.17.0

  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
  • position <integer> | <null> Смещение от начала файла, с которого должны быть прочитаны данные. Если position не является number, данные будут прочитаны с текущей позиции. По умолчанию: null
  • Возвращает: <Promise> Выполняется при успехе с объектом, содержащим два свойства:

Чтение из файла и запись в массив <ArrayBufferView>.

filehandle.stat([options])

[История]

ВерсияИзменения
v10.5.0Принимает дополнительный объект options, чтобы указать, должны ли возвращаемые числовые значения быть bigint.
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 байтов.

Следующий пример сохраняет только первые четыре байта файла:

js
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 байтов, он будет расширен, а расширенная часть будет заполнена нулевыми байтами ('\0'):

Если len отрицательное, то будет использовано значение 0.

filehandle.utimes(atime, mtime)

Добавлено в: v10.0.0

Изменяет временные метки файловой системы объекта, на который ссылается <FileHandle>, затем выполняет промис без аргументов в случае успеха.

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

[История]

ВерсияИзменения
v14.0.0Параметр buffer больше не будет приводить неподдерживаемый ввод к буферам.
v10.0.0Добавлено в: v10.0.0
  • buffer <Buffer> | <TypedArray> | <DataView>
  • offset <integer> Начальная позиция в пределах buffer, где начинаются данные для записи.
  • length <integer> Количество байтов из buffer для записи. По умолчанию: buffer.byteLength - offset
  • position <integer> | <null> Смещение от начала файла, куда следует записать данные из buffer. Если position не является number, данные будут записаны в текущую позицию. Подробнее см. в документации POSIX pwrite(2). По умолчанию: null
  • Возвращает: <Promise>

Записывает buffer в файл.

Промис выполняется с объектом, содержащим два свойства:

Опасно использовать filehandle.write() несколько раз для одного и того же файла, не дожидаясь выполнения (или отклонения) промиса. В этом случае используйте filehandle.createWriteStream().

В Linux позиционная запись не работает, когда файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

filehandle.write(buffer[, options])

Добавлено в: v18.3.0, v16.17.0

Записывает buffer в файл.

Аналогично функции filehandle.write выше, эта версия принимает необязательный объект options. Если объект options не указан, он будет использовать значения по умолчанию, указанные выше.

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

[История]

ВерсияИзменения
v14.0.0Параметр string больше не будет приводить неподдерживаемый ввод к строкам.
v10.0.0Добавлено в: v10.0.0
  • string <string>
  • position <integer> | <null> Смещение от начала файла, куда следует записывать данные из string. Если position не является number, данные будут записаны в текущую позицию. Дополнительные сведения см. в документации POSIX pwrite(2). По умолчанию: null
  • encoding <string> Ожидаемая кодировка строки. По умолчанию: 'utf8'
  • Возвращает: <Promise>

Записывает string в файл. Если string не является строкой, обещание отклоняется с ошибкой.

Обещание выполняется с объектом, содержащим два свойства:

  • bytesWritten <integer> количество записанных байтов
  • buffer <string> ссылка на записанную string.

Небезопасно использовать filehandle.write() несколько раз для одного и того же файла, не дожидаясь выполнения (или отклонения) обещания. В этом случае используйте filehandle.createWriteStream().

В Linux позиционная запись не работает, если файл открыт в режиме добавления. Ядро игнорирует аргумент position и всегда добавляет данные в конец файла.

filehandle.writeFile(data, options)

[История]

ВерсияИзменения
v15.14.0, v14.18.0Аргумент data поддерживает AsyncIterable, Iterable и Stream.
v14.0.0Параметр data больше не будет приводить неподдерживаемый ввод к строкам.
v10.0.0Добавлено в: v10.0.0

Асинхронно записывает данные в файл, заменяя файл, если он уже существует. data может быть строкой, буфером, объектом <AsyncIterable> или объектом <Iterable>. Промис выполняется без аргументов при успехе.

Если options является строкой, то она задает encoding.

<FileHandle> должен поддерживать запись.

Небезопасно использовать filehandle.writeFile() несколько раз для одного и того же файла, не дожидаясь выполнения (или отклонения) промиса.

Если один или несколько вызовов filehandle.write() были сделаны для дескриптора файла, а затем делается вызов filehandle.writeFile(), данные будут записаны с текущей позиции до конца файла. Запись не всегда происходит с начала файла.

filehandle.writev(buffers[, position])

Добавлено в: v12.9.0

  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
  • position <integer> | <null> Смещение от начала файла, куда должны быть записаны данные из buffers. Если position не является number, данные будут записаны в текущую позицию. По умолчанию: null
  • Возвращает: <Promise>

Записывает массив <ArrayBufferView> в файл.

Промис исполняется с объектом, содержащим два свойства:

Небезопасно вызывать writev() несколько раз для одного и того же файла, не дожидаясь выполнения (или отклонения) промиса.

В Linux позиционные записи не работают, когда файл открыт в режиме добавления. Ядро игнорирует аргумент position и всегда добавляет данные в конец файла.

filehandle[Symbol.asyncDispose]()

Добавлено в: v20.4.0, v18.18.0

[Стабильно: 1 - Экспериментально]

Стабильно: 1 Стабильность: 1 - Экспериментально

Псевдоним для filehandle.close().

fsPromises.access(path[, mode])

Добавлено в: v10.0.0

Проверяет разрешения пользователя для файла или каталога, указанного в path. Аргумент mode является необязательным целым числом, которое определяет проверки доступности, которые должны быть выполнены. mode должен быть либо значением fs.constants.F_OK, либо маской, состоящей из побитового ИЛИ любых из fs.constants.R_OK, fs.constants.W_OK и fs.constants.X_OK (например, fs.constants.W_OK | fs.constants.R_OK). Проверьте Константы доступа к файлам для возможных значений mode.

Если проверка доступности выполнена успешно, обещание выполняется без значения. Если какая-либо из проверок доступности завершается неудачно, обещание отклоняется с объектом <Error>. В следующем примере проверяется, может ли текущий процесс читать и записывать файл /etc/passwd.

js
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.access() для проверки доступности файла перед вызовом fsPromises.open(). Это создает состояние гонки, поскольку другие процессы могут изменить состояние файла между двумя вызовами. Вместо этого код пользователя должен открывать/читать/записывать файл напрямую и обрабатывать ошибку, возникающую, если файл недоступен.

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

[История]

ВерсияИзменения
v21.1.0, v20.10.0Теперь поддерживается опция flush.
v10.0.0Добавлено в: v10.0.0

Асинхронно добавляет данные в файл, создавая файл, если он еще не существует. data может быть строкой или <Buffer>.

Если options является строкой, то она определяет encoding.

Опция mode влияет только на вновь созданный файл. См. fs.open() для получения более подробной информации.

path может быть указан как <FileHandle>, который был открыт для добавления (с помощью fsPromises.open()).

fsPromises.chmod(path, mode)

Добавлено в: v10.0.0

Изменяет права доступа к файлу.

fsPromises.chown(path, uid, gid)

Добавлено в: v10.0.0

Изменяет владельца файла.

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> Необязательные модификаторы, определяющие поведение операции копирования. Возможно создать маску, состоящую из побитового ИЛИ двух или более значений (например, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE). По умолчанию: 0.
    • fs.constants.COPYFILE_EXCL: Операция копирования завершится с ошибкой, если dest уже существует.
    • fs.constants.COPYFILE_FICLONE: Операция копирования попытается создать рефлинк copy-on-write. Если платформа не поддерживает copy-on-write, то используется резервный механизм копирования.
    • fs.constants.COPYFILE_FICLONE_FORCE: Операция копирования попытается создать рефлинк copy-on-write. Если платформа не поддерживает copy-on-write, то операция завершится с ошибкой.
  • Возвращает: <Promise> Выполняется с undefined при успехе.

Асинхронно копирует src в dest. По умолчанию dest перезаписывается, если он уже существует.

Гарантии атомарности операции копирования не предоставляются. Если возникает ошибка после открытия целевого файла для записи, будет предпринята попытка удалить цель.

js
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Принимает дополнительную опцию mode для указания поведения при копировании как аргумент mode функции fs.copyFile().
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 для его игнорирования. При игнорировании каталога все его содержимое также будет пропущено. Также может возвращать Promise, который разрешается в true или false По умолчанию: undefined.

    • src <string> исходный путь для копирования.

    • dest <string> путь назначения для копирования.

    • Возвращает: <boolean> | <Promise> Значение, которое может быть приведено к boolean или Promise, который разрешается с таким значением.

    • force <boolean> перезаписать существующий файл или каталог. Операция копирования будет игнорировать ошибки, если вы установите это значение в false и пункт назначения существует. Используйте опцию errorOnExist, чтобы изменить это поведение. По умолчанию: true.

    • mode <integer> модификаторы для операции копирования. По умолчанию: 0. См. флаг mode функции fsPromises.copyFile().

    • 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> true, если glob должен возвращать пути в виде Dirent, иначе false. По умолчанию: false.
  • Возвращает: <AsyncIterator> AsyncIterator, который выдает пути файлов, соответствующих шаблону.

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

for await (const entry of glob('**/*.js')) console.log(entry)
js
const { glob } = require('node:fs/promises')

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

fsPromises.lchmod(path, mode)

Устарело с версии: v10.0.0

Изменяет права доступа к символьной ссылке.

Этот метод реализован только на macOS.

fsPromises.lchown(path, uid, gid)

[История]

ВерсияИзменения
v10.6.0Этот API больше не является устаревшим.
v10.0.0Добавлено в: v10.0.0

Изменяет владельца символьной ссылки.

fsPromises.lutimes(path, atime, mtime)

Добавлено в: v14.5.0, v12.19.0

Изменяет время доступа и модификации файла аналогично fsPromises.utimes(), с тем отличием, что если путь указывает на символьную ссылку, то ссылка не разыменовывается: вместо этого изменяются временные метки самой символьной ссылки.

fsPromises.link(existingPath, newPath)

Добавлено в: v10.0.0

Создает новую ссылку с existingPath на newPath. Подробности смотрите в документации POSIX link(2).

fsPromises.lstat(path[, options])

[История]

ВерсияИзменения
v10.5.0Принимает дополнительный объект options для указания, должны ли возвращаемые числовые значения быть bigint.
v10.0.0Добавлено в: v10.0.0
  • path <string> | <Buffer> | <URL>

  • options <Object>

    • bigint <boolean> Указывает, должны ли числовые значения в возвращаемом объекте <fs.Stats> быть bigint. По умолчанию: false.
  • Возвращает: <Promise>. Выполняется с объектом <fs.Stats> для заданной символической ссылки path.

Эквивалентно fsPromises.stat(), если path не ссылается на символическую ссылку, в этом случае получает информацию о самой ссылке, а не о файле, на который она ссылается. Подробности смотрите в документе 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>. В случае успеха, выполнится со значением undefined, если recursive имеет значение false, или с путем к первому созданному каталогу, если recursive имеет значение true.

Асинхронно создает каталог.

Необязательный аргумент options может быть целым числом, указывающим mode (права доступа и биты sticky), или объектом со свойством mode и свойством recursive, указывающим, следует ли создавать родительские каталоги. Вызов fsPromises.mkdir(), когда path является существующим каталогом, приводит к отклонению только тогда, когда recursive имеет значение false.

js
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)
}
js
const { mkdir } = require('node:fs/promises')
const { join } = require('node:path')

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

  console.log(dirCreation)
  return dirCreation
}

makeDirectory().catch(console.error)

fsPromises.mkdtemp(prefix[, options])

[История]

ВерсияИзменения
v20.6.0, v18.19.0Параметр prefix теперь принимает буферы и URL.
v16.5.0, v14.18.0Параметр prefix теперь принимает пустую строку.
v10.0.0Добавлено в: v10.0.0
  • prefix <string> | <Buffer> | <URL>

  • options <string> | <Object>

    • encoding <string> По умолчанию: 'utf8'
  • Возвращает: <Promise> Выполняется со строкой, содержащей путь файловой системы к вновь созданной временной директории.

Создает уникальную временную директорию. Уникальное имя директории генерируется путем добавления шести случайных символов к концу предоставленного prefix. Из-за несоответствий платформы избегайте конечных символов X в prefix. Некоторые платформы, особенно BSD, могут возвращать более шести случайных символов и заменять конечные символы X в prefix случайными символами.

Необязательный аргумент options может быть строкой, указывающей кодировку, или объектом со свойством encoding, указывающим кодировку символов для использования.

js
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() добавит шесть случайно выбранных символов непосредственно к строке prefix. Например, если дан каталог /tmp, и намерение состоит в том, чтобы создать временный каталог внутри /tmp, то prefix должен заканчиваться конечным разделителем пути, специфичным для платформы (require('node:path').sep).

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

[История]

ВерсияИзменения
v11.1.0Аргумент flags теперь является необязательным и по умолчанию имеет значение 'r'.
v10.0.0Добавлено в: v10.0.0

Открывает <FileHandle>.

Обратитесь к документации POSIX open(2) для получения более подробной информации.

Некоторые символы (\< \> : " / \ | ? *) зарезервированы в Windows, как описано в разделе Именование файлов, путей и пространств имен. В NTFS, если имя файла содержит двоеточие, Node.js откроет файловый поток, как описано на этой странице MSDN.

fsPromises.opendir(path[, options])

[История]

ВерсияИзменения
v20.1.0, v18.17.0Добавлена опция recursive.
v13.1.0, v12.16.0Представлена опция bufferSize.
v12.12.0Добавлено в: v12.12.0
  • path <string> | <Buffer> | <URL>

  • options <Object>

    • encoding <string> | <null> По умолчанию: 'utf8'
    • bufferSize <number> Количество записей каталога, которые буферизуются внутри при чтении из каталога. Более высокие значения приводят к лучшей производительности, но к более высокому использованию памяти. По умолчанию: 32
    • recursive <boolean> Результирующий Dir будет являться <AsyncIterable>, содержащим все подфайлы и каталоги. По умолчанию: false
  • Возвращает: <Promise> Выполняется с <fs.Dir>.

Асинхронно открывает каталог для итеративного сканирования. См. документацию POSIX opendir(3) для получения более подробной информации.

Создает <fs.Dir>, который содержит все дальнейшие функции для чтения и очистки каталога.

Опция encoding устанавливает кодировку для path при открытии каталога и последующих операциях чтения.

Пример использования асинхронной итерации:

js
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>.

js
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 может включать AbortSignal для отмены текущего запроса readFile.
v10.0.0Добавлено в: v10.0.0

Асинхронно считывает всё содержимое файла.

Если кодировка не указана (с использованием options.encoding), данные возвращаются в виде объекта <Buffer>. В противном случае данные будут строкой.

Если options является строкой, то она определяет кодировку.

Когда path является каталогом, поведение fsPromises.readFile() зависит от платформы. В macOS, Linux и Windows промис будет отклонён с ошибкой. В FreeBSD будет возвращено представление содержимого каталога.

Пример чтения файла package.json, расположенного в том же каталоге, что и исполняемый код:

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

Можно отменить выполняющийся readFile, используя <AbortSignal>. Если запрос отменён, возвращённый промис будет отклонён с ошибкой AbortError:

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

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

  // Отменяем запрос до того, как промис будет выполнен.
  controller.abort()

  await promise
} catch (err) {
  // Когда запрос отменён - err является AbortError
  console.error(err)
}

Отмена текущего запроса не отменяет отдельные запросы операционной системы, а скорее внутреннюю буферизацию, которую выполняет fs.readFile.

Любой указанный <FileHandle> должен поддерживать чтение.

fsPromises.readlink(path[, options])

Добавлено в: v10.0.0

Читает содержимое символической ссылки, на которую ссылается path. Подробнее см. документацию POSIX readlink(2). Promise выполняется с linkString в случае успеха.

Необязательный аргумент options может быть строкой, определяющей кодировку, или объектом со свойством encoding, определяющим кодировку символов, используемую для возвращаемого пути ссылки. Если для encoding установлено значение 'buffer', возвращаемый путь ссылки будет передан как объект <Buffer>.

fsPromises.realpath(path[, options])

Добавлено в: v10.0.0

Определяет фактическое местоположение path, используя ту же семантику, что и функция fs.realpath.native().

Поддерживаются только пути, которые можно преобразовать в строки UTF8.

Необязательный аргумент options может быть строкой, определяющей кодировку, или объектом со свойством encoding, определяющим кодировку символов, используемую для пути. Если для encoding установлено значение 'buffer', возвращаемый путь будет передан как объект <Buffer>.

В Linux, когда Node.js связан с musl libc, файловая система procfs должна быть смонтирована в /proc, чтобы эта функция работала. Glibc не имеет этого ограничения.

fsPromises.rename(oldPath, newPath)

Добавлено в: v10.0.0

Переименовывает oldPath в newPath.

fsPromises.rmdir(path[, options])

[История]

ВерсияИзменения
v16.0.0Использование fsPromises.rmdir(path, { recursive: true }) на path, который является файлом, больше не разрешено и приводит к ошибке ENOENT в Windows и ошибке ENOTDIR в POSIX.
v16.0.0Использование fsPromises.rmdir(path, { recursive: true }) на path, который не существует, больше не разрешено и приводит к ошибке 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() на файле (не каталоге) приводит к отклонению промиса с ошибкой ENOENT в Windows и ошибкой ENOTDIR в POSIX.

Чтобы получить поведение, аналогичное команде Unix rm -rf, используйте fsPromises.rm() с параметрами { recursive: true, force: true }.

fsPromises.rm(path[, options])

Добавлено в: 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.
  • Возвращает: <Promise> Выполняется с undefined в случае успеха.

Удаляет файлы и каталоги (по образцу стандартной утилиты POSIX rm).

fsPromises.stat(path[, options])

[История]

ВерсияИзменения
v10.5.0Принимает дополнительный объект options для указания того, должны ли возвращаемые числовые значения быть bigint.
v10.0.0Добавлено в: v10.0.0
  • path <string> | <Buffer> | <URL>

  • options <Object>

    • bigint <boolean> Определяет, должны ли числовые значения в возвращаемом объекте <fs.Stats> быть bigint. По умолчанию: false.
  • Возвращает: <Promise> Выполняется с объектом <fs.Stats> для заданного path.

fsPromises.statfs(path[, options])

Добавлено в: v19.6.0, v18.15.0

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

  • options <Object>

    • bigint <boolean> Определяет, должны ли числовые значения в возвращенном объекте <fs.StatFs> быть bigint. По умолчанию: false.
  • Возвращает: <Promise>, который выполняется с объектом <fs.StatFs> для заданного path.

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

[История]

ВерсияИзменения
v19.0.0Если аргумент type равен null или опущен, Node.js автоматически определит тип target и выберет dir или file.
v10.0.0Добавлено в: v10.0.0

Создает символическую ссылку.

Аргумент type используется только на платформах Windows и может принимать значения 'dir', 'file' или 'junction'. Если аргумент type равен null, Node.js автоматически определит тип target и использует 'file' или 'dir'. Если target не существует, будет использовано 'file'. Точки соединения Windows требуют, чтобы путь назначения был абсолютным. При использовании 'junction', аргумент target автоматически нормализуется до абсолютного пути. Точки соединения на томах NTFS могут указывать только на каталоги.

fsPromises.truncate(path[, len])

Добавлено в: v10.0.0

Усекает (сокращает или удлиняет) длину содержимого по адресу path до len байтов.

fsPromises.unlink(path)

Добавлено в: v10.0.0

Если path указывает на символическую ссылку, то ссылка удаляется, не затрагивая файл или каталог, на который эта ссылка указывает. Если path указывает на путь к файлу, который не является символической ссылкой, то файл удаляется. См. документацию POSIX unlink(2) для получения более подробной информации.

fsPromises.utimes(path, atime, mtime)

Добавлено в: v10.0.0

Изменяет временные метки файловой системы объекта, на который ссылается path.

Аргументы atime и mtime соответствуют следующим правилам:

  • Значения могут быть либо числами, представляющими время Unix epoch, Date или числовой строкой, такой как '123456789.0'.
  • Если значение не может быть преобразовано в число, или является NaN, Infinity или -Infinity, будет выдана ошибка Error.

fsPromises.watch(filename[, options])

Добавлено в: v15.9.0, v14.18.0

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

  • options <string> | <Object>

    • persistent <boolean> Указывает, должен ли процесс продолжать работу до тех пор, пока ведется наблюдение за файлами. По умолчанию: true.
    • recursive <boolean> Указывает, следует ли отслеживать все подкаталоги или только текущий каталог. Это применяется, когда указан каталог, и только на поддерживаемых платформах (см. предостережения). По умолчанию: false.
    • encoding <string> Указывает кодировку символов, которая будет использоваться для имени файла, передаваемого слушателю. По умолчанию: 'utf8'.
    • signal <AbortSignal> <AbortSignal>, используемый для сигнализации о том, когда наблюдатель должен остановиться.
  • Возвращает: <AsyncIterator> объектов со свойствами:

Возвращает асинхронный итератор, который отслеживает изменения в filename, где filename - это либо файл, либо каталог.

js
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 может включать AbortSignal для прерывания текущего запроса writeFile.
v14.0.0Параметр data больше не приводит неподдерживаемый ввод к строкам.
v10.0.0Добавлено в: v10.0.0

Асинхронно записывает данные в файл, заменяя файл, если он уже существует. data может быть строкой, буфером, объектом <AsyncIterable> или <Iterable>.

Параметр encoding игнорируется, если data является буфером.

Если options является строкой, то она указывает кодировку.

Параметр mode влияет только на вновь созданный файл. Подробнее см. fs.open().

Любой указанный <FileHandle> должен поддерживать запись.

Небезопасно использовать fsPromises.writeFile() несколько раз для одного и того же файла, не дожидаясь завершения промиса.

Аналогично fsPromises.readFile - fsPromises.writeFile - это удобный метод, который выполняет несколько внутренних вызовов write для записи переданного ему буфера. Для производительного кода рассмотрите возможность использования fs.createWriteStream() или filehandle.createWriteStream().

Можно использовать <AbortSignal> для отмены fsPromises.writeFile(). Отмена является "лучшей попыткой", и, вероятно, некоторое количество данных все еще будет записано.

js
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

Возвращает объект, содержащий часто используемые константы для операций файловой системы. Объект идентичен fs.constants. Более подробную информацию см. в разделе Константы FS.

API на основе обратного вызова

API на основе обратного вызова выполняют все операции асинхронно, не блокируя цикл событий, а затем вызывают функцию обратного вызова по завершении или возникновении ошибки.

API на основе обратного вызова используют базовый пул потоков Node.js для выполнения операций файловой системы вне потока цикла событий. Эти операции не синхронизированы и не являются потокобезопасными. Необходимо проявлять осторожность при выполнении нескольких одновременных модификаций одного и того же файла, иначе может произойти повреждение данных.

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

[История]

ВерсияИзменения
v20.8.0Константы fs.F_OK, fs.R_OK, fs.W_OK и fs.X_OK, которые присутствовали непосредственно в fs, устарели.
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v6.3.0Константы, такие как fs.R_OK и т. д., которые присутствовали непосредственно в fs, были перемещены в fs.constants в качестве мягкого устаревания. Таким образом, для Node.js < v6.3.0 используйте fs для доступа к этим константам или сделайте что-то вроде `(fs.constants
v0.11.15Добавлено в: v0.11.15

Проверяет права пользователя на доступ к файлу или каталогу, указанному в path. Аргумент mode — это необязательное целое число, которое указывает, какие проверки доступности необходимо выполнить. mode должен быть либо значением fs.constants.F_OK, либо маской, состоящей из побитового ИЛИ любых из fs.constants.R_OK, fs.constants.W_OK и fs.constants.X_OK (например, fs.constants.W_OK | fs.constants.R_OK). Проверьте Константы доступа к файлам для возможных значений mode.

Последний аргумент, callback, — это функция обратного вызова, которая вызывается с возможным аргументом ошибки. Если какая-либо из проверок доступности завершается неудачей, аргумент ошибки будет объектом Error. В следующих примерах проверяется, существует ли package.json, и является ли он читаемым или записываемым.

js
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.access() для проверки доступности файла перед вызовом fs.open(), fs.readFile() или fs.writeFile(). Это создает условие гонки, поскольку другие процессы могут изменить состояние файла между двумя вызовами. Вместо этого код пользователя должен открывать/читать/записывать файл напрямую и обрабатывать ошибку, если файл недоступен.

Запись (НЕ РЕКОМЕНДУЕТСЯ)

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

Запись (РЕКОМЕНДУЕТСЯ)

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

Чтение (НЕ РЕКОМЕНДУЕТСЯ)

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

Чтение (РЕКОМЕНДУЕТСЯ)

js
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_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с id DEP0013.
v7.0.0Переданный объект options никогда не будет изменен.
v5.0.0Параметр file теперь может быть файловым дескриптором.
v0.6.7Добавлено в: v0.6.7

Асинхронно добавляет данные в файл, создавая файл, если он ещё не существует. data может быть строкой или <Buffer>.

Параметр mode влияет только на вновь созданный файл. См. fs.open() для получения более подробной информации.

js
import { appendFile } from 'node:fs'

appendFile('message.txt', 'data to append', err => {
  if (err) throw err
  console.log('Данные "data to append" были добавлены в файл!')
})

Если options является строкой, то она указывает кодировку:

js
import { appendFile } from 'node:fs'

appendFile('message.txt', 'data to append', 'utf8', callback)

path может быть указан как числовой файловый дескриптор, открытый для добавления (с помощью fs.open() или fs.openSync()). Файловый дескриптор не будет закрыт автоматически.

js
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_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Непередача его вызовет ошибку TypeError во время выполнения.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Параметр callback больше не является необязательным. Непередача его вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.1.30Добавлено в: v0.1.30

Асинхронно изменяет права доступа к файлу. В функцию обратного вызова передаются только возможные исключения.

Более подробную информацию см. в документации POSIX chmod(2).

js
import { chmod } from 'node:fs'

chmod('my_file.txt', 0o775, err => {
  if (err) throw err
  console.log('Права доступа к файлу "my_file.txt" изменены!')
})

Режимы файлов

Аргумент mode, используемый в методах fs.chmod() и fs.chmodSync(), представляет собой числовую битовую маску, созданную с использованием побитового ИЛИ следующих констант:

КонстантаВосьмеричноеОписание
fs.constants.S_IRUSR0o400чтение владельцем
fs.constants.S_IWUSR0o200запись владельцем
fs.constants.S_IXUSR0o100выполнение/поиск владельцем
fs.constants.S_IRGRP0o40чтение группой
fs.constants.S_IWGRP0o20запись группой
fs.constants.S_IXGRP0o10выполнение/поиск группой
fs.constants.S_IROTH0o4чтение другими
fs.constants.S_IWOTH0o2запись другими
fs.constants.S_IXOTH0o1выполнение/поиск другими

Более простой способ построения mode — использование последовательности из трех восьмеричных цифр (например, 765). Самая левая цифра (7 в примере) задает права доступа для владельца файла. Средняя цифра (6 в примере) задает права доступа для группы. Самая правая цифра (5 в примере) задает права доступа для других.

ЧислоОписание
7чтение, запись и выполнение
6чтение и запись
5чтение и выполнение
4только чтение
3запись и выполнение
2только запись
1только выполнение
0без прав доступа

Например, восьмеричное значение 0o765 означает:

  • Владелец может читать, записывать и выполнять файл.
  • Группа может читать и записывать файл.
  • Другие могут читать и выполнять файл.

При использовании необработанных чисел там, где ожидаются режимы файлов, любое значение большее, чем 0o777, может привести к зависящему от платформы поведению, которое не гарантируется как стабильно работающее. Поэтому константы, такие как S_ISVTX, S_ISGID или S_ISUID, не представлены в fs.constants.

Оговорки: в Windows можно изменить только право на запись, а различия между правами группы, владельца или других не реализованы.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о снятии с поддержки с идентификатором DEP0013.
v0.1.97Добавлено в: v0.1.97

Асинхронно изменяет владельца и группу файла. В функцию обратного вызова передаются только возможные исключения.

Более подробную информацию см. в документации POSIX chown(2).

fs.close(fd[, callback])

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v15.9.0, v14.17.0Теперь используется обратный вызов по умолчанию, если он не предоставлен.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о снятии с поддержки с идентификатором DEP0013.
v0.0.2Добавлено в: v0.0.2

Закрывает файловый дескриптор. В функцию обратного вызова передаются только возможные исключения.

Вызов fs.close() для любого файлового дескриптора (fd), который в настоящее время используется какой-либо другой операцией fs, может привести к неопределенному поведению.

Более подробную информацию см. в документации POSIX close(2).

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v14.0.0Аргумент flags изменён на mode, и введена более строгая проверка типов.
v8.5.0Добавлено в: v8.5.0

Асинхронно копирует src в dest. По умолчанию, dest перезаписывается, если он уже существует. В функцию обратного вызова не передаются никакие аргументы, кроме возможного исключения. Node.js не гарантирует атомарность операции копирования. Если ошибка возникает после того, как целевой файл был открыт для записи, Node.js попытается удалить целевой файл.

mode — это необязательное целое число, которое указывает поведение операции копирования. Можно создать маску, состоящую из побитового ИЛИ двух или более значений (например, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

  • fs.constants.COPYFILE_EXCL: Операция копирования завершится ошибкой, если dest уже существует.
  • fs.constants.COPYFILE_FICLONE: Операция копирования попытается создать reflink с копированием при записи. Если платформа не поддерживает копирование при записи, используется резервный механизм копирования.
  • fs.constants.COPYFILE_FICLONE_FORCE: Операция копирования попытается создать reflink с копированием при записи. Если платформа не поддерживает копирование при записи, операция завершится ошибкой.
js
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Принимает дополнительный параметр mode для указания поведения копирования как аргумент mode в fs.copyFile().
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
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 для игнорирования. При игнорировании каталога все его содержимое также будет пропущено. Может также возвращать Promise, который разрешается в true или false. По умолчанию: undefined.

    • src <строка> исходный путь для копирования.

    • dest <строка> путь назначения для копирования.

    • Возвращает: <булево> | <Promise> Значение, которое может быть приведено к типу boolean, или Promise, который выполняется с таким значением.

    • force <булево> перезаписать существующий файл или каталог. Операция копирования будет игнорировать ошибки, если вы установите это значение в false, а назначение существует. Используйте параметр errorOnExist, чтобы изменить это поведение. По умолчанию: true.

    • mode <целое число> модификаторы для операции копирования. По умолчанию: 0. См. флаг mode в fs.copyFile().

    • preserveTimestamps <булево> Если true, метки времени из src будут сохранены. По умолчанию: false.

    • recursive <булево> рекурсивно копировать каталоги. По умолчанию: false

    • verbatimSymlinks <булево> Если true, разрешение пути для символических ссылок будет пропущено. По умолчанию: false

  • callback <Функция>

Асинхронно копирует всю структуру каталога из src в dest, включая подкаталоги и файлы.

При копировании каталога в другой каталог, шаблоны (globs) не поддерживаются, и поведение аналогично cp dir1/ dir2/.

fs.createReadStream(path[, options])

[История]

ВерсияИзменения
v16.10.0Опция fs не нуждается в методе open, если предоставлен fd.
v16.10.0Опция fs не нуждается в методе close, если autoClose имеет значение false.
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 может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Переданный объект options никогда не будет изменён.
v2.3.0Переданный объект options теперь может быть строкой.
v0.1.31Добавлено в: v0.1.31

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, можно переопределить соответствующие реализации fs для open, read и close. При предоставлении опции fs требуется переопределение для read. Если fd не предоставлен, также требуется переопределение для open. Если autoClose имеет значение true, также требуется переопределение для close.

js
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 устанавливает режим файла (разрешения и липкие биты), но только если файл был создан.

Пример чтения последних 10 байтов файла длиной 100 байтов:

js
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Параметру fs не требуется метод open, если предоставлен fd.
v16.10.0Параметру fs не требуется метод close, если autoClose имеет значение false.
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 может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Переданный объект options никогда не будет изменен.
v5.5.0Теперь поддерживается параметр autoClose.
v2.3.0Переданный объект options теперь может быть строкой.
v0.1.31Добавлено в: v0.1.31

options может также включать параметр start, чтобы разрешить запись данных в некоторую позицию после начала файла, допустимые значения находятся в диапазоне [0, Number.MAX_SAFE_INTEGER]. Изменение файла, а не его замена, может потребовать установки параметра flags в значение r+, а не в значение w по умолчанию. encoding может быть любым из тех, которые принимаются <Buffer>.

Если autoClose установлено в true (поведение по умолчанию), то при возникновении события 'error' или 'finish' дескриптор файла будет автоматически закрыт. Если autoClose равно false, то дескриптор файла не будет закрыт, даже если произошла ошибка. Приложение отвечает за его закрытие и за то, чтобы не было утечки дескрипторов файлов.

По умолчанию поток будет генерировать событие 'close' после того, как он будет уничтожен. Установите параметр emitClose в false, чтобы изменить это поведение.

Предоставляя параметр fs, можно переопределить соответствующие реализации fs для open, write, writev и close. Переопределение write() без writev() может снизить производительность, поскольку некоторые оптимизации (_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_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v1.0.0Устарело с версии: v1.0.0
v0.0.2Добавлено в: v0.0.2

[Стабильность: 0 - Устарело]

Стабильность: 0 Стабильность: 0 - Устарело: Используйте fs.stat() или fs.access() вместо этого.

Проверяет, существует ли элемент по заданному пути path, проверяя файловую систему. Затем вызывает аргумент callback со значением true или false:

js
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.exists() для проверки существования файла перед вызовом fs.open(), fs.readFile() или fs.writeFile() не рекомендуется. Это создает условие гонки, поскольку другие процессы могут изменить состояние файла между двумя вызовами. Вместо этого код пользователя должен открывать/читать/писать файл напрямую и обрабатывать ошибку, если файл не существует.

Запись (НЕ РЕКОМЕНДУЕТСЯ)

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

Запись (РЕКОМЕНДУЕТСЯ)

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

Чтение (НЕ РЕКОМЕНДУЕТСЯ)

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

Чтение (РЕКОМЕНДУЕТСЯ)

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет исключение TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.4.7Добавлено в: v0.4.7

Устанавливает права доступа к файлу. В функцию обратного вызова передается только возможное исключение.

Подробнее см. в документации POSIX fchmod(2).

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет исключение TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.4.7Добавлено в: v0.4.7

Устанавливает владельца файла. В функцию обратного вызова передается только возможное исключение.

Подробнее см. в документации POSIX fchown(2).

fs.fdatasync(fd, callback)

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о снятии с поддержки с идентификатором DEP0013.
v0.1.96Добавлено в: v0.1.96

Принудительно завершает все текущие операции ввода-вывода, связанные с файлом, в состоянии синхронного завершения ввода-вывода операционной системы. Подробности см. в документации POSIX fdatasync(2). В функцию обратного вызова передаются только возможные исключения.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.5.0Принимает дополнительный объект options для указания, должны ли возвращаемые числовые значения быть типа bigint.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о снятии с поддержки с идентификатором DEP0013.
v0.1.95Добавлено в: v0.1.95

Вызывает функцию обратного вызова с объектом <fs.Stats> для файлового дескриптора.

Подробнее см. в документации POSIX fstat(2).

fs.fsync(fd, callback)

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет исключение TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.1.96Добавлено в: v0.1.96

Запрос на очистку всех данных для открытого файлового дескриптора на устройство хранения. Конкретная реализация зависит от операционной системы и устройства. Для получения дополнительной информации см. документацию POSIX fsync(2). В функцию обратного вызова передаются только возможные исключения.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет исключение TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.8.6Добавлено в: v0.8.6

Укорачивает файловый дескриптор. В функцию обратного вызова передаются только возможные исключения.

См. документацию POSIX ftruncate(2) для получения дополнительной информации.

Если файл, на который ссылается файловый дескриптор, был больше len байт, в файле останутся только первые len байт.

Например, следующая программа сохраняет только первые четыре байта файла:

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

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

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

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

Если файл ранее был короче len байт, он расширяется, а расширенная часть заполняется нулевыми байтами ('\0'):

Если len отрицательно, будет использоваться 0.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с идентификатором DEP0013.
v4.1.0Числовые строки, NaN и Infinity теперь разрешены в качестве спецификаторов времени.
v0.4.2Добавлено в: v0.4.2

Изменение меток времени файловой системы объекта, на который ссылается предоставленный дескриптор файла. См. 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 <булево> true, если glob должен возвращать пути как Dirents, false в противном случае. По умолчанию: false.
  • callback <Функция>

  • Извлекает файлы, соответствующие указанному шаблону.

js
import { glob } from 'node:fs'

glob('**/*.js', (err, matches) => {
  if (err) throw err
  console.log(matches)
})
js
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_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v16.0.0Возвращаемая ошибка может быть AggregateError, если возвращается более одной ошибки.
v10.0.0Параметр callback больше не является необязательным. Не передача его вызовет ошибку TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Не передача его вызовет предупреждение об устаревании с идентификатором DEP0013.
v0.4.7Устарело с версии: v0.4.7

Изменяет права доступа к символической ссылке. В функцию обратного вызова передаются только возможные исключения.

Этот метод реализован только в macOS.

См. документацию POSIX lchmod(2) для получения более подробной информации.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.6.0Этот API больше не устарел.
v10.0.0Параметр callback больше не является необязательным. Не передача его вызовет ошибку TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Не передача его вызовет предупреждение об устаревании с идентификатором DEP0013.
v0.4.7Устаревание только в документации.

Устанавливает владельца символической ссылки. В функцию обратного вызова передаются только возможные исключения.

См. документацию POSIX lchown(2) для получения более подробной информации.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v14.5.0, v12.19.0Добавлено в: v14.5.0, v12.19.0

Изменяет время доступа и модификации файла так же, как fs.utimes(), за исключением того, что если путь указывает на символическую ссылку, то ссылка не разыменовывается: вместо этого изменяются метки времени самой символической ссылки.

В функцию обратного вызова завершения не передаются никакие аргументы, кроме возможного исключения.

fs.link(existingPath, newPath, callback)

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.6.0Параметры existingPath и newPath могут быть объектами WHATWG URL с использованием протокола file:. Поддержка в настоящее время всё ещё экспериментальная.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие выведет предупреждение о устаревании с идентификатором DEP0013.
v0.1.31Добавлено в: v0.1.31

Создаёт новую ссылку из existingPath в newPath. См. документацию POSIX link(2) для получения более подробной информации. В функцию обратного вызова завершения не передаются никакие аргументы, кроме возможного исключения.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.5.0Принимает дополнительный объект options для указания, должны ли возвращаемые числовые значения быть типа bigint.
v10.0.0Параметр callback больше не является необязательным. Отсутствие его передачи вызовет ошибку TypeError во время выполнения.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Параметр callback больше не является необязательным. Отсутствие его передачи вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.1.30Добавлено в: v0.1.30

Возвращает <fs.Stats> для символической ссылки, на которую указывает путь. Обратный вызов получает два аргумента (err, stats), где stats — это объект <fs.Stats>. lstat() идентичен stat(), за исключением того, что если path — это символическая ссылка, то проверяется сама ссылка, а не файл, на который она указывает.

См. документацию POSIX lstat(2) для получения более подробной информации.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v13.11.0, v12.17.0В режиме recursive обратный вызов теперь получает первый созданный путь в качестве аргумента.
v10.12.0Вторым аргументом теперь может быть объект options со свойствами recursive и mode.
v10.0.0Параметр callback больше не является необязательным. Непередача его вызовет ошибку TypeError во время выполнения.
v7.6.0Параметр path теперь может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Параметр callback больше не является необязательным. Непередача его вызовет предупреждение о устаревании с id DEP0013.
v0.1.8Добавлено в: v0.1.8

Асинхронно создаёт каталог.

Обратный вызов получает возможное исключение и, если recursive равно true, первый созданный путь к каталогу, (err[, path]). path может оставаться undefined, когда recursive равно true, если ни один каталог не был создан (например, если он был создан ранее).

Необязательный аргумент options может быть целым числом, указывающим mode (разрешения и липкие биты), или объектом со свойством mode и свойством recursive, указывающим, следует ли создавать родительские каталоги. Вызов fs.mkdir(), когда path является существующим каталогом, приводит к ошибке только когда recursive равно false. Если recursive равно false и каталог существует, возникает ошибка EEXIST.

js
import { mkdir } from 'node:fs'

// Создать ./tmp/a/apple, независимо от того, существуют ли ./tmp и ./tmp/a.
mkdir('./tmp/a/apple', { recursive: true }, err => {
  if (err) throw err
})

В Windows использование fs.mkdir() в корневом каталоге даже с рекурсией приведёт к ошибке:

js
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_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v16.5.0, v14.18.0Параметр prefix теперь принимает пустую строку.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с идентификатором DEP0013.
v6.2.1Параметр callback теперь является необязательным.
v5.10.0Добавлено в: v5.10.0

Создает уникальный временный каталог.

Генерирует шесть случайных символов, которые добавляются к обязательному префиксу prefix для создания уникального временного каталога. Из-за несоответствий между платформами избегайте добавления символов X в конце prefix. Некоторые платформы, в частности BSD, могут возвращать более шести случайных символов и заменять символы X в конце prefix случайными символами.

Путь к созданному каталогу передается как строка во второй параметр обратного вызова.

Необязательный аргумент options может быть строкой, указывающей кодировку, или объектом со свойством encoding, указывающим используемую кодировку символов.

js
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() добавит шесть случайно выбранных символов непосредственно к строке prefix. Например, если у вас есть каталог /tmp, и вы хотите создать временный каталог внутри /tmp, prefix должен заканчиваться разделителем пути, специфичным для платформы (require('node:path').sep).

js
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_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v11.1.0Аргумент flags теперь является необязательным и по умолчанию имеет значение 'r'.
v9.9.0Теперь поддерживаются флаги as и as+.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v0.0.2Добавлено в: v0.0.2

Асинхронное открытие файла. Более подробную информацию см. в документации 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 - Экспериментальный

Возвращает <Blob>, данные которого основаны на данном файле.

Файл не должен быть изменен после создания <Blob>. Любые изменения приведут к сбою чтения данных <Blob> с ошибкой DOMException. Синхронные операции проверки состояния файла при создании Blob и перед каждым чтением для обнаружения того, были ли изменены данные файла на диске.

js
import { openAsBlob } from 'node:fs'

const blob = await openAsBlob('the.file.txt')
const ab = await blob.arrayBuffer()
blob.stream()
js
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_ARG_TYPE вместо ERR_INVALID_CALLBACK.
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>

Асинхронно открывает каталог. Дополнительные сведения см. в документации POSIX opendir(3).

Создает <fs.Dir>, который содержит все последующие функции для чтения из каталога и его очистки.

Параметр encoding устанавливает кодировку для path при открытии каталога и последующих операциях чтения.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.10.0Параметр buffer теперь может быть любым TypedArray или DataView.
v7.4.0Параметр buffer теперь может быть Uint8Array.
v6.0.0Параметр length теперь может быть равен 0.
v0.0.2Добавлено в: v0.0.2

Чтение данных из файла, указанного fd.

Обратный вызов получает три аргумента: (err, bytesRead, buffer).

Если файл не изменяется одновременно, конец файла достигается, когда количество прочитанных байт равно нулю.

Если этот метод вызывается как его версия util.promisify(), он возвращает promise для Object со свойствами bytesRead и buffer.

Метод 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Объект options может быть передан для необязательного указания буфера, смещения, длины и позиции.
v13.11.0, v12.17.0Добавлено в: v13.11.0, v12.17.0

Аналогично функции fs.read(), эта версия принимает необязательный объект options. Если объект options не указан, будут использоваться значения по умолчанию, указанные выше.

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

Добавлено в: v18.2.0, v16.17.0

Аналогично функции fs.read(), эта версия принимает необязательный объект options. Если объект options не указан, будут использоваться значения по умолчанию, указанные выше.

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

[История]

ВерсияИзменения
v20.1.0, v18.17.0Добавлен параметр recursive.
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.10.0Добавлен новый параметр withFileTypes.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет исключение TypeError во время выполнения.
v7.6.0Параметр path может быть объектом WHATWG URL с протоколом file:.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с идентификатором DEP0013.
v6.0.0Добавлен параметр options.
v0.1.8Добавлено в: v0.1.8

Считывает содержимое каталога. Обратный вызов получает два аргумента (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_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v16.0.0Возвращаемая ошибка может быть AggregateError, если возвращается более одной ошибки.
v15.2.0, v14.17.0Аргумент options может включать AbortSignal для прерывания текущего запроса readFile.
v10.0.0Параметр callback больше не является необязательным. Отсутствие его передачи вызовет ошибку TypeError во время выполнения.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Параметр callback больше не является необязательным. Отсутствие его передачи вызовет предупреждение о устаревании с id DEP0013.
v5.1.0callback всегда будет вызываться с null в качестве параметра error в случае успеха.
v5.0.0Параметр path теперь может быть файловым дескриптором.
v0.1.29Добавлено в: v0.1.29

Асинхронно считывает всё содержимое файла.

js
import { readFile } from 'node:fs'

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

В обратный вызов передаются два аргумента (err, data), где data — это содержимое файла.

Если кодировка не указана, возвращается необработанный буфер.

Если options — строка, то она указывает кодировку:

js
import { readFile } from 'node:fs'

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

Когда путь является каталогом, поведение fs.readFile() и fs.readFileSync() зависит от платформы. На macOS, Linux и Windows будет возвращена ошибка. На FreeBSD будет возвращено представление содержимого каталога.

js
import { readFile } from 'node:fs'

// macOS, Linux и Windows
readFile('<каталог>', (err, data) => {
  // => [Error: EISDIR: недопустимая операция над каталогом, чтение <каталог>]
})

// FreeBSD
readFile('<каталог>', (err, data) => {
  // => null, <data>
})

Можно прервать запущенный запрос с помощью AbortSignal. Если запрос прерывается, обратный вызов вызывается с AbortError:

js
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 не может определить фактический размер файла, каждая операция чтения будет загружать 64 КБ данных. Для обычных файлов каждое чтение будет обрабатывать 512 КБ данных.

Для приложений, которым требуется максимально быстрое чтение содержимого файла, лучше использовать fs.read() напрямую и управлять чтением полного содержимого файла в коде приложения.

В выпуске Node.js на GitHub #25741 представлена дополнительная информация и подробный анализ производительности fs.readFile() для нескольких размеров файлов в разных версиях Node.js.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Отсутствие его передачи приведет к ошибке TypeError во время выполнения.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Параметр callback больше не является необязательным. Отсутствие его передачи вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.1.31Добавлено в: v0.1.31

Считывает содержимое символической ссылки, на которую ссылается path. Обратный вызов получает два аргумента (err, linkString).

См. документацию POSIX readlink(2) для получения более подробной информации.

Необязательный аргумент options может быть строкой, указывающей кодировку, или объектом со свойством encoding, указывающим используемую кодировку символов для пути ссылки, передаваемого в обратный вызов. Если encoding установлен в 'buffer', путь ссылки будет передан как объект <Buffer>.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v13.13.0, v12.17.0Добавлено в: v13.13.0, v12.17.0

Чтение из файла, указанного fd, и запись в массив ArrayBufferView с использованием readv().

position — это смещение от начала файла, с которого следует читать данные. Если typeof position !== 'number', данные будут читаться с текущей позиции.

Обратный вызов получит три аргумента: err, bytesRead и buffers. bytesRead — это количество байтов, прочитанных из файла.

Если этот метод вызывается как его версия util.promisify(), он возвращает promise для объекта со свойствами bytesRead и buffers.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v8.0.0Добавлена поддержка разрешения каналов/соккетов.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с идентификатором DEP0013.
v6.4.0Вызов realpath снова работает для различных пограничных случаев в Windows.
v6.0.0Параметр cache удален.
v0.1.31Добавлено в: v0.1.31

Асинхронно вычисляет каноническое имя пути, разрешая ., .. и символические ссылки.

Каноническое имя пути не обязательно уникально. Жесткие ссылки и монтирования могут предоставлять доступ к объекту файловой системы через множество имен путей.

Эта функция ведет себя как realpath(3) с некоторыми исключениями:

Обратный вызов получает два аргумента (err, resolvedPath). Может использовать process.cwd для разрешения относительных путей.

Поддерживаются только пути, которые могут быть преобразованы в строки UTF8.

Необязательный аргумент options может быть строкой, указывающей кодировку, или объектом со свойством encoding, указывающим используемую кодировку символов для пути, передаваемого в обратный вызов. Если encoding установлено в 'buffer', возвращаемый путь будет передан как объект <Buffer>.

Если path указывает на сокет или канал, функция вернет зависящее от системы имя для этого объекта.

Путь, который не существует, приводит к ошибке ENOENT. error.path — это абсолютный путь к файлу.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v9.2.0Добавлено в: v9.2.0

Асинхронный realpath(3).

Функция обратного вызова callback получает два аргумента (err, resolvedPath).

Поддерживаются только пути, которые могут быть преобразованы в строки UTF8.

Необязательный аргумент options может быть строкой, указывающей кодировку, или объектом со свойством encoding, указывающим кодировку символов, используемую для пути, переданного в функцию обратного вызова. Если encoding установлено в 'buffer', возвращаемый путь будет передан в виде объекта <Buffer>.

В Linux, когда Node.js связан с musl libc, файловая система procfs должна быть смонтирована в /proc, чтобы эта функция работала. Glibc не имеет этого ограничения.

fs.rename(oldPath, newPath, callback)

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.6.0Параметры oldPath и newPath могут быть объектами WHATWG URL с использованием протокола file:. Поддержка в настоящее время всё ещё экспериментальная.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.0.2Добавлено в: v0.0.2

Асинхронно переименовывает файл по пути oldPath в имя файла, указанное как newPath. В случае, если newPath уже существует, он будет перезаписан. Если по пути newPath находится директория, будет выброшено исключение. В функцию обратного вызова не передаются никакие аргументы, кроме возможного исключения.

См. также: rename(2).

js
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_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v16.0.0Использование fs.rmdir(path, { recursive: true }) для path, являющегося файлом, больше не допускается и приводит к ошибке ENOENT в Windows и ошибке ENOTDIR в POSIX.
v16.0.0Использование fs.rmdir(path, { recursive: true }) для path, который не существует, больше не допускается и приводит к ошибке ENOENT.
v16.0.0Опция recursive устарела, её использование вызывает предупреждение об устаревании.
v14.14.0Опция recursive устарела, используйте вместо неё fs.rm.
v13.3.0, v12.16.0Опция maxBusyTries переименована в maxRetries, и её значение по умолчанию равно 0. Опция emfileWait удалена, и ошибки EMFILE используют ту же логику повторов, что и другие ошибки. Теперь поддерживается опция retryDelay. Ошибки ENFILE теперь повторяются.
v12.10.0Теперь поддерживаются опции recursive, maxBusyTries и emfileWait.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
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>

Асинхронный rmdir(2). В функцию обратного вызова передаются только возможные исключения.

Использование fs.rmdir() для файла (а не каталога) приводит к ошибке ENOENT в Windows и ошибке ENOTDIR в POSIX.

Для получения поведения, аналогичного команде rm -rf Unix, используйте fs.rm() с опциями { recursive: true, force: true }.

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

[История]

ВерсияИзменения
v17.3.0, v16.14.0Параметр path может быть объектом WHATWG URL с использованием протокола file:
v14.14.0Добавлено в: v14.14.0
  • path <строка> | <Buffer> | <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 <Функция>

Асинхронно удаляет файлы и каталоги (моделируется по стандартной утилите POSIX rm). В функцию обратного вызова завершения не передаются аргументы, кроме возможного исключения.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.5.0Принимает дополнительный объект options для указания, должны ли возвращаемые числовые значения быть типа bigint.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.0.2Добавлено в: v0.0.2

Асинхронный stat(2). Обратный вызов получает два аргумента (err, stats), где stats — это объект <fs.Stats>.

В случае ошибки, err.code будет одним из Общие системные ошибки.

fs.stat() следует символическим ссылкам. Используйте fs.lstat(), чтобы просмотреть сами ссылки.

Использование fs.stat() для проверки существования файла перед вызовом fs.open(), fs.readFile() или fs.writeFile() не рекомендуется. Вместо этого пользовательский код должен открывать/читать/записывать файл напрямую и обрабатывать ошибку, которая возникает, если файл недоступен.

Для проверки существования файла без последующего его изменения рекомендуется использовать fs.access().

Например, при следующей структуре каталогов:

text
- txtDir
-- file.txt
- app.js

Следующая программа проверит статистику указанных путей:

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

Полученный вывод будет выглядеть примерно так:

bash
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

Асинхронный statfs(2). Возвращает информацию о смонтированной файловой системе, содержащей path. Обратный вызов получает два аргумента (err, stats), где stats — это объект <fs.StatFs>.

В случае ошибки err.code будет одним из Общие системные ошибки.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v12.0.0Если аргумент type не определен, Node автоматически определит тип target и автоматически выберет dir или file.
v7.6.0Аргументы target и path могут быть объектами WHATWG URL с использованием протокола file:. Поддержка в настоящее время все еще экспериментальная.
v0.1.31Добавлено в: v0.1.31

Создает ссылку с именем path, указывающую на target. В обратный вызов завершения не передаются никакие аргументы, кроме возможного исключения.

См. документацию POSIX symlink(2) для получения более подробной информации.

Аргумент type доступен только в Windows и игнорируется на других платформах. Он может быть установлен в 'dir', 'file' или 'junction'. Если аргумент type имеет значение null, Node.js автоматически определит тип target и использует 'file' или 'dir'. Если target не существует, будет использоваться 'file'. Точки соединения Windows требуют, чтобы путь к месту назначения был абсолютным. При использовании 'junction' аргумент target будет автоматически нормализован до абсолютного пути. Точки соединения в томах NTFS могут указывать только на каталоги.

Относительные цели являются относительными к родительскому каталогу ссылки.

js
import { symlink } from 'node:fs'

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

В приведенном выше примере создается символическая ссылка mewtwo, которая указывает на mew в том же каталоге:

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

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v16.0.0Возвращаемая ошибка может быть AggregateError, если возвращается более одной ошибки.
v10.0.0Параметр callback больше не является необязательным. Отсутствие его передачи вызовет ошибку TypeError во время выполнения.
v7.0.0Параметр callback больше не является необязательным. Отсутствие его передачи вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.8.6Добавлено в: v0.8.6

Усекает файл. В функцию обратного вызова передаются только возможные исключения. В качестве первого аргумента также может быть передан дескриптор файла. В этом случае вызывается fs.ftruncate().

js
import { truncate } from 'node:fs'
// Предполагается, что 'path/file.txt' — это обычный файл.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt was truncated')
})
js
const { truncate } = require('node:fs')
// Предполагается, что 'path/file.txt' — это обычный файл.
truncate('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt was truncated')
})

Передача дескриптора файла устарела и может привести к возникновению ошибки в будущем.

См. документацию POSIX truncate(2) для получения более подробной информации.

fs.unlink(path, callback)

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Отсутствие его передачи вызовет ошибку TypeError во время выполнения.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Параметр callback больше не является необязательным. Отсутствие его передачи вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.0.2Добавлено в: v0.0.2

Асинхронно удаляет файл или символическую ссылку. В функцию обратного вызова передаются только возможные исключения.

js
import { unlink } from 'node:fs'
// Предполагается, что 'path/file.txt' — обычный файл.
unlink('path/file.txt', err => {
  if (err) throw err
  console.log('path/file.txt был удалён')
})

fs.unlink() не будет работать с директориями, пустыми или нет. Для удаления директории используйте fs.rmdir().

См. документацию POSIX unlink(2) для получения более подробной информации.

fs.unwatchFile(filename[, listener])

Добавлено в: v0.1.31

Прекращает наблюдение за изменениями в filename. Если указан listener, удаляется только этот обработчик. В противном случае удаляются все обработчики, что фактически прекращает наблюдение за filename.

Вызов fs.unwatchFile() с именем файла, за которым не ведётся наблюдение, не приводит к ошибке.

Использование fs.watch() более эффективно, чем fs.watchFile() и fs.unwatchFile(). fs.watch() следует использовать вместо fs.watchFile() и fs.unwatchFile(), когда это возможно.

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v10.0.0Параметр callback больше не является необязательным. Непередача его вызовет ошибку TypeError во время выполнения.
v8.0.0NaN, Infinity и -Infinity больше не являются допустимыми спецификаторами времени.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Параметр callback больше не является необязательным. Непередача его вызовет предупреждение о устаревании с идентификатором DEP0013.
v4.1.0Числовые строки, NaN и Infinity теперь являются допустимыми спецификаторами времени.
v0.4.2Добавлено в: v0.4.2

Изменить метки времени файловой системы объекта, на который ссылается path.

Аргументы atime и mtime следуют этим правилам:

  • Значения могут быть числами, представляющими время эпохи Unix в секундах, объектами Date или числовыми строками, такими как '123456789.0'.
  • Если значение не может быть преобразовано в число или является NaN, Infinity или -Infinity, будет выброшена ошибка Error.

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

[История]

ВерсияИзменения
v19.1.0Добавлена поддержка рекурсии для Linux, AIX и IBMi.
v15.9.0, v14.17.0Добавлена поддержка закрытия наблюдателя с помощью AbortSignal.
v7.6.0Параметр filename может быть объектом WHATWG URL с использованием протокола file:.
v7.0.0Переданный объект options никогда не будет изменен.
v0.5.10Добавлено в: v0.5.10
  • filename <строка> | <Buffer> | <URL>

  • options <строка> | <Объект>

    • persistent <булево> Указывает, должен ли процесс продолжать работу, пока файлы находятся под наблюдением. По умолчанию: true.
    • recursive <булево> Указывает, следует ли наблюдать за всеми подкаталогами или только за текущим каталогом. Это применимо, когда указан каталог, и только на поддерживаемых платформах (см. ограничения). По умолчанию: false.
    • encoding <строка> Задает кодировку символов, которая будет использоваться для имени файла, передаваемого в обработчик. По умолчанию: 'utf8'.
    • signal <AbortSignal> позволяет закрыть наблюдатель с помощью AbortSignal.
  • listener <Функция> | <неопределено> По умолчанию: undefined

  • Возвращает: <fs.FSWatcher>

Отслеживает изменения в filename, где filename — это файл или каталог.

Второй аргумент является необязательным. Если options предоставлен в виде строки, он указывает encoding. В противном случае options должен быть передан как объект.

Обратный вызов обработчика получает два аргумента (eventType, filename). eventType — это либо 'rename', либо 'change', а filename — имя файла, который вызвал событие.

На большинстве платформ 'rename' генерируется всякий раз, когда имя файла появляется или исчезает в каталоге.

Обратный вызов обработчика прикрепляется к событию 'change', генерируемому <fs.FSWatcher>, но это не то же самое, что значение 'change' для eventType.

Если передан signal, прерывание соответствующего AbortController закроет возвращаемый <fs.FSWatcher>.

Оговорки

API fs.watch не обладает 100% кроссплатформенной согласованностью и недоступен в некоторых ситуациях.

В Windows события не будут генерироваться, если наблюдаемая директория перемещена или переименована. Ошибка EPERM сообщается при удалении наблюдаемой директории.

Доступность

Эта функция зависит от наличия в базовой операционной системе способа получать уведомления об изменениях в файловой системе.

  • В системах Linux используется inotify(7).
  • В системах BSD используется kqueue(2).
  • В macOS используется kqueue(2) для файлов и FSEvents для директорий.
  • В системах SunOS (включая Solaris и SmartOS) используются event ports.
  • В системах Windows эта функция зависит от ReadDirectoryChangesW.
  • В системах AIX эта функция зависит от AHAFS, который должен быть включен.
  • В системах IBM i эта функция не поддерживается.

Если базовая функциональность недоступна по какой-либо причине, то fs.watch() не сможет функционировать и может выбросить исключение. Например, наблюдение за файлами или директориями может быть ненадежным, а в некоторых случаях невозможным, в сетевых файловых системах (NFS, SMB и т.д.) или файловых системах хоста при использовании программного обеспечения для виртуализации, такого как Vagrant или Docker.

Все еще возможно использовать fs.watchFile(), который использует опрос stat, но этот метод медленнее и менее надежен.

Индексные дескрипторы (иноды)

В системах Linux и macOS fs.watch() разрешает путь к иноду и следит за инодом. Если наблюдаемый путь удален и воссоздан, ему присваивается новый инод. Наблюдение выдаст событие об удалении, но будет продолжать наблюдение за оригинальным инодом. События для нового инода генерироваться не будут. Это ожидаемое поведение.

Файлы AIX сохраняют тот же инод в течение всего времени существования файла. Сохранение и закрытие наблюдаемого файла в AIX приведет к двум уведомлениям (одному о добавлении нового содержимого и одному об усечении).

Аргумент filename

Предоставление аргумента filename в обратном вызове поддерживается только в Linux, macOS, Windows и AIX. Даже на поддерживаемых платформах предоставление filename не гарантируется. Поэтому не предполагайте, что аргумент filename всегда предоставляется в обратном вызове, и предусмотрите логику резервного копирования, если он равен null.

js
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 может быть объектом WHATWG URL с использованием протокола file:.
v0.1.31Добавлено в: v0.1.31

Отслеживает изменения в filename. Обратный вызов listener будет вызываться каждый раз при доступе к файлу.

Аргумент options может быть опущен. Если он предоставлен, он должен быть объектом. Объект options может содержать булево значение persistent, указывающее, должен ли процесс продолжать работу, пока файлы находятся под наблюдением. Объект options может указывать свойство interval, указывающее, как часто целевой объект должен опрашиваться в миллисекундах.

listener получает два аргумента: текущий объект stat и предыдущий объект stat:

js
import { watchFile } from 'node:fs'

watchFile('message.text', (curr, prev) => {
  console.log(`текущее значение mtime: ${curr.mtime}`)
  console.log(`предыдущее значение mtime: ${prev.mtime}`)
})

Эти объекты stat являются экземплярами fs.Stat. Если опция bigint равна true, числовые значения в этих объектах задаются как BigInt.

Чтобы получать уведомления о том, что файл был изменен, а не просто доступен, необходимо сравнить curr.mtimeMs и prev.mtimeMs.

Если операция fs.watchFile приводит к ошибке ENOENT, она вызовет listener один раз со всеми полями, установленными в ноль (или для дат — эпоха Unix). Если файл будет создан позже, listener будет вызван снова с последними объектами stat. Это изменение функциональности, начиная с версии v0.10.

Использование fs.watch() более эффективно, чем fs.watchFile и fs.unwatchFile. fs.watch следует использовать вместо fs.watchFile и fs.unwatchFile, когда это возможно.

Когда файл, за которым наблюдает fs.watchFile(), исчезает и появляется снова, содержимое previous во втором событии обратного вызова (повторное появление файла) будет таким же, как содержимое previous в первом событии обратного вызова (его исчезновение).

Это происходит, когда:

  • файл удаляется, а затем восстанавливается
  • файл переименовывается, а затем переименовывается второй раз в исходное имя

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

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v14.0.0Параметр buffer больше не будет приводить неподдерживаемый ввод к строкам.
v10.10.0Параметр buffer теперь может быть любым TypedArray или DataView.
v10.0.0Параметр callback больше не является необязательным. Отсутствие его вызовет исключение TypeError во время выполнения.
v7.4.0Параметр buffer теперь может быть Uint8Array.
v7.2.0Параметры offset и length теперь являются необязательными.
v7.0.0Параметр callback больше не является необязательным. Отсутствие его вызовет предупреждение о устаревании с идентификатором DEP0013.
v0.0.2Добавлено в: v0.0.2

Записывает buffer в файл, указанный fd.

offset определяет часть буфера, которая будет записана, а length — целое число, указывающее количество байтов для записи.

position ссылается на смещение от начала файла, куда должны быть записаны эти данные. Если typeof position !== 'number', данные будут записаны в текущую позицию. См. pwrite(2).

Обратный вызов получит три аргумента (err, bytesWritten, buffer), где bytesWritten указывает, сколько байтов было записано из buffer.

Если этот метод вызывается как его версия util.promisify(), он возвращает обещание для объекта со свойствами bytesWritten и buffer.

Небезопасно использовать fs.write() несколько раз для одного и того же файла, не дожидаясь обратного вызова. Для этого сценария рекомендуется использовать fs.createWriteStream().

В Linux позиционные записи не работают, если файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

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

Добавлено в: v18.3.0, v16.17.0

Записывает buffer в файл, указанный fd.

Аналогично описанной выше функции fs.write, эта версия принимает необязательный объект options. Если объект options не указан, будут использоваться значения по умолчанию, указанные выше.

fs.write(fd, string[, position[, encoding]], callback)

[История]

ВерсияИзменения
v19.0.0Передача в параметр string объекта с собственной функцией toString больше не поддерживается.
v17.8.0Передача в параметр string объекта с собственной функцией toString устарела.
v14.12.0Параметр string будет преобразовывать в строку объект с явной функцией toString.
v14.0.0Параметр string больше не будет приводить неподдерживаемые входные данные к строкам.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.2.0Параметр position теперь является необязательным.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение об устаревании с идентификатором DEP0013.
v0.11.5Добавлено в: v0.11.5

Записывает string в файл, указанный fd. Если string не является строкой, выбрасывается исключение.

position указывает смещение от начала файла, куда должны быть записаны данные. Если typeof position !== 'number', данные будут записаны в текущую позицию. См. pwrite(2).

encoding — ожидаемая кодировка строки.

Функция обратного вызова получит аргументы (err, written, string), где written указывает, сколько байт потребовалось для записи переданной строки. Количество записанных байт не обязательно совпадает с количеством записанных символов строки. См. Buffer.byteLength.

Небезопасно использовать fs.write() несколько раз для одного и того же файла, не дожидаясь обратного вызова. В этом случае рекомендуется использовать fs.createWriteStream().

В Linux позиционные записи не работают, если файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

В Windows, если дескриптор файла подключен к консоли (например, fd == 1 или stdout), строка, содержащая не-ASCII символы, по умолчанию не будет отображаться правильно, независимо от используемой кодировки. Можно настроить консоль для правильного отображения UTF-8, изменив активную кодовую страницу с помощью команды chcp 65001. См. документацию по chcp для получения более подробной информации.

fs.writeFile(file, data[, options], callback)

[История]

ВерсияИзменения
v21.0.0, v20.10.0Теперь поддерживается параметр flush.
v19.0.0Больше не поддерживается передача в параметр string объекта с собственной функцией toString.
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v17.8.0Передача в параметр string объекта с собственной функцией toString устарела.
v16.0.0Возвращаемая ошибка может быть AggregateError, если возвращается более одной ошибки.
v15.2.0, v14.17.0Аргумент options может включать AbortSignal для прерывания текущего запроса writeFile.
v14.12.0Параметр data будет преобразовывать в строку объект с явно указанной функцией toString.
v14.0.0Параметр data больше не будет приводить неподдерживаемые входные данные к строкам.
v10.10.0Параметр data теперь может быть любым TypedArray или DataView.
v10.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет ошибку TypeError во время выполнения.
v7.4.0Параметр data теперь может быть Uint8Array.
v7.0.0Параметр callback больше не является необязательным. Его отсутствие вызовет предупреждение об устаревании с идентификатором DEP0013.
v5.0.0Параметр file теперь может быть дескриптором файла.
v0.1.29Добавлено в: v0.1.29

Если file — это имя файла, асинхронно записывает данные в файл, заменяя файл, если он уже существует. data может быть строкой или буфером.

Если file — это дескриптор файла, поведение аналогично прямому вызову fs.write() (что рекомендуется). См. примечания ниже об использовании дескриптора файла.

Параметр encoding игнорируется, если data — это буфер.

Параметр mode влияет только на вновь созданный файл. См. fs.open() для получения более подробной информации.

js
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('Файл сохранен!')
})

Если options — это строка, то она указывает кодировку:

js
import { writeFile } from 'node:fs'

writeFile('message.txt', 'Hello Node.js', 'utf8', callback)

Небезопасно использовать fs.writeFile() несколько раз для одного и того же файла, не дожидаясь обратного вызова. Для этого сценария рекомендуется использовать fs.createWriteStream().

Аналогично fs.readFile - fs.writeFile - это вспомогательный метод, который внутренне выполняет несколько вызовов write для записи буфера, переданного ему. Для кода, чувствительного к производительности, следует рассмотреть использование fs.createWriteStream().

Можно использовать <AbortSignal> для отмены fs.writeFile(). Отмена выполняется "по возможности", и некоторое количество данных, вероятно, все еще будет записано.

js
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(), например:

js
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_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v12.9.0Добавлено в: v12.9.0

Запись массива ArrayBufferView в файл, указанный fd, используя writev().

position — это смещение от начала файла, куда должны быть записаны эти данные. Если typeof position !== 'number', данные будут записаны в текущую позицию.

Обратный вызов получит три аргумента: err, bytesWritten и buffers. bytesWritten — это количество байтов, записанных из buffers.

Если этот метод был util.promisify(), он возвращает promise для Object со свойствами bytesWritten и buffers.

Небезопасно использовать fs.writev() несколько раз в одном файле, не дожидаясь обратного вызова. В этом случае используйте fs.createWriteStream().

В Linux позиционные записи не работают, когда файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

Синхронный API

Синхронные API выполняют все операции синхронно, блокируя цикл событий до завершения или сбоя операции.

fs.accessSync(path[, mode])

[История]

ВерсияИзменения
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:
v0.11.15Добавлено в: v0.11.15

Синхронно проверяет права пользователя на доступ к файлу или каталогу, указанному в path. Аргумент mode — это необязательное целое число, которое указывает, какие проверки доступности следует выполнить. mode должен быть либо значением fs.constants.F_OK, либо маской, состоящей из побитового ИЛИ любого из fs.constants.R_OK, fs.constants.W_OK и fs.constants.X_OK (например, fs.constants.W_OK | fs.constants.R_OK). Проверьте Константы доступа к файлам для возможных значений mode.

Если какая-либо из проверок доступности завершится неудачей, будет выброшена ошибка Error. В противном случае метод вернет undefined.

js
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

Синхронно добавляет данные в файл, создавая файл, если он еще не существует. data может быть строкой или <Buffer>.

Параметр mode влияет только на вновь созданный файл. Подробнее см. в разделе fs.open().

js
import { appendFileSync } from 'node:fs'

try {
  appendFileSync('message.txt', 'data to append')
  console.log('Данные "data to append" были добавлены в файл!')
} catch (err) {
  /* Обработка ошибки */
}

Если options — это строка, то она указывает кодировку:

js
import { appendFileSync } from 'node:fs'

appendFileSync('message.txt', 'data to append', 'utf8')

path может быть указан как числовой дескриптор файла, который был открыт для добавления (с помощью fs.open() или fs.openSync()). Дескриптор файла не будет закрыт автоматически.

js
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 может быть объектом WHATWG URL с использованием протокола file:
v0.6.7Добавлено в: v0.6.7

Для подробной информации см. документацию асинхронной версии этого API: fs.chmod().

См. документацию POSIX chmod(2) для получения более подробной информации.

fs.chownSync(path, uid, gid)

[История]

ВерсияИзменения
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:
v0.1.97Добавлено в: v0.1.97

Синхронно изменяет владельца и группу файла. Возвращает undefined. Это синхронная версия fs.chown().

См. документацию POSIX chown(2) для получения более подробной информации.

fs.closeSync(fd)

Добавлено в: v0.1.21

Закрывает дескриптор файла. Возвращает undefined.

Вызов fs.closeSync() для любого дескриптора файла (fd), который в настоящее время используется через любую другую операцию fs, может привести к неопределенному поведению.

См. документацию POSIX close(2) для получения более подробной информации.

fs.copyFileSync(src, dest[, mode])

[История]

ВерсияИзменения
v14.0.0Аргумент flags изменён на mode и введена более строгая проверка типов.
v8.5.0Добавлено в: v8.5.0

Синхронно копирует src в dest. По умолчанию, dest перезаписывается, если он уже существует. Возвращает undefined. Node.js не гарантирует атомарность операции копирования. Если ошибка возникает после того, как файл назначения был открыт для записи, Node.js попытается удалить файл назначения.

mode — это необязательное целое число, которое указывает поведение операции копирования. Можно создать маску, состоящую из побитовой дизъюнкции двух или более значений (например, fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

  • fs.constants.COPYFILE_EXCL: Операция копирования завершится ошибкой, если dest уже существует.
  • fs.constants.COPYFILE_FICLONE: Операция копирования попытается создать reflink с копированием при записи. Если платформа не поддерживает копирование при записи, используется резервный механизм копирования.
  • fs.constants.COPYFILE_FICLONE_FORCE: Операция копирования попытается создать reflink с копированием при записи. Если платформа не поддерживает копирование при записи, операция завершится ошибкой.
js
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Принимает дополнительный параметр mode для указания поведения копирования как аргумент mode в fs.copyFile().
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 <строка> путь назначения для копирования.

    • Возвращает: <булево> Любое значение, не являющееся Promise, которое может быть приведено к типу boolean.

    • force <булево> перезаписать существующий файл или каталог. Операция копирования будет игнорировать ошибки, если вы установите это значение в false, а назначение существует. Используйте параметр errorOnExist для изменения этого поведения. По умолчанию: true.

    • mode <целое число> модификаторы для операции копирования. По умолчанию: 0. См. флаг mode в fs.copyFileSync().

    • preserveTimestamps <булево> Если true, метки времени из src будут сохранены. По умолчанию: false.

    • recursive <булево> копировать каталоги рекурсивно. По умолчанию: false

    • verbatimSymlinks <булево> Если true, разрешение пути для символических ссылок будет пропущено. По умолчанию: false

Синхронно копирует всю структуру каталога из src в dest, включая подкаталоги и файлы.

При копировании каталога в другой каталог шаблоны не поддерживаются, и поведение аналогично cp dir1/ dir2/.

fs.existsSync(path)

[История]

ВерсияИзменения
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:
v0.1.21Добавлено в: v0.1.21

Возвращает true, если путь существует, false в противном случае.

Для подробной информации см. документацию асинхронной версии этого API: fs.exists().

fs.exists() устарел, но fs.existsSync() — нет. Параметр callback для fs.exists() принимает параметры, несовместимые с другими обратными вызовами Node.js. fs.existsSync() не использует обратный вызов.

js
import { existsSync } from 'node:fs'

if (existsSync('/etc/passwd')) console.log('Путь существует.')

fs.fchmodSync(fd, mode)

Добавлено в: v0.4.7

Устанавливает права доступа к файлу. Возвращает undefined.

См. документацию POSIX fchmod(2) для получения более подробной информации.

fs.fchownSync(fd, uid, gid)

Добавлено в: v0.4.7

Устанавливает владельца файла. Возвращает undefined.

См. документацию POSIX fchown(2) для получения более подробной информации.

fs.fdatasyncSync(fd)

Добавлено в: v0.1.96

Принудительно выполняет все текущие операции ввода-вывода, связанные с файлом, до состояния синхронного завершения ввода-вывода операционной системы. Подробности см. в документации POSIX fdatasync(2). Возвращает undefined.

fs.fstatSync(fd[, options])

[История]

ВерсияИзменения
v10.5.0Принимает дополнительный объект options для указания, должны ли возвращаемые числовые значения быть bigint.
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

Запрос на сброс всех данных для открытого дескриптора файла на устройство хранения. Конкретная реализация зависит от операционной системы и устройства. Подробности см. в документации POSIX fsync(2). Возвращает undefined.

fs.ftruncateSync(fd[, len])

Добавлено в: v0.8.6

Усекает дескриптор файла. Возвращает undefined.

Подробную информацию см. в документации асинхронной версии этого API: fs.ftruncate().

fs.futimesSync(fd, atime, mtime)

[История]

ВерсияИзменения
v4.1.0Теперь допускаются числовые строки, NaN и Infinity в качестве спецификаторов времени.
v0.4.2Добавлено в: v0.4.2

Синхронная версия 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 <булево> true, если glob должен возвращать пути в виде Dirents, false в противном случае. По умолчанию: false.
  • Возвращает: <массив строк> пути к файлам, соответствующим шаблону.

js
import { globSync } from 'node:fs'

console.log(globSync('**/*.js'))
js
const { globSync } = require('node:fs')

console.log(globSync('**/*.js'))

fs.lchmodSync(path, mode)

Устарело с версии: v0.4.7

Изменяет права доступа к символической ссылке. Возвращает undefined.

Этот метод реализован только в macOS.

См. документацию POSIX lchmod(2) для получения более подробной информации.

fs.lchownSync(path, uid, gid)

[История]

ВерсияИзменения
v10.6.0Этот API больше не устарел.
v0.4.7Устаревание только в документации.

Устанавливает владельца для пути. Возвращает undefined.

См. документацию POSIX lchown(2) для получения более подробной информации.

fs.lutimesSync(path, atime, mtime)

Добавлен в: v14.5.0, v12.19.0

Изменяет метки времени файловой системы символической ссылки, на которую ссылается path. Возвращает undefined или вызывает исключение, если параметры неверны или операция завершилась неудачей. Это синхронная версия fs.lutimes().

fs.linkSync(existingPath, newPath)

[История]

ВерсияИзменения
v7.6.0Параметры existingPath и newPath могут быть объектами WHATWG URL с использованием протокола file:. Поддержка пока что экспериментальная.
v0.1.31Добавлено в: v0.1.31

Создает новую ссылку из existingPath в newPath. Более подробную информацию см. в документации POSIX link(2). Возвращает undefined.

fs.lstatSync(path[, options])

[История]

ВерсияИзменения
v15.3.0, v14.17.0Принимает опцию throwIfNoEntry для указания, должно ли быть выброшено исключение, если запись не существует.
v10.5.0Принимает дополнительный объект options для указания, должны ли возвращаемые числовые значения быть типа bigint.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v0.1.30Добавлено в: v0.1.30
  • path <string> | <Buffer> | <URL>

  • options <Object>

    • bigint <boolean> Указывает, должны ли числовые значения в возвращаемом объекте <fs.Stats> быть типа bigint. По умолчанию: false.
    • throwIfNoEntry <boolean> Указывает, должно ли быть выброшено исключение, если запись файловой системы не существует, вместо возвращения undefined. По умолчанию: true.
  • Возвращает: <fs.Stats>

Извлекает <fs.Stats> для символической ссылки, на которую указывает path.

Более подробную информацию см. в документации POSIX lstat(2).

fs.mkdirSync(path[, options])

[История]

ВерсияИзменения
v13.11.0, v12.17.0В режиме recursive теперь возвращается первый созданный путь.
v10.12.0Вторым аргументом теперь может быть объект options со свойствами recursive и mode.
v7.6.0Параметр path теперь может быть объектом WHATWG URL с использованием протокола file:.
v0.1.21Добавлено в: v0.1.21

Синхронно создаёт директорию. Возвращает 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

Возвращает путь к созданной директории.

Для подробной информации см. документацию асинхронной версии этого 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 <строка> | <Buffer> | <URL>

  • options <Объект>

    • encoding <строка> | <null> По умолчанию: 'utf8'
    • bufferSize <число> Количество записей каталога, которые буферизуются внутренне при чтении из каталога. Более высокие значения обеспечивают лучшую производительность, но большее потребление памяти. По умолчанию: 32
    • recursive <булево> По умолчанию: 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 может быть объектом WHATWG URL с использованием протокола file:.
v0.1.21Добавлено в: v0.1.21

Возвращает целое число, представляющее дескриптор файла.

Для подробной информации см. документацию асинхронной версии этого API: fs.open().

fs.readdirSync(path[, options])

[История]

ВерсияИзменения
v20.1.0, v18.17.0Добавлен параметр recursive.
v10.10.0Добавлен новый параметр withFileTypes.
v7.6.0Параметр path может быть объектом WHATWG URL с протоколом file:.
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 может быть объектом WHATWG URL с использованием протокола file:
v5.0.0Параметр path теперь может быть файловым дескриптором.
v0.1.8Добавлено в: v0.1.8

Возвращает содержимое path.

Для получения подробной информации см. документацию асинхронной версии этого API: fs.readFile().

Если указан параметр encoding, то функция возвращает строку. В противном случае она возвращает буфер.

Аналогично fs.readFile(), когда путь является директорией, поведение fs.readFileSync() зависит от платформы.

js
import { readFileSync } from 'node:fs'

// macOS, Linux и Windows
readFileSync('<directory>')
// => [Error: EISDIR: недопустимая операция над директорией, чтение <directory>]

// FreeBSD
readFileSync('<directory>') // => <данные>

fs.readlinkSync(path[, options])

[История]

ВерсияИзменения
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:
v0.1.31Добавлено в: v0.1.31

Возвращает строковое значение символической ссылки.

Дополнительные сведения см. в документации POSIX readlink(2).

Необязательный аргумент options может быть строкой, указывающей кодировку, или объектом со свойством encoding, указывающим используемую кодировку символов для возвращаемого пути ссылки. Если encoding установлен в 'buffer', возвращаемый путь ссылки будет передан как объект <Buffer>.

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

[История]

ВерсияИзменения
v10.10.0Параметр buffer теперь может быть любым TypedArray или DataView.
v6.0.0Параметр length теперь может быть равен 0.
v0.1.21Добавлено в: v0.1.21

Возвращает количество bytesRead.

Подробную информацию см. в документации асинхронной версии этого API: fs.read().

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

[История]

ВерсияИзменения
v13.13.0, v12.17.0Возможно передать объект options для опциональной установки смещения, длины и позиции.
v13.13.0, v12.17.0Добавлено в: v13.13.0, v12.17.0

Возвращает количество bytesRead.

Аналогично описанной выше функции fs.readSync, эта версия принимает необязательный объект options. Если объект options не указан, будут использованы значения по умолчанию, указанные выше.

Для получения подробной информации см. документацию асинхронной версии этого API: fs.read().

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

Добавлено в: v13.13.0, v12.17.0

Для получения подробной информации см. документацию асинхронной версии этого API: fs.readv().

fs.realpathSync(path[, options])

[История]

ВерсияИзменения
v8.0.0Добавлена поддержка разрешения каналов/сокетов.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:.
v6.4.0Вызов realpathSync снова работает для различных пограничных случаев в Windows.
v6.0.0Параметр cache удален.
v0.1.31Добавлено в: v0.1.31

Возвращает разрешенное имя пути.

Для подробной информации см. документацию асинхронной версии этого API: fs.realpath().

fs.realpathSync.native(path[, options])

Добавлено в: v9.2.0

Синхронный realpath(3).

Поддерживаются только пути, которые могут быть преобразованы в строки UTF8.

Необязательный аргумент options может быть строкой, указывающей кодировку, или объектом со свойством encoding, указывающим используемую кодировку символов для возвращаемого пути. Если encoding установлен в 'buffer', возвращаемый путь будет передан в виде объекта <Buffer>.

В Linux, когда Node.js связан с библиотекой musl libc, файловая система procfs должна быть смонтирована в /proc, чтобы эта функция работала. Glibc не имеет этого ограничения.

fs.renameSync(oldPath, newPath)

[История]

ВерсияИзменения
v7.6.0Параметры oldPath и newPath могут быть объектами WHATWG URL с использованием протокола file:. Поддержка на данный момент всё ещё экспериментальная.
v0.1.21Добавлено в: v0.1.21

Переименовывает файл из oldPath в newPath. Возвращает undefined.

См. документацию POSIX rename(2) для получения более подробной информации.

fs.rmdirSync(path[, options])

[История]

ВерсияИзменения
v16.0.0Использование fs.rmdirSync(path, { recursive: true }) для path, являющегося файлом, больше не допускается и приводит к ошибке ENOENT в Windows и ошибке ENOTDIR в POSIX.
v16.0.0Использование fs.rmdirSync(path, { recursive: true }) для path, который не существует, больше не допускается и приводит к ошибке 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 может быть объектом WHATWG URL с использованием протокола file:.
v0.1.21Добавлено в: v0.1.21
  • path <строка> | <Buffer> | <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() для файла (не каталога) приводит к ошибке ENOENT в Windows и ошибке ENOTDIR в POSIX.

Чтобы получить поведение, аналогичное команде Unix rm -rf, используйте fs.rmSync() с параметрами { recursive: true, force: true }.

fs.rmSync(path[, options])

[История]

ВерсияИзменения
v17.3.0, v16.14.0Параметр path может быть объектом WHATWG URL с использованием протокола file:
v14.14.0Добавлено в: v14.14.0
  • path <string> | <Buffer> | <URL>
  • options <Object>
    • force <boolean> Если true, исключения игнорируются, если path не существует. По умолчанию: false.
    • maxRetries <integer> Если возникает ошибка EBUSY, EMFILE, ENFILE, ENOTEMPTY или EPERM, Node.js повторит операцию с линейной экспоненциальной задержкой в retryDelay миллисекунд дольше при каждой попытке. Этот параметр представляет количество попыток. Этот параметр игнорируется, если параметр recursive не равен true. По умолчанию: 0.
    • recursive <boolean> Если true, выполняется рекурсивное удаление каталога. В рекурсивном режиме операции повторяются при сбое. По умолчанию: false.
    • retryDelay <integer> Время ожидания в миллисекундах между повторными попытками. Этот параметр игнорируется, если параметр recursive не равен true. По умолчанию: 100.

Синхронно удаляет файлы и каталоги (моделируется на стандартной утилите POSIX rm). Возвращает undefined.

fs.statSync(path[, options])

[История]

ВерсияИзменения
v15.3.0, v14.17.0Принимает параметр throwIfNoEntry для указания, следует ли генерировать исключение, если запись не существует.
v10.5.0Принимает дополнительный объект options для указания, должны ли возвращаемые числовые значения быть bigint.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:
v0.1.21Добавлено в: v0.1.21
  • path <string> | <Buffer> | <URL>

  • options <Object>

    • bigint <boolean> Должны ли числовые значения в возвращаемом объекте <fs.Stats> быть bigint. По умолчанию: false.
    • throwIfNoEntry <boolean> Следует ли генерировать исключение, если запись в файловой системе не существует, вместо возврата undefined. По умолчанию: true.
  • Возвращает: <fs.Stats>

Извлекает <fs.Stats> для пути.

fs.statfsSync(path[, options])

Добавлено в: v19.6.0, v18.15.0

Синхронный statfs(2). Возвращает информацию о смонтированной файловой системе, содержащей path.

В случае ошибки, err.code будет одним из Общие системные ошибки.

fs.symlinkSync(target, path[, type])

[История]

ВерсияИзменения
v12.0.0Если аргумент type оставлен неопределенным, Node автоматически определит тип target и автоматически выберет dir или file.
v7.6.0Параметры target и path могут быть объектами WHATWG URL с использованием протокола file:. Поддержка в настоящее время все еще экспериментальная.
v0.1.31Добавлено в: v0.1.31

Возвращает undefined.

Для подробной информации см. документацию асинхронной версии этого API: fs.symlink().

fs.truncateSync(path[, len])

Добавлено в: v0.8.6

Усекает файл. Возвращает undefined. Дескриптор файла также может быть передан в качестве первого аргумента. В этом случае вызывается fs.ftruncateSync().

Передача дескриптора файла устарела и может привести к возникновению ошибки в будущем.

fs.unlinkSync(path)

[История]

ВерсияИзменения
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:
v0.1.21Добавлено в: v0.1.21

Синхронный unlink(2). Возвращает undefined.

fs.utimesSync(path, atime, mtime)

[История]

ВерсияИзменения
v8.0.0NaN, Infinity и -Infinity больше не являются допустимыми спецификаторами времени.
v7.6.0Параметр path может быть объектом WHATWG URL с использованием протокола file:
v4.1.0Числовые строки, NaN и Infinity теперь разрешены в качестве спецификаторов времени.
v0.4.2Добавлено в: v0.4.2

Возвращает undefined.

Для подробной информации см. документацию асинхронной версии этого API: fs.utimes().

fs.writeFileSync(file, data[, options])

[История]

ВерсияИзменения
v21.0.0, v20.10.0Теперь поддерживается параметр flush.
v19.0.0Передача в параметр data объекта с собственной функцией toString больше не поддерживается.
v17.8.0Передача в параметр data объекта с собственной функцией toString устарела.
v14.12.0Параметр data будет сериализовать объект с явно указанной функцией toString.
v14.0.0Параметр data больше не будет приводить неподдерживаемые входные данные к строкам.
v10.10.0Параметр data теперь может быть любым TypedArray или DataView.
v7.4.0Параметр data теперь может быть Uint8Array.
v5.0.0Параметр file теперь может быть дескриптором файла.
v0.1.29Добавлено в: v0.1.29

Возвращает 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

Для подробной информации см. документацию асинхронной версии этого API: fs.write(fd, buffer...).

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

Добавлено в: v18.3.0, v16.17.0

Для подробной информации см. документацию асинхронной версии этого 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

Для подробной информации см. документацию асинхронной версии этого API: fs.write(fd, string...).

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

Добавлено в: v12.9.0

Для подробной информации см. документацию асинхронной версии этого API: fs.writev().

Общие объекты

Общие объекты используются всеми вариантами API файловой системы (promise, callback и синхронный).

Класс: fs.Dir

Добавлен в: v12.12.0

Класс, представляющий поток каталога.

Создается с помощью fs.opendir(), fs.opendirSync() или fsPromises.opendir().

js
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

Асинхронно закрывает дескриптор базового ресурса каталога. Последующие операции чтения приведут к ошибкам.

Возвращается промис, который будет выполнен после закрытия ресурса.

dir.close(callback)

[История]

ВерсияИзменения
v18.0.0Передача недопустимого обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK.
v12.12.0Добавлено в: v12.12.0

Асинхронно закрывает дескриптор базового ресурса каталога. Последующие операции чтения приведут к ошибкам.

Обратный вызов callback будет вызван после закрытия дескриптора ресурса.

dir.closeSync()

Добавлен в: v12.12.0

Синхронно закрывает дескриптор базового ресурса каталога. Последующие операции чтения приведут к ошибкам.

dir.path

Добавлен в: v12.12.0

Только для чтения путь к этому каталогу, как он был предоставлен в fs.opendir(), fs.opendirSync() или fsPromises.opendir().

dir.read()

Добавлено в: v12.12.0

Асинхронно читает следующую запись каталога через readdir(3) как <fs.Dirent>.

Возвращается promise, который будет выполнен с <fs.Dirent> или null, если больше нет записей каталога для чтения.

Записи каталога, возвращаемые этой функцией, не имеют определенного порядка, как предоставляется базовыми механизмами каталогов операционной системы. Записи, добавленные или удаленные во время итерации по каталогу, могут не быть включены в результаты итерации.

dir.read(callback)

Добавлено в: v12.12.0

Асинхронно читает следующую запись каталога через readdir(3) как <fs.Dirent>.

После завершения чтения callback будет вызван с <fs.Dirent> или null, если больше нет записей каталога для чтения.

Записи каталога, возвращаемые этой функцией, не имеют определенного порядка, как предоставляется базовыми механизмами каталогов операционной системы. Записи, добавленные или удаленные во время итерации по каталогу, могут не быть включены в результаты итерации.

dir.readSync()

Добавлено в: v12.12.0

Синхронно читает следующую запись каталога как <fs.Dirent>. См. документацию POSIX readdir(3) для получения более подробной информации.

Если больше нет записей каталога для чтения, будет возвращено null.

Записи каталога, возвращаемые этой функцией, не имеют определенного порядка, как предоставляется базовыми механизмами каталогов операционной системы. Записи, добавленные или удаленные во время итерации по каталогу, могут не быть включены в результаты итерации.

dir[Symbol.asyncIterator]()

Добавлено в: v12.12.0

Асинхронно итерирует по директории, пока не будут прочитаны все записи. Более подробную информацию см. в документации POSIX readdir(3).

Записи, возвращаемые асинхронным итератором, всегда являются <fs.Dirent>. Случай null из dir.read() обрабатывается внутренне.

Пример см. в <fs.Dir>.

Записи директории, возвращаемые этим итератором, не имеют определенного порядка, предоставляемого базовыми механизмами директорий операционной системы. Записи, добавленные или удаленные во время итерации по директории, могут не быть включены в результаты итерации.

Класс: fs.Dirent

Добавлено в: v10.10.0

Представление записи директории, которая может быть файлом или поддиректорией внутри директории, как возвращается при чтении из <fs.Dir>. Запись директории представляет собой комбинацию пар имени файла и типа файла.

Кроме того, когда fs.readdir() или fs.readdirSync() вызываются с параметром withFileTypes, установленным в true, результирующий массив заполняется объектами <fs.Dirent>, а не строками или <Buffer>.

dirent.isBlockDevice()

Добавлено в: v10.10.0

Возвращает true, если объект <fs.Dirent> описывает блочное устройство.

dirent.isCharacterDevice()

Добавлено в: v10.10.0

Возвращает true, если объект <fs.Dirent> описывает символьное устройство.

dirent.isDirectory()

Добавлено в: v10.10.0

Возвращает true, если объект <fs.Dirent> описывает директорию файловой системы.

dirent.isFIFO()

Добавлено в: v10.10.0

Возвращает true, если объект <fs.Dirent> описывает канал FIFO (first-in-first-out).

dirent.isFile()

Добавлено в: v10.10.0

Возвращает true, если объект <fs.Dirent> описывает обычный файл.

dirent.isSocket()

Добавлено в: v10.10.0

Возвращает true, если объект <fs.Dirent> описывает сокет.

Добавлено в: v10.10.0

Возвращает true, если объект <fs.Dirent> описывает символическую ссылку.

dirent.name

Добавлено в: v10.10.0

Имя файла, на который ссылается этот объект <fs.Dirent>. Тип этого значения определяется параметром options.encoding, переданным в fs.readdir() или fs.readdirSync().

dirent.parentPath

Добавлено в: v21.4.0, v20.12.0, v18.20.0

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1 - Экспериментальный

Путь к родительской директории файла, на который ссылается этот объект <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 вместо этого.

Псевдоним для dirent.parentPath.

Класс: fs.FSWatcher

Добавлено в: v0.5.8

Успешный вызов метода fs.watch() вернет новый объект <fs.FSWatcher>.

Все объекты <fs.FSWatcher> генерируют событие 'change' всякий раз, когда изменяется наблюдаемый файл.

Событие: 'change'

Добавлено в: v0.5.8

  • eventType <строка> Тип события изменения, которое произошло
  • filename <строка> | <Buffer> Измененное имя файла (если применимо/доступно)

Генерируется, когда что-то изменяется в наблюдаемой директории или файле. Подробнее см. в fs.watch().

Аргумент filename может не предоставляться в зависимости от поддержки операционной системы. Если filename предоставляется, он будет предоставлен в виде <Buffer>, если fs.watch() вызывается с параметром encoding, установленным в 'buffer', в противном случае filename будет строкой UTF-8.

js
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

Генерируется при возникновении ошибки во время наблюдения за файлом. Объект <fs.FSWatcher> с ошибкой более не доступен в обработчике событий.

watcher.close()

Добавлено в: v0.5.8

Остановить наблюдение за изменениями в заданном <fs.FSWatcher>. После остановки объект <fs.FSWatcher> более не доступен.

watcher.ref()

Добавлено в: v14.3.0, v12.20.0

При вызове запрашивает, чтобы цикл событий Node.js не завершался, пока активен <fs.FSWatcher>. Многократный вызов watcher.ref() не будет иметь эффекта.

По умолчанию все объекты <fs.FSWatcher> имеют ссылку ("ref'ed"), поэтому обычно нет необходимости вызывать watcher.ref(), если ранее не был вызван watcher.unref().

watcher.unref()

Добавлено в: v14.3.0, v12.20.0

При вызове активный объект <fs.FSWatcher> не будет требовать, чтобы цикл событий Node.js оставался активным. Если нет другой активности, поддерживающей работу цикла событий, процесс может завершиться до вызова обратного вызова объекта <fs.FSWatcher>. Многократный вызов watcher.unref() не будет иметь эффекта.

Класс: fs.StatWatcher

Добавлено в: v14.3.0, v12.20.0

Успешный вызов метода fs.watchFile() вернет новый объект <fs.StatWatcher>.

watcher.ref()

Добавлено в: v14.3.0, v12.20.0

При вызове запрашивает, чтобы цикл событий Node.js не завершался, пока активен <fs.StatWatcher>. Многократный вызов watcher.ref() не будет иметь эффекта.

По умолчанию все объекты <fs.StatWatcher> имеют ссылку ("ref'ed"), поэтому обычно нет необходимости вызывать watcher.ref(), если ранее не был вызван watcher.unref().

watcher.unref()

Добавлен в: v14.3.0, v12.20.0

После вызова активный объект <fs.StatWatcher> не будет требовать, чтобы цикл событий Node.js оставался активным. Если нет другой активности, поддерживающей работу цикла событий, процесс может завершиться до вызова обратного вызова объекта <fs.StatWatcher>. Многократный вызов watcher.unref() не окажет никакого эффекта.

Класс: fs.ReadStream

Добавлен в: v0.1.93

Экземпляры <fs.ReadStream> создаются и возвращаются с помощью функции fs.createReadStream().

Событие: 'close'

Добавлен в: v0.1.93

Генерируется, когда базовый файловый дескриптор <fs.ReadStream> закрыт.

Событие: 'open'

Добавлен в: v0.1.93

Генерируется, когда файловый дескриптор <fs.ReadStream> открыт.

Событие: 'ready'

Добавлен в: v9.11.0

Генерируется, когда <fs.ReadStream> готов к использованию.

Вызывается сразу после 'open'.

readStream.bytesRead

Добавлен в: v6.4.0

Количество байтов, прочитанных на данный момент.

readStream.path

Добавлен в: v0.1.93

Путь к файлу, из которого поток читает данные, как указано в первом аргументе fs.createReadStream(). Если path передается как строка, то readStream.path будет строкой. Если path передается как <Buffer>, то readStream.path будет <Buffer>. Если указан fd, то readStream.path будет undefined.

readStream.pending

Добавлено в: v11.2.0, v10.16.0

Это свойство имеет значение true, если базовый файл ещё не открыт, т.е. до того, как событие 'ready' будет испущено.

Класс: 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() и их синхронными аналогами, имеют этот тип. Если bigint в параметрах options, переданных этим методам, имеет значение true, числовые значения будут bigint вместо number, и объект будет содержать дополнительные свойства с наносекундной точностью, оканчивающиеся на Ns. Объекты Stat не должны создаваться напрямую с помощью ключевого слова new.

bash
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:

bash
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

Возвращает true, если объект <fs.Stats> описывает блочное устройство.

stats.isCharacterDevice()

Добавлен в: v0.1.10

Возвращает true, если объект <fs.Stats> описывает символьное устройство.

stats.isDirectory()

Добавлен в: v0.1.10

Возвращает true, если объект <fs.Stats> описывает каталог файловой системы.

Если объект <fs.Stats> был получен вызовом fs.lstat() для символической ссылки, которая разрешается в каталог, этот метод вернет false. Это связано с тем, что fs.lstat() возвращает информацию о самой символической ссылке, а не о пути, к которому она ведет.

stats.isFIFO()

Добавлен в: v0.1.10

Возвращает true, если объект <fs.Stats> описывает именованный канал FIFO (first-in-first-out).

stats.isFile()

Добавлен в: v0.1.10

Возвращает true, если объект <fs.Stats> описывает обычный файл.

stats.isSocket()

Добавлен в: v0.1.10

Возвращает true, если объект <fs.Stats> описывает сокет.

Добавлен в: v0.1.10

Возвращает true, если объект <fs.Stats> описывает символическую ссылку.

Этот метод действителен только при использовании fs.lstat().

stats.dev

Цифровой идентификатор устройства, содержащего файл.

stats.ino

Уникальный номер файла в файловой системе (Inode).

stats.mode

Битовое поле, описывающее тип и режим файла.

Количество жёстких ссылок на файл.

stats.uid

Цифровой идентификатор пользователя, которому принадлежит файл (POSIX).

stats.gid

Цифровой идентификатор группы, которой принадлежит файл (POSIX).

stats.rdev

Цифровой идентификатор устройства, если файл представляет устройство.

stats.size

Размер файла в байтах.

Если базовая файловая система не поддерживает получение размера файла, это значение будет равно 0.

stats.blksize

Размер блока файловой системы для операций ввода-вывода.

stats.blocks

Количество блоков, выделенных для этого файла.

stats.atimeMs

Добавлен в: v8.1.0

Метка времени, указывающая на последнее время доступа к этому файлу, выраженная в миллисекундах с момента начала эпохи POSIX.

stats.mtimeMs

Добавлен в: v8.1.0

Метка времени, указывающая на последнее время изменения этого файла, выраженная в миллисекундах с момента начала эпохи POSIX.

stats.ctimeMs

Добавлен в: v8.1.0

Метка времени, указывающая на последнее время изменения статуса файла, выраженная в миллисекундах с момента начала эпохи POSIX.

stats.birthtimeMs

Добавлен в: v8.1.0

Метка времени, указывающая на время создания этого файла, выраженная в миллисекундах с момента начала эпохи POSIX.

stats.atimeNs

Добавлен в: v12.10.0

Присутствует только тогда, когда bigint: true передается в метод, который генерирует объект. Метка времени, указывающая на последнее время доступа к этому файлу, выраженная в наносекундах с момента начала эпохи POSIX.

stats.mtimeNs

Добавлено в: v12.10.0

Присутствует только в том случае, если в метод, генерирующий объект, передано значение bigint: true. Метка времени, указывающая на последнее время изменения этого файла, выраженная в наносекундах с начала эпохи POSIX.

stats.ctimeNs

Добавлено в: v12.10.0

Присутствует только в том случае, если в метод, генерирующий объект, передано значение bigint: true. Метка времени, указывающая на последнее время изменения статуса файла, выраженная в наносекундах с начала эпохи POSIX.

stats.birthtimeNs

Добавлено в: v12.10.0

Присутствует только в том случае, если в метод, генерирующий объект, передано значение bigint: true. Метка времени, указывающая на время создания этого файла, выраженная в наносекундах с начала эпохи POSIX.

stats.atime

Добавлено в: v0.11.13

Метка времени, указывающая на последнее время доступа к этому файлу.

stats.mtime

Добавлено в: v0.11.13

Метка времени, указывающая на последнее время изменения этого файла.

stats.ctime

Добавлено в: v0.11.13

Метка времени, указывающая на последнее время изменения статуса файла.

stats.birthtime

Добавлено в: v0.11.13

Метка времени, указывающая на время создания этого файла.

Значения времени Stat

Свойства atimeMs, mtimeMs, ctimeMs, birthtimeMs представляют собой числовые значения, содержащие соответствующие времена в миллисекундах. Их точность зависит от платформы. Когда в метод, генерирующий объект, передано значение bigint: true, свойства будут bigints, в противном случае они будут numbers.

Свойства atimeNs, mtimeNs, ctimeNs, birthtimeNs представляют собой bigints, содержащие соответствующие времена в наносекундах. Они присутствуют только в том случае, если в метод, генерирующий объект, передано значение 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 "Время изменения статуса": время последнего изменения статуса файла (изменение данных индексного дескриптора). Изменяется системными вызовами chmod(2), chown(2), link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2) и write(2).
  • birthtime "Время создания": время создания файла. Устанавливается один раз при создании файла. В файловых системах, где время создания недоступно, это поле может вместо этого содержать либо ctime, либо 1970-01-01T00:00Z (т.е. метку времени эпохи Unix 0). В этом случае это значение может быть больше, чем atime или mtime. В Darwin и других вариантах FreeBSD также устанавливается, если atime явно установлено на более раннее значение, чем текущее birthtime, с помощью системного вызова utimes(2).

До Node.js 0.12, ctime содержало birthtime в системах Windows. Начиная с версии 0.12, ctime не является "временем создания", и в Unix-системах им никогда не было.

Класс: fs.StatFs

Добавлено в: v19.6.0, v18.15.0

Предоставляет информацию о смонтированной файловой системе.

Объекты, возвращаемые функцией fs.statfs() и её синхронным аналогом, имеют этот тип. Если параметр bigint в options, переданный этим методам, равен true, числовые значения будут типа bigint, а не number.

bash
StatFs {
  type: 1397114950,
  bsize: 4096,
  blocks: 121938943,
  bfree: 61058895,
  bavail: 61058895,
  files: 999,
  ffree: 1000000
}

Версия с bigint:

bash
StatFs {
  type: 1397114950n,
  bsize: 4096n,
  blocks: 121938943n,
  bfree: 61058895n,
  bavail: 61058895n,
  files: 999n,
  ffree: 1000000n
}

statfs.bavail

Добавлено в: v19.6.0, v18.15.0

Количество свободных блоков, доступных непривилегированным пользователям.

statfs.bfree

Добавлено в: v19.6.0, v18.15.0

Количество свободных блоков в файловой системе.

statfs.blocks

Добавлено в: v19.6.0, v18.15.0

Общее количество блоков данных в файловой системе.

statfs.bsize

Добавлено в: v19.6.0, v18.15.0

Оптимальный размер блока для передачи данных.

statfs.ffree

Добавлено в: v19.6.0, v18.15.0

Количество свободных узлов файлов в файловой системе.

statfs.files

Добавлено в: v19.6.0, v18.15.0

Общее количество файловых узлов в файловой системе.

statfs.type

Добавлено в: v19.6.0, v18.15.0

Тип файловой системы.

Класс: fs.WriteStream

Добавлено в: v0.1.93

Экземпляры <fs.WriteStream> создаются и возвращаются с помощью функции fs.createWriteStream().

Событие: 'close'

Добавлено в: v0.1.93

Генерируется, когда базовый файловый дескриптор <fs.WriteStream> закрыт.

Событие: 'open'

Добавлено в: v0.1.93

Генерируется, когда файл <fs.WriteStream> открыт.

Событие: 'ready'

Добавлено в: v9.11.0

Генерируется, когда <fs.WriteStream> готов к использованию.

Выполняется сразу после 'open'.

writeStream.bytesWritten

Добавлено в: v0.4.7

Количество записанных байтов. Не включает данные, которые всё ещё находятся в очереди на запись.

writeStream.close([callback])

Добавлено в: v0.9.4

Закрывает writeStream. Необязательно принимает обратный вызов, который будет выполнен после закрытия writeStream.

writeStream.path

Добавлено в: v0.1.93

Путь к файлу, в который записывает поток, как указано в первом аргументе fs.createWriteStream(). Если path передаётся как строка, то writeStream.path будет строкой. Если path передаётся как <Buffer>, то writeStream.path будет <Buffer>.

writeStream.pending

Добавлено в: v11.2.0

Это свойство имеет значение true, если базовый файл ещё не открыт, т.е. до того, как будет отправлено событие 'ready'.

fs.constants

Возвращает объект, содержащий часто используемые константы для операций файловой системы.

Константы FS

Следующие константы экспортируются fs.constants и fsPromises.constants.

Не все константы будут доступны в каждой операционной системе; это особенно важно для Windows, где многие определения, специфичные для POSIX, недоступны. Для переносимых приложений рекомендуется проверять их наличие перед использованием.

Чтобы использовать более одной константы, используйте побитовую операцию ИЛИ |.

Пример:

js
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) => {
  // ...
})
Константы доступа к файлам

Следующие константы предназначены для использования в качестве параметра mode, передаваемого в fsPromises.access(), fs.access() и fs.accessSync().

КонстантаОписание
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Флаг, указывающий, что если файл существует и является обычным файлом, и файл успешно открыт для записи, его длина будет усечена до нуля.
O_APPENDФлаг, указывающий, что данные будут добавляться в конец файла.
O_DIRECTORYФлаг, указывающий, что открытие должно завершиться неудачей, если путь не является каталогом.
O_NOATIMEФлаг, указывающий, что доступ к файловой системе для чтения больше не будет приводить к обновлению информации atime, связанной с файлом. Этот флаг доступен только в операционных системах Linux.
O_NOFOLLOWФлаг, указывающий, что открытие должно завершиться неудачей, если путь является символической ссылкой.
O_SYNCФлаг, указывающий, что файл открыт для синхронного ввода-вывода, а операции записи ожидают целостности файла.
O_DSYNCФлаг, указывающий, что файл открыт для синхронного ввода-вывода, а операции записи ожидают целостности данных.
O_SYMLINKФлаг, указывающий на открытие самой символической ссылки, а не ресурса, на который она указывает.
O_DIRECTПри установке будет предпринята попытка минимизировать эффекты кэширования файлового ввода-вывода.
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.

Константы типа файла

Следующие константы предназначены для использования со свойством mode объекта <fs.Stats> для определения типа файла.

КонстантаОписание
S_IFMTБитовая маска, используемая для извлечения кода типа файла.
S_IFREGКонстанта типа файла для обычного файла.
S_IFDIRКонстанта типа файла для директории.
S_IFCHRКонстанта типа файла для символьного устройства.
S_IFBLKКонстанта типа файла для блочного устройства.
S_IFIFOКонстанта типа файла для FIFO/pipe.
S_IFLNKКонстанта типа файла для символической ссылки.
S_IFSOCKКонстанта типа файла для сокета.

В Windows доступны только S_IFCHR, S_IFDIR, S_IFLNK, S_IFMT и S_IFREG.

Константы режима файла

Следующие константы предназначены для использования со свойством mode объекта <fs.Stats> для определения прав доступа к файлу.

КонстантаОписание
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.

Примечания

Порядок выполнения операций на основе обратных вызовов и промисов

Поскольку они выполняются асинхронно пулом потоков, нет гарантированного порядка при использовании методов на основе обратных вызовов или промисов.

Например, следующий код склонен к ошибкам, потому что операция fs.stat() может завершиться раньше операции fs.rename():

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

Важно правильно упорядочить операции, ожидая результатов одной перед вызовом другой:

js
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)
}
js
const { rename, stat } = require('node:fs/promises')

;(async function (oldPath, newPath) {
  try {
    await rename(oldPath, newPath)
    const stats = await stat(newPath)
    console.log(`stats: ${JSON.stringify(stats)}`)
  } catch (error) {
    console.error('there was an error:', error.message)
  }
})('/tmp/hello', '/tmp/world')

Или, при использовании API на основе обратных вызовов, переместите вызов fs.stat() в обратный вызов операции fs.rename():

js
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)}`)
  })
})
js
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> или объекта <URL> с использованием протокола file:.

Строковые пути

Строковые пути интерпретируются как последовательности символов UTF-8, определяющие абсолютное или относительное имя файла. Относительные пути будут разрешены относительно текущего рабочего каталога, определяемого вызовом process.cwd().

Пример использования абсолютного пути в POSIX:

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

let fd
try {
  fd = await open('/open/some/file.txt', 'r')
  // Выполните какие-либо действия с файлом
} finally {
  await fd?.close()
}

Пример использования относительного пути в POSIX (относительно process.cwd()):

js
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 может быть передан как объект <URL> с использованием протокола file:.

js
import { readFileSync } from 'node:fs'

readFileSync(new URL('file:///tmp/hello'))

URL file: всегда представляют собой абсолютные пути.

Особенности разных платформ

В Windows URL file: <URL> с именем узла преобразуются в пути UNC, а URL file: <URL> с буквой диска преобразуются в локальные абсолютные пути. URL file: <URL> без имени узла и буквы диска приведут к ошибке:

js
import { readFileSync } from 'node:fs'
// В Windows:

// - URL-адреса файлов WHATWG с именем узла преобразуются в путь UNC
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
readFileSync(new URL('file://hostname/p/a/t/h/file'))

// - URL-адреса файлов WHATWG с буквами дисков преобразуются в абсолютный путь
// file:///C:/tmp/hello => C:\tmp\hello
readFileSync(new URL('file:///C:/tmp/hello'))

// - URL-адреса файлов WHATWG без имени узла должны иметь буквы дисков
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 файла должен быть абсолютным

В URL file: <URL> с буквами дисков необходимо использовать : в качестве разделителя сразу после буквы диска. Использование другого разделителя приведет к ошибке.

На всех остальных платформах URL file: <URL> с именем узла не поддерживаются и приведут к ошибке:

js
import { readFileSync } from 'node:fs'
// На других платформах:

// - URL-адреса файлов WHATWG с именем узла не поддерживаются
// file://hostname/p/a/t/h/file => throw!
readFileSync(new URL('file://hostname/p/a/t/h/file'))
// TypeError [ERR_INVALID_FILE_URL_PATH]: должен быть абсолютным

// - URL-адреса файлов WHATWG преобразуются в абсолютный путь
// file:///tmp/hello => /tmp/hello
readFileSync(new URL('file:///tmp/hello'))

URL file: <URL> с закодированными символами слэша приведут к ошибке на всех платформах:

js
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 URL file: <URL> с закодированным обратным слэшем приведут к ошибке:

js
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:

js
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() открывают файл и выделяют новый дескриптор файла. После выделения дескриптор файла может использоваться для чтения данных из файла, записи данных в файл или запроса информации о файле.

Операционные системы ограничивают количество дескрипторов файлов, которые могут быть открыты в любой момент времени, поэтому крайне важно закрыть дескриптор после завершения операций. В противном случае произойдет утечка памяти, которая в конечном итоге приведет к сбою приложения.

js
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> вместо числового дескриптора файла. Эти объекты лучше управляются системой, чтобы гарантировать, что ресурсы не будут потеряны. Однако по-прежнему необходимо закрывать их после завершения операций:

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

Использование пула потоков

Все коллбэки и API файловой системы на основе промисов (за исключением fs.FSWatcher()) используют пул потоков libuv. Это может иметь неожиданные и негативные последствия для производительности некоторых приложений. См. документацию по UV_THREADPOOL_SIZE для получения дополнительной информации.

Флаги файловой системы

Следующие флаги доступны везде, где опция flag принимает строку.

  • 'a': Открыть файл для добавления. Файл создается, если он не существует.
  • 'ax': Аналогично 'a', но возвращает ошибку, если путь существует.
  • 'a+': Открыть файл для чтения и добавления. Файл создается, если он не существует.
  • 'ax+': Аналогично 'a+', но возвращает ошибку, если путь существует.
  • 'as': Открыть файл для добавления в синхронном режиме. Файл создается, если он не существует.
  • 'as+': Открыть файл для чтения и добавления в синхронном режиме. Файл создается, если он не существует.
  • 'r': Открыть файл для чтения. Возникает исключение, если файл не существует.
  • 'rs': Открыть файл для чтения в синхронном режиме. Возникает исключение, если файл не существует.
  • 'r+': Открыть файл для чтения и записи. Возникает исключение, если файл не существует.
  • 'rs+': Открыть файл для чтения и записи в синхронном режиме. Инструктирует операционную систему обходить локальный кэш файловой системы. Это в первую очередь полезно для открытия файлов на монтированных NFS, так как позволяет пропускать потенциально устаревший локальный кэш. Это оказывает очень реальное влияние на производительность ввода-вывода, поэтому использование этого флага не рекомендуется, если это не требуется. Это не превращает 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 в CREATE_NEW, как это принимается CreateFileW.

Исключительный флаг 'x' (флаг O_EXCL в open(2)) приводит к тому, что операция возвращает ошибку, если путь уже существует. В POSIX, если путь является символической ссылкой, использование O_EXCL возвращает ошибку, даже если ссылка указывает на путь, который не существует. Исключительный флаг может не работать с сетевыми файловыми системами.

В Linux позиционные записи не работают, когда файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.

Изменение файла, а не его замена, может потребовать установить опцию flag в 'r+', а не в значение по умолчанию 'w'.

Поведение некоторых флагов зависит от платформы. Таким образом, открытие каталога в macOS и Linux с флагом 'a+', как в примере ниже, вернет ошибку. Напротив, в Windows и FreeBSD будет возвращен дескриптор файла или FileHandle.

js
// macOS и Linux
fs.open('<directory>', 'a+', (err, fd) => {
  // => [Error: EISDIR: незаконная операция над каталогом, open <directory>]
})

// Windows и FreeBSD
fs.open('<directory>', 'a+', (err, fd) => {
  // => null, <fd>
})

В Windows открытие существующего скрытого файла с помощью флага 'w' (через fs.open(), fs.writeFile() или fsPromises.open()) завершится ошибкой EPERM. Существующие скрытые файлы можно открыть для записи с флагом 'r+'.

Для сброса содержимого файла можно использовать вызов fs.ftruncate() или filehandle.truncate().