Файловая система
[Стабильно: 2 - Стабильно]
Стабильно: 2 Стабильность: 2 - Стабильно
Исходный код: lib/fs.js
Модуль node:fs
позволяет взаимодействовать с файловой системой способом, смоделированным на стандартных функциях POSIX.
Для использования API на основе промисов:
import * as fs from 'node:fs/promises'
const fs = require('node:fs/promises')
Для использования API на основе колбэков и синхронных API:
import * as fs from 'node:fs'
const fs = require('node:fs')
Все операции с файловой системой имеют синхронные, колбэк-ориентированные и основанные на промисах формы и доступны с использованием как синтаксиса CommonJS, так и модулей ES6 (ESM).
Пример с промисами
Операции на основе промисов возвращают промис, который выполняется, когда асинхронная операция завершена.
import { unlink } from 'node:fs/promises'
try {
await unlink('/tmp/hello')
console.log('успешно удалено /tmp/hello')
} catch (error) {
console.error('произошла ошибка:', error.message)
}
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
.
import { unlink } from 'node:fs'
unlink('/tmp/hello', err => {
if (err) throw err
console.log('успешно удалено /tmp/hello')
})
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
или могут быть оставлены для всплытия.
import { unlinkSync } from 'node:fs'
try {
unlinkSync('/tmp/hello')
console.log('успешно удалено /tmp/hello')
} catch (err) {
// обработать ошибку
}
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.0 | API доступен только через 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 |
data
<string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>Возвращает: <Promise> Разрешается с
undefined
при успехе.
Псевдоним filehandle.writeFile()
.
При работе с файловыми дескрипторами режим не может быть изменен по сравнению с тем, который был установлен с помощью fsPromises.open()
. Следовательно, это эквивалентно filehandle.writeFile()
.
filehandle.chmod(mode)
Добавлено в: v10.0.0
Изменяет разрешения на файл. См. chmod(2)
.
filehandle.chown(uid, gid)
Добавлено в: v10.0.0
uid
<integer> Идентификатор пользователя нового владельца файла.gid
<integer> Идентификатор группы новой группы файла.- Возвращает: <Promise> Выполняется с
undefined
при успехе.
Изменяет владельца файла. Обертка для chown(2)
.
filehandle.close()
Добавлено в: v10.0.0
- Возвращает: <Promise> Выполняется с
undefined
при успехе.
Закрывает дескриптор файла после ожидания завершения любых ожидающих операций с дескриптором.
import { open } from 'node:fs/promises'
let filehandle
try {
filehandle = await open('thefile.txt', 'r')
} finally {
await filehandle?.close()
}
filehandle.createReadStream([options])
Добавлено в: v16.11.0
options
<Object>encoding
<string> По умолчанию:null
autoClose
<boolean> По умолчанию:true
emitClose
<boolean> По умолчанию:true
start
<integer>end
<integer> По умолчанию:Infinity
highWaterMark
<integer> По умолчанию:64 * 1024
signal
<AbortSignal> | <undefined> По умолчанию:undefined
Возвращает: <fs.ReadStream>
options
может включать значения start
и end
для чтения диапазона байтов из файла вместо всего файла. Оба start
и end
являются инклюзивными и начинают отсчет с 0, допустимые значения находятся в диапазоне [0, Number.MAX_SAFE_INTEGER
]. Если start
опущен или имеет значение undefined
, filehandle.createReadStream()
считывает последовательно с текущей позиции файла. encoding
может быть любым из тех, которые принимаются <Buffer>.
Если FileHandle
указывает на символьное устройство, которое поддерживает только блокирующие чтения (например, клавиатуру или звуковую карту), операции чтения не завершаются до тех пор, пока не появятся данные. Это может помешать процессу завершиться и естественному закрытию потока.
По умолчанию поток будет генерировать событие 'close'
после его уничтожения. Установите для параметра emitClose
значение false
, чтобы изменить это поведение.
import { open } from 'node:fs/promises'
const fd = await open('/dev/input/event0')
// Создание потока из некоторого символьного устройства.
const stream = fd.createReadStream()
setTimeout(() => {
stream.close() // Это может не закрыть поток.
// Искусственное обозначение конца потока, как если бы базовый ресурс сам по себе
// указал конец файла, позволяет потоку закрыться.
// Это не отменяет ожидающие операции чтения, и если такая операция есть,
// процесс все равно может не выйти успешно, пока она не завершится.
stream.push(null)
stream.read(0)
}, 100)
Если autoClose
имеет значение false, дескриптор файла не будет закрыт, даже если произошла ошибка. Приложение несет ответственность за его закрытие и обеспечение отсутствия утечки дескрипторов файлов. Если для autoClose
установлено значение true (поведение по умолчанию), при 'error'
или 'end'
дескриптор файла будет закрыт автоматически.
Пример чтения последних 10 байтов файла длиной 100 байтов:
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>Возвращает: <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> Выполняется при успехе с объектом, имеющим два свойства:
bytesRead
<integer> Количество прочитанных байтовbuffer
<Buffer> | <TypedArray> | <DataView> Ссылка на переданный аргументbuffer
.
Считывает данные из файла и сохраняет их в заданный буфер.
Если файл не изменяется одновременно, конец файла достигается, когда количество прочитанных байтов равно нулю.
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> Выполняется при успехе с объектом с двумя свойствами:
bytesRead
<integer> Количество прочитанных байтовbuffer
<Buffer> | <TypedArray> | <DataView> Ссылка на переданный аргументbuffer
.
Читает данные из файла и сохраняет их в заданном буфере.
Если файл не изменяется одновременно, конец файла достигается, когда количество прочитанных байтов равно нулю.
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> Выполняется успешно с объектом с двумя свойствами:
bytesRead
<integer> Количество прочитанных байтовbuffer
<Buffer> | <TypedArray> | <DataView> Ссылка на переданный аргументbuffer
.
Считывает данные из файла и сохраняет их в заданный буфер.
Если файл не изменяется одновременно, конец файла достигается, когда количество прочитанных байтов равно нулю.
filehandle.readableWebStream([options])
[История]
Версия | Изменения |
---|---|
v20.0.0, v18.17.0 | Добавлена опция для создания потока 'bytes'. |
v17.0.0 | Добавлено в: v17.0.0 |
[Стабильно: 1 - Экспериментально]
Стабильно: 1 Стабильность: 1 - Экспериментально
options
<Object>type
<string> | <undefined> Указывает, следует ли открывать обычный поток или поток'bytes'
. По умолчанию:undefined
Возвращает: <ReadableStream>
Возвращает ReadableStream
, который можно использовать для чтения данных файла.
Ошибка будет сгенерирована, если этот метод будет вызван более одного раза или будет вызван после закрытия или процесса закрытия FileHandle
.
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()
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
encoding
<string> | <null> По умолчанию:null
signal
<AbortSignal> позволяет прервать выполняющееся readFile
Возвращает: <Promise> Исполняется при успешном чтении с содержимым файла. Если кодировка не указана (используя
options.encoding
), данные возвращаются в виде объекта <Buffer>. В противном случае данные будут строкой.
Асинхронно считывает все содержимое файла.
Если options
является строкой, то она определяет encoding
.
<FileHandle> должен поддерживать чтение.
Если один или несколько вызовов filehandle.read()
выполняются с файловым дескриптором, а затем выполняется вызов filehandle.readFile()
, данные будут читаться с текущей позиции до конца файла. Он не всегда читает с начала файла.
filehandle.readLines([options])
Добавлено в: v18.11.0
options
<Object>Возвращает: <readline.InterfaceConstructor>
Удобный метод для создания интерфейса readline
и потоковой передачи файла. Смотрите filehandle.createReadStream()
для получения информации об опциях.
import { open } from 'node:fs/promises'
const file = await open('./some/file/to/read')
for await (const line of file.readLines()) {
console.log(line)
}
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> Выполняется при успехе с объектом, содержащим два свойства:
bytesRead
<integer> количество прочитанных байтовbuffers
<Buffer[]> | <TypedArray[]> | <DataView[]> свойство, содержащее ссылку на вводbuffers
.
Чтение из файла и запись в массив <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
байтов, в файле будут сохранены только первые len
байтов.
Следующий пример сохраняет только первые четыре байта файла:
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
, данные будут записаны в текущую позицию. Подробнее см. в документации POSIXpwrite(2)
. По умолчанию:null
- Возвращает: <Promise>
Записывает buffer
в файл.
Промис выполняется с объектом, содержащим два свойства:
bytesWritten
<integer> количество записанных байтовbuffer
<Buffer> | <TypedArray> | <DataView> ссылка на записанныйbuffer
.
Опасно использовать filehandle.write()
несколько раз для одного и того же файла, не дожидаясь выполнения (или отклонения) промиса. В этом случае используйте filehandle.createWriteStream()
.
В Linux позиционная запись не работает, когда файл открыт в режиме добавления. Ядро игнорирует аргумент позиции и всегда добавляет данные в конец файла.
filehandle.write(buffer[, options])
Добавлено в: v18.3.0, v16.17.0
buffer
<Buffer> | <TypedArray> | <DataView>options
<Object>Возвращает: <Promise>
Записывает buffer
в файл.
Аналогично функции filehandle.write
выше, эта версия принимает необязательный объект options
. Если объект options
не указан, он будет использовать значения по умолчанию, указанные выше.
filehandle.write(string[, position[, encoding]])
[История]
Версия | Изменения |
---|---|
v14.0.0 | Параметр string больше не будет приводить неподдерживаемый ввод к строкам. |
v10.0.0 | Добавлено в: v10.0.0 |
string
<string>position
<integer> | <null> Смещение от начала файла, куда следует записывать данные изstring
. Еслиposition
не являетсяnumber
, данные будут записаны в текущую позицию. Дополнительные сведения см. в документации POSIXpwrite(2)
. По умолчанию:null
encoding
<string> Ожидаемая кодировка строки. По умолчанию:'utf8'
- Возвращает: <Promise>
Записывает 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
<string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>Возвращает: <Promise>
Асинхронно записывает данные в файл, заменяя файл, если он уже существует. 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> в файл.
Промис исполняется с объектом, содержащим два свойства:
bytesWritten
<integer> количество записанных байтовbuffers
<Buffer[]> | <TypedArray[]> | <DataView[]> ссылка на входныеbuffers
.
Небезопасно вызывать 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
<string> | <Buffer> | <URL>mode
<integer> По умолчанию:fs.constants.F_OK
- Возвращает: <Promise> Разрешается с
undefined
при успехе.
Проверяет разрешения пользователя для файла или каталога, указанного в path
. Аргумент mode
является необязательным целым числом, которое определяет проверки доступности, которые должны быть выполнены. mode
должен быть либо значением fs.constants.F_OK
, либо маской, состоящей из побитового ИЛИ любых из fs.constants.R_OK
, fs.constants.W_OK
и fs.constants.X_OK
(например, fs.constants.W_OK | fs.constants.R_OK
). Проверьте Константы доступа к файлам для возможных значений mode
.
Если проверка доступности выполнена успешно, обещание выполняется без значения. Если какая-либо из проверок доступности завершается неудачно, обещание отклоняется с объектом <Error>. В следующем примере проверяется, может ли текущий процесс читать и записывать файл /etc/passwd
.
import { access, constants } from 'node:fs/promises'
try {
await access('/etc/passwd', constants.R_OK | constants.W_OK)
console.log('can access')
} catch {
console.error('cannot access')
}
Не рекомендуется использовать fsPromises.access()
для проверки доступности файла перед вызовом fsPromises.open()
. Это создает состояние гонки, поскольку другие процессы могут изменить состояние файла между двумя вызовами. Вместо этого код пользователя должен открывать/читать/записывать файл напрямую и обрабатывать ошибку, возникающую, если файл недоступен.
fsPromises.appendFile(path, data[, options])
[История]
Версия | Изменения |
---|---|
v21.1.0, v20.10.0 | Теперь поддерживается опция flush . |
v10.0.0 | Добавлено в: v10.0.0 |
path
<string> | <Buffer> | <URL> | <FileHandle> имя файла или <FileHandle>Возвращает: <Promise> Разрешается с
undefined
при успехе.
Асинхронно добавляет данные в файл, создавая файл, если он еще не существует. data
может быть строкой или <Buffer>.
Если options
является строкой, то она определяет encoding
.
Опция mode
влияет только на вновь созданный файл. См. fs.open()
для получения более подробной информации.
path
может быть указан как <FileHandle>, который был открыт для добавления (с помощью fsPromises.open()
).
fsPromises.chmod(path, mode)
Добавлено в: v10.0.0
path
<string> | <Buffer> | <URL>mode
<string> | <integer>- Возвращает: <Promise> Выполняется с
undefined
при успехе.
Изменяет права доступа к файлу.
fsPromises.chown(path, uid, gid)
Добавлено в: v10.0.0
path
<string> | <Buffer> | <URL>uid
<integer>gid
<integer>- Возвращает: <Promise> Выполняется с
undefined
при успехе.
Изменяет владельца файла.
fsPromises.copyFile(src, dest[, mode])
[История]
Версия | Изменения |
---|---|
v14.0.0 | Аргумент flags изменен на mode и наложена более строгая проверка типов. |
v10.0.0 | Добавлено в: v10.0.0 |
src
<string> | <Buffer> | <URL> Имя исходного файла для копированияdest
<string> | <Buffer> | <URL> Имя целевого файла операции копированияmode
<integer> Необязательные модификаторы, определяющие поведение операции копирования. Возможно создать маску, состоящую из побитового ИЛИ двух или более значений (например,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
перезаписывается, если он уже существует.
Гарантии атомарности операции копирования не предоставляются. Если возникает ошибка после открытия целевого файла для записи, будет предпринята попытка удалить цель.
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 |
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, который выдает пути файлов, соответствующих шаблону.
import { glob } from 'node:fs/promises'
for await (const entry of glob('**/*.js')) console.log(entry)
const { glob } = require('node:fs/promises')
;(async () => {
for await (const entry of glob('**/*.js')) console.log(entry)
})()
fsPromises.lchmod(path, mode)
Устарело с версии: v10.0.0
path
<string> | <Buffer> | <URL>mode
<integer>- Возвращает: <Promise> Выполняется с
undefined
при успехе.
Изменяет права доступа к символьной ссылке.
Этот метод реализован только на macOS.
fsPromises.lchown(path, uid, gid)
[История]
Версия | Изменения |
---|---|
v10.6.0 | Этот API больше не является устаревшим. |
v10.0.0 | Добавлено в: v10.0.0 |
path
<string> | <Buffer> | <URL>uid
<integer>gid
<integer>- Возвращает: <Promise> Разрешается с
undefined
в случае успеха.
Изменяет владельца символьной ссылки.
fsPromises.lutimes(path, atime, mtime)
Добавлено в: v14.5.0, v12.19.0
path
<string> | <Buffer> | <URL>atime
<number> | <string> | <Date>mtime
<number> | <string> | <Date>- Возвращает: <Promise> Разрешается с
undefined
в случае успеха.
Изменяет время доступа и модификации файла аналогично fsPromises.utimes()
, с тем отличием, что если путь указывает на символьную ссылку, то ссылка не разыменовывается: вместо этого изменяются временные метки самой символьной ссылки.
fsPromises.link(existingPath, newPath)
Добавлено в: v10.0.0
existingPath
<string> | <Buffer> | <URL>newPath
<string> | <Buffer> | <URL>- Возвращает: <Promise>. Выполняется с
undefined
в случае успеха.
Создает новую ссылку с existingPath
на newPath
. Подробности смотрите в документации POSIX link(2)
.
fsPromises.lstat(path[, options])
[История]
Версия | Изменения |
---|---|
v10.5.0 | Принимает дополнительный объект options для указания, должны ли возвращаемые числовые значения быть bigint. |
v10.0.0 | Добавлено в: v10.0.0 |
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
Возвращает: <Promise>. В случае успеха, выполнится со значением
undefined
, еслиrecursive
имеет значениеfalse
, или с путем к первому созданному каталогу, еслиrecursive
имеет значениеtrue
.
Асинхронно создает каталог.
Необязательный аргумент options
может быть целым числом, указывающим mode
(права доступа и биты sticky), или объектом со свойством mode
и свойством recursive
, указывающим, следует ли создавать родительские каталоги. Вызов fsPromises.mkdir()
, когда path
является существующим каталогом, приводит к отклонению только тогда, когда recursive
имеет значение false.
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)
}
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 |
encoding
<string> По умолчанию:'utf8'
Возвращает: <Promise> Выполняется со строкой, содержащей путь файловой системы к вновь созданной временной директории.
Создает уникальную временную директорию. Уникальное имя директории генерируется путем добавления шести случайных символов к концу предоставленного prefix
. Из-за несоответствий платформы избегайте конечных символов X
в prefix
. Некоторые платформы, особенно BSD, могут возвращать более шести случайных символов и заменять конечные символы X
в prefix
случайными символами.
Необязательный аргумент options
может быть строкой, указывающей кодировку, или объектом со свойством encoding
, указывающим кодировку символов для использования.
import { mkdtemp } from 'node:fs/promises'
import { join } from 'node:path'
import { tmpdir } from 'node:os'
try {
await mkdtemp(join(tmpdir(), 'foo-'))
} catch (err) {
console.error(err)
}
Метод fsPromises.mkdtemp()
добавит шесть случайно выбранных символов непосредственно к строке prefix
. Например, если дан каталог /tmp
, и намерение состоит в том, чтобы создать временный каталог внутри /tmp
, то prefix
должен заканчиваться конечным разделителем пути, специфичным для платформы (require('node:path').sep
).
fsPromises.open(path, flags[, mode])
[История]
Версия | Изменения |
---|---|
v11.1.0 | Аргумент flags теперь является необязательным и по умолчанию имеет значение 'r' . |
v10.0.0 | Добавлено в: v10.0.0 |
path
<string> | <Buffer> | <URL>flags
<string> | <number> См. поддержкуflags
файловой системы. По умолчанию:'r'
.mode
<string> | <integer> Устанавливает режим файла (разрешения и биты липкости), если файл создан. По умолчанию:0o666
(чтение и запись)- Возвращает: <Promise> Выполняется с объектом <FileHandle>.
Открывает <FileHandle>.
Обратитесь к документации POSIX open(2)
для получения более подробной информации.
Некоторые символы (\< \> : " / \ | ? *
) зарезервированы в Windows, как описано в разделе Именование файлов, путей и пространств имен. В NTFS, если имя файла содержит двоеточие, Node.js откроет файловый поток, как описано на этой странице MSDN.
fsPromises.opendir(path[, options])
[История]
Версия | Изменения |
---|---|
v20.1.0, v18.17.0 | Добавлена опция recursive . |
v13.1.0, v12.16.0 | Представлена опция bufferSize . |
v12.12.0 | Добавлено в: v12.12.0 |
options
<Object>encoding
<string> | <null> По умолчанию:'utf8'
bufferSize
<number> Количество записей каталога, которые буферизуются внутри при чтении из каталога. Более высокие значения приводят к лучшей производительности, но к более высокому использованию памяти. По умолчанию:32
recursive
<boolean> РезультирующийDir
будет являться <AsyncIterable>, содержащим все подфайлы и каталоги. По умолчанию:false
Асинхронно открывает каталог для итеративного сканирования. См. документацию POSIX opendir(3)
для получения более подробной информации.
Создает <fs.Dir>, который содержит все дальнейшие функции для чтения и очистки каталога.
Опция encoding
устанавливает кодировку для path
при открытии каталога и последующих операциях чтения.
Пример использования асинхронной итерации:
import { opendir } from 'node:fs/promises'
try {
const dir = await opendir('./')
for await (const dirent of dir) console.log(dirent.name)
} catch (err) {
console.error(err)
}
При использовании асинхронного итератора объект <fs.Dir> будет автоматически закрыт после выхода итератора.
fsPromises.readdir(path[, options])
[История]
Версия | Изменения |
---|---|
v20.1.0, v18.17.0 | Добавлен параметр recursive . |
v10.11.0 | Добавлен новый параметр withFileTypes . |
v10.0.0 | Добавлено в: v10.0.0 |
Возвращает: <Promise> Завершается массивом имен файлов в каталоге, исключая
'.'
и'..'
.
Считывает содержимое каталога.
Необязательный аргумент options
может быть строкой, определяющей кодировку, или объектом со свойством encoding
, определяющим кодировку символов, используемую для имен файлов. Если encoding
установлено значение 'buffer'
, возвращаемые имена файлов будут переданы как объекты <Buffer>.
Если options.withFileTypes
установлено в значение true
, возвращаемый массив будет содержать объекты <fs.Dirent>.
import { readdir } from 'node:fs/promises'
try {
const files = await readdir(path)
for (const file of files) console.log(file)
} catch (err) {
console.error(err)
}
fsPromises.readFile(path[, options])
[История]
Версия | Изменения |
---|---|
v15.2.0, v14.17.0 | Аргумент options может включать AbortSignal для отмены текущего запроса readFile. |
v10.0.0 | Добавлено в: v10.0.0 |
path
<string> | <Buffer> | <URL> | <FileHandle> имя файла илиFileHandle
encoding
<string> | <null> По умолчанию:null
flag
<string> См. поддержка флагов файловой системы. По умолчанию:'r'
.signal
<AbortSignal> позволяет отменить выполняющийся readFile
Возвращает: <Promise> Разрешается содержимым файла.
Асинхронно считывает всё содержимое файла.
Если кодировка не указана (с использованием options.encoding
), данные возвращаются в виде объекта <Buffer>. В противном случае данные будут строкой.
Если options
является строкой, то она определяет кодировку.
Когда path
является каталогом, поведение fsPromises.readFile()
зависит от платформы. В macOS, Linux и Windows промис будет отклонён с ошибкой. В FreeBSD будет возвращено представление содержимого каталога.
Пример чтения файла package.json
, расположенного в том же каталоге, что и исполняемый код:
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)
}
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
:
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
encoding
<string> По умолчанию:'utf8'
Возвращает: <Promise> Разрешается с разрешенным путем в случае успеха.
Определяет фактическое местоположение 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
<string> | <Buffer> | <URL>newPath
<string> | <Buffer> | <URL>- Возвращает: <Promise> Разрешается с
undefined
при успехе.
Переименовывает 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 |
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
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 |
options
<Object>bigint
<boolean> Определяет, должны ли числовые значения в возвращаемом объекте <fs.Stats> бытьbigint
. По умолчанию:false
.
Возвращает: <Promise> Выполняется с объектом <fs.Stats> для заданного
path
.
fsPromises.statfs(path[, options])
Добавлено в: v19.6.0, v18.15.0
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 |
target
<string> | <Buffer> | <URL>path
<string> | <Buffer> | <URL>type
<string> | <null> По умолчанию:null
- Возвращает: <Promise>, который выполняется с
undefined
в случае успеха.
Создает символическую ссылку.
Аргумент type
используется только на платформах Windows и может принимать значения 'dir'
, 'file'
или 'junction'
. Если аргумент type
равен null
, Node.js автоматически определит тип target
и использует 'file'
или 'dir'
. Если target
не существует, будет использовано 'file'
. Точки соединения Windows требуют, чтобы путь назначения был абсолютным. При использовании 'junction'
, аргумент target
автоматически нормализуется до абсолютного пути. Точки соединения на томах NTFS могут указывать только на каталоги.
fsPromises.truncate(path[, len])
Добавлено в: v10.0.0
path
<string> | <Buffer> | <URL>len
<integer> По умолчанию:0
- Возвращает: <Promise>. Выполняется с
undefined
при успехе.
Усекает (сокращает или удлиняет) длину содержимого по адресу path
до len
байтов.
fsPromises.unlink(path)
Добавлено в: v10.0.0
Если path
указывает на символическую ссылку, то ссылка удаляется, не затрагивая файл или каталог, на который эта ссылка указывает. Если path
указывает на путь к файлу, который не является символической ссылкой, то файл удаляется. См. документацию POSIX unlink(2)
для получения более подробной информации.
fsPromises.utimes(path, atime, mtime)
Добавлено в: v10.0.0
path
<string> | <Buffer> | <URL>atime
<number> | <string> | <Date>mtime
<number> | <string> | <Date>- Возвращает: <Promise>. Выполняется с
undefined
при успехе.
Изменяет временные метки файловой системы объекта, на который ссылается path
.
Аргументы atime
и mtime
соответствуют следующим правилам:
- Значения могут быть либо числами, представляющими время Unix epoch,
Date
или числовой строкой, такой как'123456789.0'
. - Если значение не может быть преобразовано в число, или является
NaN
,Infinity
или-Infinity
, будет выдана ошибкаError
.
fsPromises.watch(filename[, options])
Добавлено в: v15.9.0, v14.18.0
persistent
<boolean> Указывает, должен ли процесс продолжать работу до тех пор, пока ведется наблюдение за файлами. По умолчанию:true
.recursive
<boolean> Указывает, следует ли отслеживать все подкаталоги или только текущий каталог. Это применяется, когда указан каталог, и только на поддерживаемых платформах (см. предостережения). По умолчанию:false
.encoding
<string> Указывает кодировку символов, которая будет использоваться для имени файла, передаваемого слушателю. По умолчанию:'utf8'
.signal
<AbortSignal> <AbortSignal>, используемый для сигнализации о том, когда наблюдатель должен остановиться.
Возвращает: <AsyncIterator> объектов со свойствами:
Возвращает асинхронный итератор, который отслеживает изменения в filename
, где filename
- это либо файл, либо каталог.
const { watch } = require('node:fs/promises')
const ac = new AbortController()
const { signal } = ac
setTimeout(() => ac.abort(), 10000)
;(async () => {
try {
const watcher = watch(__filename, { signal })
for await (const event of watcher) console.log(event)
} catch (err) {
if (err.name === 'AbortError') return
throw err
}
})()
На большинстве платформ событие 'rename'
возникает всякий раз, когда имя файла появляется или исчезает в каталоге.
Все предостережения для fs.watch()
также применяются к fsPromises.watch()
.
fsPromises.writeFile(file, data[, options])
[История]
Версия | Изменения |
---|---|
v21.0.0, v20.10.0 | Теперь поддерживается параметр flush . |
v15.14.0, v14.18.0 | Аргумент data поддерживает AsyncIterable , Iterable и Stream . |
v15.2.0, v14.17.0 | Аргумент options может включать AbortSignal для прерывания текущего запроса writeFile. |
v14.0.0 | Параметр data больше не приводит неподдерживаемый ввод к строкам. |
v10.0.0 | Добавлено в: v10.0.0 |
file
<string> | <Buffer> | <URL> | <FileHandle> имя файла илиFileHandle
data
<string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>encoding
<string> | <null> По умолчанию:'utf8'
mode
<integer> По умолчанию:0o666
flag
<string> См. поддержку флагов файловой системы. По умолчанию:'w'
.flush
<boolean> Если все данные успешно записаны в файл, иflush
имеет значениеtrue
, для сброса данных используетсяfilehandle.sync()
. По умолчанию:false
.signal
<AbortSignal> позволяет прервать выполняющийся writeFile
Возвращает: <Promise> Выполняется с
undefined
при успехе.
Асинхронно записывает данные в файл, заменяя файл, если он уже существует. data
может быть строкой, буфером, объектом <AsyncIterable> или <Iterable>.
Параметр encoding
игнорируется, если data
является буфером.
Если options
является строкой, то она указывает кодировку.
Параметр mode
влияет только на вновь созданный файл. Подробнее см. fs.open()
.
Любой указанный <FileHandle> должен поддерживать запись.
Небезопасно использовать fsPromises.writeFile()
несколько раз для одного и того же файла, не дожидаясь завершения промиса.
Аналогично fsPromises.readFile
- fsPromises.writeFile
- это удобный метод, который выполняет несколько внутренних вызовов write
для записи переданного ему буфера. Для производительного кода рассмотрите возможность использования fs.createWriteStream()
или filehandle.createWriteStream()
.
Можно использовать <AbortSignal> для отмены fsPromises.writeFile()
. Отмена является "лучшей попыткой", и, вероятно, некоторое количество данных все еще будет записано.
import { writeFile } from 'node:fs/promises'
import { Buffer } from 'node:buffer'
try {
const controller = new AbortController()
const { signal } = controller
const data = new Uint8Array(Buffer.from('Hello Node.js'))
const promise = writeFile('message.txt', data, { signal })
// Прерываем запрос до того, как промис разрешится.
controller.abort()
await promise
} catch (err) {
// Когда запрос прерван - err является AbortError
console.error(err)
}
Прерывание текущего запроса не прерывает отдельные запросы операционной системы, а скорее внутреннюю буферизацию, которую выполняет fs.writeFile
.
fsPromises.constants
Добавлено в: v18.4.0, v16.17.0
Возвращает объект, содержащий часто используемые константы для операций файловой системы. Объект идентичен 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
<строка> | <Buffer> | <URL>mode
<целое число> По умолчанию:fs.constants.F_OK
callback
<Функция>err
<Ошибка>
Проверяет права пользователя на доступ к файлу или каталогу, указанному в 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
, и является ли он читаемым или записываемым.
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()
. Это создает условие гонки, поскольку другие процессы могут изменить состояние файла между двумя вызовами. Вместо этого код пользователя должен открывать/читать/записывать файл напрямую и обрабатывать ошибку, если файл недоступен.
Запись (НЕ РЕКОМЕНДУЕТСЯ)
import { access, open, close } from 'node:fs'
access('myfile', err => {
if (!err) {
console.error('myfile уже существует')
return
}
open('myfile', 'wx', (err, fd) => {
if (err) throw err
try {
writeMyData(fd)
} finally {
close(fd, err => {
if (err) throw err
})
}
})
})
Запись (РЕКОМЕНДУЕТСЯ)
import { open, close } from 'node:fs'
open('myfile', 'wx', (err, fd) => {
if (err) {
if (err.code === 'EEXIST') {
console.error('myfile уже существует')
return
}
throw err
}
try {
writeMyData(fd)
} finally {
close(fd, err => {
if (err) throw err
})
}
})
Чтение (НЕ РЕКОМЕНДУЕТСЯ)
import { access, open, close } from 'node:fs'
access('myfile', err => {
if (err) {
if (err.code === 'ENOENT') {
console.error('myfile не существует')
return
}
throw err
}
open('myfile', 'r', (err, fd) => {
if (err) throw err
try {
readMyData(fd)
} finally {
close(fd, err => {
if (err) throw err
})
}
})
})
Чтение (РЕКОМЕНДУЕТСЯ)
import { open, close } from 'node:fs'
open('myfile', 'r', (err, fd) => {
if (err) {
if (err.code === 'ENOENT') {
console.error('myfile не существует')
return
}
throw err
}
try {
readMyData(fd)
} finally {
close(fd, err => {
if (err) throw err
})
}
})
Приведенные выше примеры "не рекомендуется" проверяют доступность, а затем используют файл; примеры "рекомендуется" лучше, потому что они используют файл напрямую и обрабатывают ошибку, если таковая имеется.
В общем, проверяйте доступность файла только в том случае, если файл не будет использоваться напрямую, например, когда его доступность является сигналом от другого процесса.
В Windows политики контроля доступа (ACL) к каталогу могут ограничивать доступ к файлу или каталогу. Однако функция fs.access()
не проверяет ACL и поэтому может сообщать, что путь доступен, даже если ACL ограничивает пользователя от чтения или записи в него.
fs.appendFile(path, data[, options], callback)
[История]
Версия | Изменения |
---|---|
v21.1.0, v20.10.0 | Теперь поддерживается параметр flush . |
v18.0.0 | Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_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 |
path
<строка> | <Buffer> | <URL> | <число> имя файла или файловый дескрипторencoding
<строка> | <null> По умолчанию:'utf8'
mode
<целое число> По умолчанию:0o666
flag
<строка> См. поддержку флагов файловой системы. По умолчанию:'a'
.flush
<логическое значение> Еслиtrue
, базовый файловый дескриптор очищается перед закрытием. По умолчанию:false
.
callback
<Функция>err
<Ошибка>
Асинхронно добавляет данные в файл, создавая файл, если он ещё не существует. data
может быть строкой или <Buffer>.
Параметр mode
влияет только на вновь созданный файл. См. fs.open()
для получения более подробной информации.
import { appendFile } from 'node:fs'
appendFile('message.txt', 'data to append', err => {
if (err) throw err
console.log('Данные "data to append" были добавлены в файл!')
})
Если options
является строкой, то она указывает кодировку:
import { appendFile } from 'node:fs'
appendFile('message.txt', 'data to append', 'utf8', callback)
path
может быть указан как числовой файловый дескриптор, открытый для добавления (с помощью fs.open()
или fs.openSync()
). Файловый дескриптор не будет закрыт автоматически.
import { open, close, appendFile } from 'node:fs'
function closeFd(fd) {
close(fd, err => {
if (err) throw err
})
}
open('message.txt', 'a', (err, fd) => {
if (err) throw err
try {
appendFile(fd, 'data to append', 'utf8', err => {
closeFd(fd)
if (err) throw err
})
} catch (err) {
closeFd(fd)
throw err
}
})
fs.chmod(path, mode, callback)
[История]
Версия | Изменения |
---|---|
v18.0.0 | Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_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)
.
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_IRUSR | 0o400 | чтение владельцем |
fs.constants.S_IWUSR | 0o200 | запись владельцем |
fs.constants.S_IXUSR | 0o100 | выполнение/поиск владельцем |
fs.constants.S_IRGRP | 0o40 | чтение группой |
fs.constants.S_IWGRP | 0o20 | запись группой |
fs.constants.S_IXGRP | 0o10 | выполнение/поиск группой |
fs.constants.S_IROTH | 0o4 | чтение другими |
fs.constants.S_IWOTH | 0o2 | запись другими |
fs.constants.S_IXOTH | 0o1 | выполнение/поиск другими |
Более простой способ построения mode
— использование последовательности из трех восьмеричных цифр (например, 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 |
path
<строка> | <Buffer> | <URL>uid
<целое число>gid
<целое число>callback
<Функция>err
<Ошибка>
Асинхронно изменяет владельца и группу файла. В функцию обратного вызова передаются только возможные исключения.
Более подробную информацию см. в документации 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 |
fd
<целое число>callback
<Функция>err
<Ошибка>
Закрывает файловый дескриптор. В функцию обратного вызова передаются только возможные исключения.
Вызов 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
<строка> | <Buffer> | <URL> имя исходного файла для копированияdest
<строка> | <Buffer> | <URL> имя файла назначения для операции копированияmode
<целое число> модификаторы для операции копирования. По умолчанию:0
.callback
<Функция>err
<Ошибка>
Асинхронно копирует 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 с копированием при записи. Если платформа не поддерживает копирование при записи, операция завершится ошибкой.
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 |
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
<Функция>err
<Ошибка>
Асинхронно копирует всю структуру каталога из 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 |
flags
<string> См. поддержку флагов файловой системы. По умолчанию:'r'
.encoding
<string> По умолчанию:null
fd
<integer> | <FileHandle> По умолчанию:null
mode
<integer> По умолчанию:0o666
autoClose
<boolean> По умолчанию:true
emitClose
<boolean> По умолчанию:true
start
<integer>end
<integer> По умолчанию:Infinity
highWaterMark
<integer> По умолчанию:64 * 1024
fs
<Object> | <null> По умолчанию:null
signal
<AbortSignal> | <null> По умолчанию:null
Возвращает: <fs.ReadStream>
options
может включать значения start
и end
для чтения диапазона байтов из файла вместо всего файла. start
и end
включительные и начинаются с 0, допустимые значения находятся в диапазоне [0, Number.MAX_SAFE_INTEGER
]. Если указан fd
и start
опущен или имеет значение undefined
, fs.createReadStream()
читает последовательно из текущей позиции файла. encoding
может быть любым из тех, которые принимаются <Buffer>.
Если указан fd
, ReadStream
проигнорирует аргумент path
и будет использовать указанный дескриптор файла. Это означает, что событие 'open'
не будет генерироваться. fd
должен быть блокирующим; неблокирующие fd
должны передаваться в <net.Socket>.
Если fd
указывает на символьное устройство, которое поддерживает только блокирующие операции чтения (например, клавиатура или звуковая карта), операции чтения не завершаются до тех пор, пока данные не станут доступны. Это может помешать процессу завершиться и потоку закрыться естественным образом.
По умолчанию поток будет генерировать событие 'close'
после того, как он будет уничтожен. Установите опцию emitClose
в false
, чтобы изменить это поведение.
Предоставляя опцию fs
, можно переопределить соответствующие реализации fs
для open
, read
и close
. При предоставлении опции fs
требуется переопределение для read
. Если fd
не предоставлен, также требуется переопределение для open
. Если autoClose
имеет значение true
, также требуется переопределение для close
.
import { createReadStream } from 'node:fs'
// Создаём поток из некоторого символьного устройства.
const stream = createReadStream('/dev/input/event0')
setTimeout(() => {
stream.close() // Это может не закрыть поток.
// Искусственное обозначение конца потока, как если бы базовый ресурс
// сам указал конец файла, позволяет закрыть поток.
// Это не отменяет ожидающие операции чтения, и если такая операция есть,
// процесс всё ещё может не суметь успешно завершиться, пока она не завершится.
stream.push(null)
stream.read(0)
}, 100)
Если autoClose
имеет значение false, то дескриптор файла не будет закрыт, даже если произошла ошибка. Приложение отвечает за его закрытие и за то, чтобы не было утечки дескрипторов файлов. Если autoClose
установлено в true (поведение по умолчанию), при 'error'
или 'end'
дескриптор файла будет закрыт автоматически.
mode
устанавливает режим файла (разрешения и липкие биты), но только если файл был создан.
Пример чтения последних 10 байтов файла длиной 100 байтов:
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 |
flags
<строка> См. поддержку флагов файловой системы. По умолчанию:'w'
.encoding
<строка> По умолчанию:'utf8'
fd
<целое число> | <FileHandle> По умолчанию:null
mode
<целое число> По умолчанию:0o666
autoClose
<булево> По умолчанию:true
emitClose
<булево> По умолчанию:true
start
<целое число>fs
<Объект> | <null> По умолчанию:null
signal
<AbortSignal> | <null> По умолчанию:null
highWaterMark
<число> По умолчанию:16384
flush
<булево> Еслиtrue
, базовый дескриптор файла очищается перед закрытием. По умолчанию:false
.
Возвращает: <fs.WriteStream>
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:
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()
не рекомендуется. Это создает условие гонки, поскольку другие процессы могут изменить состояние файла между двумя вызовами. Вместо этого код пользователя должен открывать/читать/писать файл напрямую и обрабатывать ошибку, если файл не существует.
Запись (НЕ РЕКОМЕНДУЕТСЯ)
import { exists, open, close } from 'node:fs'
exists('myfile', e => {
if (e) {
console.error('myfile already exists')
} else {
open('myfile', 'wx', (err, fd) => {
if (err) throw err
try {
writeMyData(fd)
} finally {
close(fd, err => {
if (err) throw err
})
}
})
}
})
Запись (РЕКОМЕНДУЕТСЯ)
import { open, close } from 'node:fs'
open('myfile', 'wx', (err, fd) => {
if (err) {
if (err.code === 'EEXIST') {
console.error('myfile already exists')
return
}
throw err
}
try {
writeMyData(fd)
} finally {
close(fd, err => {
if (err) throw err
})
}
})
Чтение (НЕ РЕКОМЕНДУЕТСЯ)
import { open, close, exists } from 'node:fs'
exists('myfile', e => {
if (e) {
open('myfile', 'r', (err, fd) => {
if (err) throw err
try {
readMyData(fd)
} finally {
close(fd, err => {
if (err) throw err
})
}
})
} else {
console.error('myfile does not exist')
}
})
Чтение (РЕКОМЕНДУЕТСЯ)
import { open, close } from 'node:fs'
open('myfile', 'r', (err, fd) => {
if (err) {
if (err.code === 'ENOENT') {
console.error('myfile does not exist')
return
}
throw err
}
try {
readMyData(fd)
} finally {
close(fd, err => {
if (err) throw err
})
}
})
Приведённые выше примеры "не рекомендуется" проверяют существование, а затем используют файл; примеры "рекомендуется" лучше, потому что они используют файл напрямую и обрабатывают ошибку, если она есть.
В общем, проверяйте существование файла только в том случае, если файл не будет использоваться напрямую, например, когда его существование является сигналом от другого процесса.
fs.fchmod(fd, mode, callback)
[История]
Версия | Изменения |
---|---|
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 |
fd
<целое число>mode
<строка> | <целое число>callback
<Функция>err
<Ошибка>
Устанавливает права доступа к файлу. В функцию обратного вызова передается только возможное исключение.
Подробнее см. в документации 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 |
fd
<целое число>uid
<целое число>gid
<целое число>callback
<Функция>err
<Ошибка>
Устанавливает владельца файла. В функцию обратного вызова передается только возможное исключение.
Подробнее см. в документации 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 |
fd
<целое число>callback
<Функция>err
<Ошибка>
Принудительно завершает все текущие операции ввода-вывода, связанные с файлом, в состоянии синхронного завершения ввода-вывода операционной системы. Подробности см. в документации 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 |
options
<Объект>bigint
<булево> Должны ли числовые значения в возвращаемом объекте <fs.Stats> быть типаbigint
. По умолчанию:false
.
callback
<Функция>err
<Ошибка>stats
<fs.Stats>
Вызывает функцию обратного вызова с объектом <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 |
fd
<целое число>callback
<Функция>err
<Ошибка>
Запрос на очистку всех данных для открытого файлового дескриптора на устройство хранения. Конкретная реализация зависит от операционной системы и устройства. Для получения дополнительной информации см. документацию 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 |
fd
<целое число>len
<целое число> По умолчанию:0
callback
<Функция>err
<Ошибка>
Укорачивает файловый дескриптор. В функцию обратного вызова передаются только возможные исключения.
См. документацию POSIX ftruncate(2)
для получения дополнительной информации.
Если файл, на который ссылается файловый дескриптор, был больше len
байт, в файле останутся только первые len
байт.
Например, следующая программа сохраняет только первые четыре байта файла:
import { open, close, ftruncate } from 'node:fs'
function closeFd(fd) {
close(fd, err => {
if (err) throw err
})
}
open('temp.txt', 'r+', (err, fd) => {
if (err) throw err
try {
ftruncate(fd, 4, err => {
closeFd(fd)
if (err) throw err
})
} catch (err) {
closeFd(fd)
if (err) throw err
}
})
Если файл ранее был короче len
байт, он расширяется, а расширенная часть заполняется нулевыми байтами ('\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 |
fd
<целое число>atime
<число> | <строка> | <Date>mtime
<число> | <строка> | <Date>callback
<Функция>err
<Ошибка>
Изменение меток времени файловой системы объекта, на который ссылается предоставленный дескриптор файла. См. 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
<Функция>err
<Ошибка>
Извлекает файлы, соответствующие указанному шаблону.
import { glob } from 'node:fs'
glob('**/*.js', (err, matches) => {
if (err) throw err
console.log(matches)
})
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 |
path
<строка> | <Buffer> | <URL>mode
<целое число>callback
<Функция>err
<Ошибка> | <AggregateError>
Изменяет права доступа к символической ссылке. В функцию обратного вызова передаются только возможные исключения.
Этот метод реализован только в 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 | Устаревание только в документации. |
path
<строка> | <Buffer> | <URL>uid
<целое число>gid
<целое число>callback
<Функция>err
<Ошибка>
Устанавливает владельца символической ссылки. В функцию обратного вызова передаются только возможные исключения.
См. документацию 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 |
path
<строка> | <Buffer> | <URL>atime
<число> | <строка> | <Date>mtime
<число> | <строка> | <Date>callback
<Функция>err
<Error>
Изменяет время доступа и модификации файла так же, как 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
<строка> | <Buffer> | <URL>newPath
<строка> | <Buffer> | <URL>callback
<Функция>err
<Error>
Создаёт новую ссылку из 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 |
options
<Объект>bigint
<булево> Указывает, должны ли числовые значения в возвращаемом объекте <fs.Stats> быть типаbigint
. По умолчанию:false
.
callback
<Функция>err
<Ошибка>stats
<fs.Stats>
Возвращает <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 |
options
<Объект> | <целое число>recursive
<булево> По умолчанию:false
mode
<строка> | <целое число> Не поддерживается в Windows. По умолчанию:0o777
.
callback
<Функция>err
<Ошибка>path
<строка> | <неопределено> Присутствует только если каталог создан сrecursive
, установленным вtrue
.
Асинхронно создаёт каталог.
Обратный вызов получает возможное исключение и, если recursive
равно true
, первый созданный путь к каталогу, (err[, path])
. path
может оставаться undefined
, когда recursive
равно true
, если ни один каталог не был создан (например, если он был создан ранее).
Необязательный аргумент options
может быть целым числом, указывающим mode
(разрешения и липкие биты), или объектом со свойством mode
и свойством recursive
, указывающим, следует ли создавать родительские каталоги. Вызов fs.mkdir()
, когда path
является существующим каталогом, приводит к ошибке только когда recursive
равно false. Если recursive
равно false и каталог существует, возникает ошибка EEXIST
.
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()
в корневом каталоге даже с рекурсией приведёт к ошибке:
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
, указывающим используемую кодировку символов.
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
).
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 |
path
<строка> | <Buffer> | <URL>flags
<строка> | <число> См. поддержку флагов файловой системы. По умолчанию:'r'
.mode
<строка> | <целое число> По умолчанию:0o666
(доступен для чтения и записи)callback
<Функция>err
<Ошибка>fd
<целое число>
Асинхронное открытие файла. Более подробную информацию см. в документации 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
и перед каждым чтением для обнаружения того, были ли изменены данные файла на диске.
import { openAsBlob } from 'node:fs'
const blob = await openAsBlob('the.file.txt')
const ab = await blob.arrayBuffer()
blob.stream()
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 |
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
<целое число>buffer
<Buffer> | <TypedArray> | <DataView> Буфер, в который будут записаны данные.offset
<целое число> Позиция вbuffer
, куда будут записаны данные.length
<целое число> Количество байт для чтения.position
<целое число> | <bigint> | <null> Указывает, с какой позиции начинать чтение в файле. Еслиposition
равноnull
или-1
, данные будут читаться с текущей позиции в файле, и позиция файла будет обновлена. Еслиposition
— неотрицательное целое число, позиция файла останется неизменной.callback
<Функция>err
<Ошибка>bytesRead
<целое число>buffer
<Buffer>
Чтение данных из файла, указанного 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 |
options
<Объект>buffer
<Buffer> | <TypedArray> | <DataView> По умолчанию:Buffer.alloc(16384)
offset
<целое число> По умолчанию:0
length
<целое число> По умолчанию:buffer.byteLength - offset
position
<целое число> | <bigint> | <null> По умолчанию:null
callback
<Функция>err
<Ошибка>bytesRead
<целое число>buffer
<Buffer>
Аналогично функции fs.read()
, эта версия принимает необязательный объект options
. Если объект options
не указан, будут использоваться значения по умолчанию, указанные выше.
fs.read(fd, buffer[, options], callback)
Добавлено в: v18.2.0, v16.17.0
buffer
<Buffer> | <TypedArray> | <DataView> Буфер, в который будут записаны данные.options
<Объект>offset
<целое число> По умолчанию:0
length
<целое число> По умолчанию:buffer.byteLength - offset
position
<целое число> | <bigint> По умолчанию:null
callback
<Функция>err
<Error>bytesRead
<целое число>buffer
<Buffer>
Аналогично функции fs.read()
, эта версия принимает необязательный объект options
. Если объект options
не указан, будут использоваться значения по умолчанию, указанные выше.
fs.readdir(path[, options], callback)
[История]
Версия | Изменения |
---|---|
v20.1.0, v18.17.0 | Добавлен параметр recursive . |
v18.0.0 | Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_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 |
callback
<Функция>err
<Error>files
<string[]> | <Buffer[]> | <fs.Dirent[]>
Считывает содержимое каталога. Обратный вызов получает два аргумента (err, files)
, где files
— это массив имен файлов в каталоге, за исключением '.'
и '..'
.
См. документацию POSIX readdir(3)
для получения более подробной информации.
Необязательный аргумент options
может быть строкой, указывающей кодировку, или объектом со свойством encoding
, указывающим кодировку символов, которая будет использоваться для имен файлов, передаваемых в обратный вызов. Если encoding
установлен в 'buffer'
, возвращаемые имена файлов будут передаваться как объекты <Buffer>.
Если options.withFileTypes
установлено в true
, массив files
будет содержать объекты <fs.Dirent>.
fs.readFile(path[, options], callback)
[История]
Версия | Изменения |
---|---|
v18.0.0 | Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_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.0 | callback всегда будет вызываться с null в качестве параметра error в случае успеха. |
v5.0.0 | Параметр path теперь может быть файловым дескриптором. |
v0.1.29 | Добавлено в: v0.1.29 |
path
<строка> | <Buffer> | <URL> | <целое число> имя файла или файловый дескрипторencoding
<строка> | <null> По умолчанию:null
flag
<строка> См. поддержку флагов файловой системы. По умолчанию:'r'
.signal
<AbortSignal> позволяет прервать запущенный процесс чтения файла
callback
<Функция>err
<Ошибка> | <AggregateError>data
<строка> | <Buffer>
Асинхронно считывает всё содержимое файла.
import { readFile } from 'node:fs'
readFile('/etc/passwd', (err, data) => {
if (err) throw err
console.log(data)
})
В обратный вызов передаются два аргумента (err, data)
, где data
— это содержимое файла.
Если кодировка не указана, возвращается необработанный буфер.
Если options
— строка, то она указывает кодировку:
import { readFile } from 'node:fs'
readFile('/etc/passwd', 'utf8', callback)
Когда путь является каталогом, поведение fs.readFile()
и fs.readFileSync()
зависит от платформы. На macOS, Linux и Windows будет возвращена ошибка. На FreeBSD будет возвращено представление содержимого каталога.
import { readFile } from 'node:fs'
// macOS, Linux и Windows
readFile('<каталог>', (err, data) => {
// => [Error: EISDIR: недопустимая операция над каталогом, чтение <каталог>]
})
// FreeBSD
readFile('<каталог>', (err, data) => {
// => null, <data>
})
Можно прервать запущенный запрос с помощью AbortSignal
. Если запрос прерывается, обратный вызов вызывается с AbortError
:
import { readFile } from 'node:fs'
const controller = new AbortController()
const signal = controller.signal
readFile(fileInfo[0].name, { signal }, (err, buf) => {
// ...
})
// Когда нужно прервать запрос
controller.abort()
Функция fs.readFile()
буферизует весь файл. Для минимизации затрат памяти, когда это возможно, предпочтительнее использовать потоковую передачу через fs.createReadStream()
.
Прерывание текущего запроса не прерывает отдельные запросы операционной системы, а внутреннее буферирование, выполняемое fs.readFile
.
Дескрипторы файлов
Соображения по производительности
Метод fs.readFile()
асинхронно считывает содержимое файла в память по одному фрагменту за раз, позволяя циклу событий переключаться между каждым фрагментом. Это позволяет операции чтения оказывать меньшее влияние на другую активность, которая может использовать базовый пул потоков libuv, но означает, что чтение полного файла в память займет больше времени.
Дополнительные накладные расходы на чтение могут значительно различаться на разных системах и зависят от типа считываемого файла. Если тип файла не является обычным файлом (например, конвейер) и Node.js не может определить фактический размер файла, каждая операция чтения будет загружать 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
<целое число>buffers
<ArrayBufferView[]>position
<целое число> | <null> По умолчанию:null
callback
<Функция>err
<Ошибка>bytesRead
<целое число>buffers
<ArrayBufferView[]>
Чтение из файла, указанного 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
<строка> | <Buffer> | <URL>newPath
<строка> | <Buffer> | <URL>callback
<Функция>err
<Ошибка>
Асинхронно переименовывает файл по пути oldPath
в имя файла, указанное как newPath
. В случае, если newPath
уже существует, он будет перезаписан. Если по пути newPath
находится директория, будет выброшено исключение. В функцию обратного вызова не передаются никакие аргументы, кроме возможного исключения.
См. также: rename(2)
.
import { rename } from 'node:fs'
rename('oldFile.txt', 'newFile.txt', err => {
if (err) throw err
console.log('Rename complete!')
})
fs.rmdir(path[, options], callback)
[История]
Версия | Изменения |
---|---|
v18.0.0 | Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_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 |
options
<Object>maxRetries
<integer> Если возникает ошибкаEBUSY
,EMFILE
,ENFILE
,ENOTEMPTY
илиEPERM
, Node.js повторяет операцию с линейной экспоненциальной задержкой вretryDelay
миллисекунд дольше при каждой попытке. Эта опция представляет собой количество повторов. Эта опция игнорируется, если опцияrecursive
не равнаtrue
. По умолчанию:0
.recursive
<boolean> Еслиtrue
, выполняется рекурсивное удаление каталога. В рекурсивном режиме операции повторяются при сбое. По умолчанию:false
. Устарело.retryDelay
<integer> Время ожидания в миллисекундах между попытками. Эта опция игнорируется, если опцияrecursive
не равнаtrue
. По умолчанию:100
.
callback
<Function>err
<Error>
Асинхронный rmdir(2)
. В функцию обратного вызова передаются только возможные исключения.
Использование fs.rmdir()
для файла (а не каталога) приводит к ошибке 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 |
options
<Объект>force
<булево> Еслиtrue
, исключения игнорируются, еслиpath
не существует. По умолчанию:false
.maxRetries
<целое число> Если возникает ошибкаEBUSY
,EMFILE
,ENFILE
,ENOTEMPTY
илиEPERM
, Node.js будет повторять операцию с линейной экспоненциальной задержкой вretryDelay
миллисекунд дольше при каждой попытке. Этот параметр представляет количество попыток. Этот параметр игнорируется, если параметрrecursive
не равенtrue
. По умолчанию:0
.recursive
<булево> Еслиtrue
, выполняется рекурсивное удаление. В рекурсивном режиме операции повторяются при сбое. По умолчанию:false
.retryDelay
<целое число> Время в миллисекундах для ожидания между попытками. Этот параметр игнорируется, если параметрrecursive
не равенtrue
. По умолчанию:100
.
callback
<Функция>err
<Ошибка>
Асинхронно удаляет файлы и каталоги (моделируется по стандартной утилите POSIX rm
). В функцию обратного вызова завершения не передаются аргументы, кроме возможного исключения.
fs.stat(path[, options], callback)
[История]
Версия | Изменения |
---|---|
v18.0.0 | Передача недопустимого обратного вызова в аргумент callback теперь вызывает исключение ERR_INVALID_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 |
options
<Объект>bigint
<логическое> Должны ли числовые значения в возвращаемом объекте <fs.Stats> быть типаbigint
. По умолчанию:false
.
callback
<Функция>err
<Ошибка>stats
<fs.Stats>
Асинхронный stat(2)
. Обратный вызов получает два аргумента (err, stats)
, где stats
— это объект <fs.Stats>.
В случае ошибки, err.code
будет одним из Общие системные ошибки.
fs.stat()
следует символическим ссылкам. Используйте fs.lstat()
, чтобы просмотреть сами ссылки.
Использование fs.stat()
для проверки существования файла перед вызовом fs.open()
, fs.readFile()
или fs.writeFile()
не рекомендуется. Вместо этого пользовательский код должен открывать/читать/записывать файл напрямую и обрабатывать ошибку, которая возникает, если файл недоступен.
Для проверки существования файла без последующего его изменения рекомендуется использовать fs.access()
.
Например, при следующей структуре каталогов:
- txtDir
-- file.txt
- app.js
Следующая программа проверит статистику указанных путей:
import { stat } from 'node:fs'
const pathsToCheck = ['./txtDir', './txtDir/file.txt']
for (let i = 0; i < pathsToCheck.length; i++) {
stat(pathsToCheck[i], (err, stats) => {
console.log(stats.isDirectory())
console.log(stats)
})
}
Полученный вывод будет выглядеть примерно так:
true
Stats {
dev: 16777220,
mode: 16877,
nlink: 3,
uid: 501,
gid: 20,
rdev: 0,
blksize: 4096,
ino: 14214262,
size: 96,
blocks: 0,
atimeMs: 1561174653071.963,
mtimeMs: 1561174614583.3518,
ctimeMs: 1561174626623.5366,
birthtimeMs: 1561174126937.2893,
atime: 2019-06-22T03:37:33.072Z,
mtime: 2019-06-22T03:36:54.583Z,
ctime: 2019-06-22T03:37:06.624Z,
birthtime: 2019-06-22T03:28:46.937Z
}
false
Stats {
dev: 16777220,
mode: 33188,
nlink: 1,
uid: 501,
gid: 20,
rdev: 0,
blksize: 4096,
ino: 14214074,
size: 8,
blocks: 8,
atimeMs: 1561174616618.8555,
mtimeMs: 1561174614584,
ctimeMs: 1561174614583.8145,
birthtimeMs: 1561174007710.7478,
atime: 2019-06-22T03:36:56.619Z,
mtime: 2019-06-22T03:36:54.584Z,
ctime: 2019-06-22T03:36:54.584Z,
birthtime: 2019-06-22T03:26:47.711Z
}
fs.statfs(path[, options], callback)
Добавлено в: v19.6.0, v18.15.0
options
<Object>bigint
<boolean> Должны ли числовые значения в возвращаемом объекте <fs.StatFs> бытьbigint
. По умолчанию:false
.
callback
<Function>err
<Error>stats
<fs.StatFs>
Асинхронный 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 |
target
<string> | <Buffer> | <URL>path
<string> | <Buffer> | <URL>type
<string> | <null> По умолчанию:null
callback
<Function>err
<Error>
Создает ссылку с именем path
, указывающую на target
. В обратный вызов завершения не передаются никакие аргументы, кроме возможного исключения.
См. документацию POSIX symlink(2)
для получения более подробной информации.
Аргумент type
доступен только в Windows и игнорируется на других платформах. Он может быть установлен в 'dir'
, 'file'
или 'junction'
. Если аргумент type
имеет значение null
, Node.js автоматически определит тип target
и использует 'file'
или 'dir'
. Если target
не существует, будет использоваться 'file'
. Точки соединения Windows требуют, чтобы путь к месту назначения был абсолютным. При использовании 'junction'
аргумент target
будет автоматически нормализован до абсолютного пути. Точки соединения в томах NTFS могут указывать только на каталоги.
Относительные цели являются относительными к родительскому каталогу ссылки.
import { symlink } from 'node:fs'
symlink('./mew', './mewtwo', callback)
В приведенном выше примере создается символическая ссылка mewtwo
, которая указывает на mew
в том же каталоге:
$ 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 |
path
<строка> | <Buffer> | <URL>len
<целое число> По умолчанию:0
callback
<Функция>err
<Ошибка> | <AggregateError>
Усекает файл. В функцию обратного вызова передаются только возможные исключения. В качестве первого аргумента также может быть передан дескриптор файла. В этом случае вызывается fs.ftruncate()
.
import { truncate } from 'node:fs'
// Предполагается, что 'path/file.txt' — это обычный файл.
truncate('path/file.txt', err => {
if (err) throw err
console.log('path/file.txt was truncated')
})
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 |
Асинхронно удаляет файл или символическую ссылку. В функцию обратного вызова передаются только возможные исключения.
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
<строка> | <Buffer> | <URL>listener
<Функция> Необязательно, обработчик, ранее прикреплённый с помощьюfs.watchFile()
Прекращает наблюдение за изменениями в 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.0 | NaN , 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
<string> | <Buffer> | <URL>atime
<number> | <string> | <Date>mtime
<number> | <string> | <Date>callback
<Function>err
<Error>
Изменить метки времени файловой системы объекта, на который ссылается path
.
Аргументы atime
и mtime
следуют этим правилам:
- Значения могут быть числами, представляющими время эпохи Unix в секундах, объектами
Date
или числовыми строками, такими как'123456789.0'
. - Если значение не может быть преобразовано в число или является
NaN
,Infinity
или-Infinity
, будет выброшена ошибкаError
.
fs.watch(filename[, options][, listener])
[История]
Версия | Изменения |
---|---|
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 |
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
.
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 |
options
<Object>listener
<Function>current
<fs.Stats>previous
<fs.Stats>
Возвращает: <fs.StatWatcher>
Отслеживает изменения в filename
. Обратный вызов listener
будет вызываться каждый раз при доступе к файлу.
Аргумент options
может быть опущен. Если он предоставлен, он должен быть объектом. Объект options
может содержать булево значение persistent
, указывающее, должен ли процесс продолжать работу, пока файлы находятся под наблюдением. Объект options
может указывать свойство interval
, указывающее, как часто целевой объект должен опрашиваться в миллисекундах.
listener
получает два аргумента: текущий объект stat и предыдущий объект stat:
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 |
fd
<целое число>buffer
<Buffer> | <TypedArray> | <DataView>offset
<целое число> По умолчанию:0
length
<целое число> По умолчанию:buffer.byteLength - offset
position
<целое число> | <null> По умолчанию:null
callback
<Функция>err
<Ошибка>bytesWritten
<целое число>buffer
<Buffer> | <TypedArray> | <DataView>
Записывает 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
fd
<целое>buffer
<Buffer> | <TypedArray> | <DataView>options
<Объект>callback
<Функция>err
<Ошибка>bytesWritten
<целое>buffer
<Buffer> | <TypedArray> | <DataView>
Записывает 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 |
fd
<целое>string
<строка>position
<целое> | <null> По умолчанию:null
encoding
<строка> По умолчанию:'utf8'
callback
<Функция>
Записывает 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
<строка> | <Buffer> | <URL> | <целое число> имя файла или дескриптор файлаdata
<строка> | <Buffer> | <TypedArray> | <DataView>encoding
<строка> | <null> По умолчанию:'utf8'
mode
<целое число> По умолчанию:0o666
flag
<строка> См. поддержку флагов файловой системы. По умолчанию:'w'
.flush
<булево> Если все данные успешно записаны в файл, иflush
имеет значениеtrue
, то для сброса данных используетсяfs.fsync()
. По умолчанию:false
.signal
<AbortSignal> позволяет прервать незавершенную запись writeFile
callback
<Функция>err
<Ошибка> | <AggregateError>
Если file
— это имя файла, асинхронно записывает данные в файл, заменяя файл, если он уже существует. data
может быть строкой или буфером.
Если file
— это дескриптор файла, поведение аналогично прямому вызову fs.write()
(что рекомендуется). См. примечания ниже об использовании дескриптора файла.
Параметр encoding
игнорируется, если data
— это буфер.
Параметр mode
влияет только на вновь созданный файл. См. fs.open()
для получения более подробной информации.
import { writeFile } from 'node:fs'
import { Buffer } from 'node:buffer'
const data = new Uint8Array(Buffer.from('Hello Node.js'))
writeFile('message.txt', data, err => {
if (err) throw err
console.log('Файл сохранен!')
})
Если options
— это строка, то она указывает кодировку:
import { writeFile } from 'node:fs'
writeFile('message.txt', 'Hello Node.js', 'utf8', callback)
Небезопасно использовать fs.writeFile()
несколько раз для одного и того же файла, не дожидаясь обратного вызова. Для этого сценария рекомендуется использовать fs.createWriteStream()
.
Аналогично fs.readFile
- fs.writeFile
- это вспомогательный метод, который внутренне выполняет несколько вызовов write
для записи буфера, переданного ему. Для кода, чувствительного к производительности, следует рассмотреть использование fs.createWriteStream()
.
Можно использовать <AbortSignal> для отмены fs.writeFile()
. Отмена выполняется "по возможности", и некоторое количество данных, вероятно, все еще будет записано.
import { writeFile } from 'node:fs'
import { Buffer } from 'node:buffer'
const controller = new AbortController()
const { signal } = controller
const data = new Uint8Array(Buffer.from('Hello Node.js'))
writeFile('message.txt', data, { signal }, err => {
// Когда запрос прерывается - обратный вызов вызывается с AbortError
})
// Когда запрос должен быть прерван
controller.abort()
Прерывание текущего запроса не прерывает отдельные запросы операционной системы, а скорее внутреннее буферизованное выполнение fs.writeFile
.
Использование fs.writeFile()
с дескрипторами файлов
Когда file
— это дескриптор файла, поведение практически идентично прямому вызову fs.write()
, например:
import { write } from 'node:fs'
import { Buffer } from 'node:buffer'
write(fd, Buffer.from(data, options.encoding), callback)
Отличие от прямого вызова fs.write()
заключается в том, что в некоторых необычных условиях fs.write()
может записать только часть буфера и потребует повторного вызова для записи оставшихся данных, тогда как fs.writeFile()
повторяет попытки до тех пор, пока данные не будут полностью записаны (или не произойдет ошибка).
Последствия этого являются частым источником путаницы. В случае с дескриптором файла файл не заменяется! Данные не обязательно записываются в начало файла, и исходные данные файла могут оставаться до и/или после вновь записанных данных.
Например, если fs.writeFile()
вызывается дважды подряд, сначала для записи строки '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 |
fd
<целое число>buffers
<ArrayBufferView[]>position
<целое число> | <null> По умолчанию:null
callback
<Функция>err
<Ошибка>bytesWritten
<целое число>buffers
<ArrayBufferView[]>
Запись массива 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
.
import { accessSync, constants } from 'node:fs'
try {
accessSync('etc/passwd', constants.R_OK | constants.W_OK)
console.log('доступ к чтению/записи')
} catch (err) {
console.error('нет доступа!')
}
fs.appendFileSync(path, data[, options])
[История]
Версия | Изменения |
---|---|
v21.1.0, v20.10.0 | Теперь поддерживается параметр flush . |
v7.0.0 | Переданный объект options никогда не будет изменен. |
v5.0.0 | Параметр file теперь может быть дескриптором файла. |
v0.6.7 | Добавлено в: v0.6.7 |
path
<string> | <Buffer> | <URL> | <number> имя файла или дескриптор файлаdata
<string> | <Buffer>options
<Object> | <string>
Синхронно добавляет данные в файл, создавая файл, если он еще не существует. data
может быть строкой или <Buffer>.
Параметр mode
влияет только на вновь созданный файл. Подробнее см. в разделе fs.open()
.
import { appendFileSync } from 'node:fs'
try {
appendFileSync('message.txt', 'data to append')
console.log('Данные "data to append" были добавлены в файл!')
} catch (err) {
/* Обработка ошибки */
}
Если options
— это строка, то она указывает кодировку:
import { appendFileSync } from 'node:fs'
appendFileSync('message.txt', 'data to append', 'utf8')
path
может быть указан как числовой дескриптор файла, который был открыт для добавления (с помощью fs.open()
или fs.openSync()
). Дескриптор файла не будет закрыт автоматически.
import { openSync, closeSync, appendFileSync } from 'node:fs'
let fd
try {
fd = openSync('message.txt', 'a')
appendFileSync(fd, 'data to append', 'utf8')
} catch (err) {
/* Обработка ошибки */
} finally {
if (fd !== undefined) closeSync(fd)
}
fs.chmodSync(path, mode)
[История]
Версия | Изменения |
---|---|
v7.6.0 | Параметр path может быть объектом WHATWG URL с использованием протокола file: |
v0.6.7 | Добавлено в: v0.6.7 |
path
<строка> | <Buffer> | <URL>mode
<строка> | <целое число>
Для подробной информации см. документацию асинхронной версии этого API: fs.chmod()
.
См. документацию POSIX chmod(2)
для получения более подробной информации.
fs.chownSync(path, uid, gid)
[История]
Версия | Изменения |
---|---|
v7.6.0 | Параметр path может быть объектом WHATWG URL с использованием протокола file: |
v0.1.97 | Добавлено в: v0.1.97 |
path
<строка> | <Buffer> | <URL>uid
<целое число>gid
<целое число>
Синхронно изменяет владельца и группу файла. Возвращает 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
<строка> | <Buffer> | <URL> имя исходного файла для копированияdest
<строка> | <Buffer> | <URL> имя файла назначения для операции копированияmode
<целое число> модификаторы для операции копирования. По умолчанию: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 с копированием при записи. Если платформа не поддерживает копирование при записи, операция завершится ошибкой.
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 |
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()
не использует обратный вызов.
import { existsSync } from 'node:fs'
if (existsSync('/etc/passwd')) console.log('Путь существует.')
fs.fchmodSync(fd, mode)
Добавлено в: v0.4.7
fd
<целое число>mode
<строка> | <целое число>
Устанавливает права доступа к файлу. Возвращает undefined
.
См. документацию POSIX fchmod(2)
для получения более подробной информации.
fs.fchownSync(fd, uid, gid)
Добавлено в: v0.4.7
fd
<целое число>uid
<целое число> Идентификатор пользователя нового владельца файла.gid
<целое число> Идентификатор группы нового владельца файла.
Устанавливает владельца файла. Возвращает undefined
.
См. документацию POSIX fchown(2)
для получения более подробной информации.
fs.fdatasyncSync(fd)
Добавлено в: v0.1.96
fd
<integer>
Принудительно выполняет все текущие операции ввода-вывода, связанные с файлом, до состояния синхронного завершения ввода-вывода операционной системы. Подробности см. в документации 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
fd
<integer>
Запрос на сброс всех данных для открытого дескриптора файла на устройство хранения. Конкретная реализация зависит от операционной системы и устройства. Подробности см. в документации 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
.
Возвращает: <массив строк> пути к файлам, соответствующим шаблону.
import { globSync } from 'node:fs'
console.log(globSync('**/*.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 | Устаревание только в документации. |
path
<string> | <Buffer> | <URL>uid
<integer> ID пользователя нового владельца файла.gid
<integer> ID группы нового владельца файла.
Устанавливает владельца для пути. Возвращает undefined
.
См. документацию POSIX lchown(2)
для получения более подробной информации.
fs.lutimesSync(path, atime, mtime)
Добавлен в: v14.5.0, v12.19.0
path
<string> | <Buffer> | <URL>atime
<number> | <string> | <Date>mtime
<number> | <string> | <Date>
Изменяет метки времени файловой системы символической ссылки, на которую ссылается path
. Возвращает undefined
или вызывает исключение, если параметры неверны или операция завершилась неудачей. Это синхронная версия fs.lutimes()
.
fs.linkSync(existingPath, newPath)
[История]
Версия | Изменения |
---|---|
v7.6.0 | Параметры existingPath и newPath могут быть объектами 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 |
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 |
Возвращает: <string> | <undefined>
Синхронно создаёт директорию. Возвращает undefined
, или, если recursive
имеет значение true
, первый созданный путь к директории. Это синхронная версия fs.mkdir()
.
См. документацию POSIX mkdir(2)
для более подробной информации.
fs.mkdtempSync(prefix[, options])
[История]
Версия | Изменения |
---|---|
v20.6.0, v18.19.0 | Параметр prefix теперь принимает буферы и URL. |
v16.5.0, v14.18.0 | Параметр prefix теперь принимает пустую строку. |
v5.10.0 | Добавлено в: v5.10.0 |
Возвращает путь к созданной директории.
Для подробной информации см. документацию асинхронной версии этого 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 |
Синхронно открывает каталог. См. 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 |
path
<строка> | <Buffer> | <URL>flags
<строка> | <число> По умолчанию:'r'
. См. поддержку флагов файловой системы.mode
<строка> | <целое число> По умолчанию:0o666
- Возвращает: <число>
Возвращает целое число, представляющее дескриптор файла.
Для подробной информации см. документацию асинхронной версии этого 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 |
Возвращает: <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
<строка> | <Buffer> | <URL> | <целое число> имя файла или файловый дескрипторencoding
<строка> | <null> По умолчанию:null
flag
<строка> См. поддержку флагов файловой системы. По умолчанию:'r'
.
Возвращает содержимое path
.
Для получения подробной информации см. документацию асинхронной версии этого API: fs.readFile()
.
Если указан параметр encoding
, то функция возвращает строку. В противном случае она возвращает буфер.
Аналогично fs.readFile()
, когда путь является директорией, поведение fs.readFileSync()
зависит от платформы.
import { readFileSync } from 'node:fs'
// macOS, Linux и Windows
readFileSync('<directory>')
// => [Error: EISDIR: недопустимая операция над директорией, чтение <directory>]
// FreeBSD
readFileSync('<directory>') // => <данные>
fs.readlinkSync(path[, options])
[История]
Версия | Изменения |
---|---|
v7.6.0 | Параметр path может быть объектом WHATWG URL с использованием протокола file: |
v0.1.31 | Добавлено в: v0.1.31 |
encoding
<строка> По умолчанию:'utf8'
Возвращает строковое значение символической ссылки.
Дополнительные сведения см. в документации POSIX readlink(2)
.
Необязательный аргумент options
может быть строкой, указывающей кодировку, или объектом со свойством encoding
, указывающим используемую кодировку символов для возвращаемого пути ссылки. Если encoding
установлен в 'buffer'
, возвращаемый путь ссылки будет передан как объект <Buffer>.
fs.readSync(fd, buffer, offset, length[, position])
[История]
Версия | Изменения |
---|---|
v10.10.0 | Параметр buffer теперь может быть любым TypedArray или DataView . |
v6.0.0 | Параметр length теперь может быть равен 0 . |
v0.1.21 | Добавлено в: v0.1.21 |
fd
<целое число>buffer
<Buffer> | <TypedArray> | <DataView>offset
<целое число>length
<целое число>position
<целое число> | <bigint> | <null> По умолчанию:null
- Возвращает: <число>
Возвращает количество 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 |
buffer
<Buffer> | <TypedArray> | <DataView>options
<Объект>offset
<целое число> По умолчанию:0
length
<целое число> По умолчанию:buffer.byteLength - offset
position
<целое число> | <bigint> | <null> По умолчанию:null
Возвращает: <число>
Возвращает количество bytesRead
.
Аналогично описанной выше функции fs.readSync
, эта версия принимает необязательный объект options
. Если объект options
не указан, будут использованы значения по умолчанию, указанные выше.
Для получения подробной информации см. документацию асинхронной версии этого API: fs.read()
.
fs.readvSync(fd, buffers[, position])
Добавлено в: v13.13.0, v12.17.0
fd
<целое число>buffers
<ArrayBufferView[]>position
<целое число> | <null> По умолчанию:null
- Возвращает: <число> Количество прочитанных байтов.
Для получения подробной информации см. документацию асинхронной версии этого API: fs.readv()
.
fs.realpathSync(path[, options])
[История]
Версия | Изменения |
---|---|
v8.0.0 | Добавлена поддержка разрешения каналов/сокетов. |
v7.6.0 | Параметр path может быть объектом WHATWG URL с использованием протокола file: . |
v6.4.0 | Вызов realpathSync снова работает для различных пограничных случаев в Windows. |
v6.0.0 | Параметр cache удален. |
v0.1.31 | Добавлено в: v0.1.31 |
encoding
<строка> По умолчанию:'utf8'
Возвращает разрешенное имя пути.
Для подробной информации см. документацию асинхронной версии этого API: fs.realpath()
.
fs.realpathSync.native(path[, options])
Добавлено в: v9.2.0
encoding
<строка> По умолчанию:'utf8'
Синхронный 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 |
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
options
<Object>bigint
<boolean> Должны ли числовые значения в возвращаемом объекте <fs.StatFs> бытьbigint
. По умолчанию:false
.
Возвращает: <fs.StatFs>
Синхронный statfs(2)
. Возвращает информацию о смонтированной файловой системе, содержащей path
.
В случае ошибки, err.code
будет одним из Общие системные ошибки.
fs.symlinkSync(target, path[, type])
[История]
Версия | Изменения |
---|---|
v12.0.0 | Если аргумент type оставлен неопределенным, Node автоматически определит тип target и автоматически выберет dir или file . |
v7.6.0 | Параметры target и path могут быть объектами WHATWG URL с использованием протокола file: . Поддержка в настоящее время все еще экспериментальная. |
v0.1.31 | Добавлено в: v0.1.31 |
target
<string> | <Buffer> | <URL>path
<string> | <Buffer> | <URL>type
<string> | <null> По умолчанию:null
Возвращает undefined
.
Для подробной информации см. документацию асинхронной версии этого API: fs.symlink()
.
fs.truncateSync(path[, len])
Добавлено в: v0.8.6
path
<строка> | <Buffer> | <URL>len
<целое число> По умолчанию:0
Усекает файл. Возвращает 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.0 | NaN , 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 |
file
<строка> | <Buffer> | <URL> | <целое число> имя файла или дескриптор файлаdata
<строка> | <Buffer> | <TypedArray> | <DataView>options
<Объект> | <строка>encoding
<строка> | <null> По умолчанию:'utf8'
mode
<целое число> По умолчанию:0o666
flag
<строка> См. поддержку флагов файловой системы. По умолчанию:'w'
.flush
<булево> Если все данные успешно записаны в файл, иflush
равноtrue
, используетсяfs.fsyncSync()
для очистки данных.
Возвращает undefined
.
Параметр mode
влияет только на вновь созданный файл. См. fs.open()
для получения более подробной информации.
Для подробной информации см. документацию асинхронной версии этого API: fs.writeFile()
.
fs.writeSync(fd, buffer, offset[, length[, position]])
[История]
Версия | Изменения |
---|---|
v14.0.0 | Параметр buffer больше не будет приводить неподдерживаемые входные данные к строкам. |
v10.10.0 | Параметр buffer теперь может быть любым TypedArray или DataView . |
v7.4.0 | Параметр buffer теперь может быть Uint8Array . |
v7.2.0 | Параметры offset и length теперь являются необязательными. |
v0.1.21 | Добавлено в: v0.1.21 |
fd
<целое>buffer
<Buffer> | <TypedArray> | <DataView>offset
<целое> По умолчанию:0
length
<целое> По умолчанию:buffer.byteLength - offset
position
<целое> | <null> По умолчанию:null
- Возвращает: <число> Количество записанных байтов.
Для подробной информации см. документацию асинхронной версии этого API: fs.write(fd, buffer...)
.
fs.writeSync(fd, buffer[, options])
Добавлено в: v18.3.0, v16.17.0
fd
<целое>buffer
<Buffer> | <TypedArray> | <DataView>options
<Объект>Возвращает: <число> Количество записанных байтов.
Для подробной информации см. документацию асинхронной версии этого API: fs.write(fd, buffer...)
.
fs.writeSync(fd, string[, position[, encoding]])
[История]
Версия | Изменения |
---|---|
v14.0.0 | Параметр string больше не будет приводить неподдерживаемые входные данные к строкам. |
v7.2.0 | Параметр position теперь необязательный. |
v0.11.5 | Добавлено в: v0.11.5 |
fd
<целое число>string
<строка>position
<целое число> | <null> По умолчанию:null
encoding
<строка> По умолчанию:'utf8'
- Возвращает: <число> Количество записанных байтов.
Для подробной информации см. документацию асинхронной версии этого API: fs.write(fd, string...)
.
fs.writevSync(fd, buffers[, position])
Добавлено в: v12.9.0
fd
<целое число>buffers
<ArrayBufferView[]>position
<целое число> | <null> По умолчанию:null
- Возвращает: <число> Количество записанных байтов.
Для подробной информации см. документацию асинхронной версии этого API: fs.writev()
.
Общие объекты
Общие объекты используются всеми вариантами API файловой системы (promise, callback и синхронный).
Класс: fs.Dir
Добавлен в: v12.12.0
Класс, представляющий поток каталога.
Создается с помощью fs.opendir()
, fs.opendirSync()
или fsPromises.opendir()
.
import { opendir } from 'node:fs/promises'
try {
const dir = await opendir('./')
for await (const dirent of dir) console.log(dirent.name)
} catch (err) {
console.error(err)
}
При использовании асинхронного итератора объект <fs.Dir> будет автоматически закрыт после выхода из итератора.
dir.close()
Добавлен в: v12.12.0
- Возвращает: <Promise>
Асинхронно закрывает дескриптор базового ресурса каталога. Последующие операции чтения приведут к ошибкам.
Возвращается промис, который будет выполнен после закрытия ресурса.
dir.close(callback)
[История]
Версия | Изменения |
---|---|
v18.0.0 | Передача недопустимого обратного вызова в аргумент callback теперь вызывает ERR_INVALID_ARG_TYPE вместо ERR_INVALID_CALLBACK . |
v12.12.0 | Добавлено в: v12.12.0 |
callback
<Function>err
<Error>
Асинхронно закрывает дескриптор базового ресурса каталога. Последующие операции чтения приведут к ошибкам.
Обратный вызов callback
будет вызван после закрытия дескриптора ресурса.
dir.closeSync()
Добавлен в: v12.12.0
Синхронно закрывает дескриптор базового ресурса каталога. Последующие операции чтения приведут к ошибкам.
dir.path
Добавлен в: v12.12.0
Только для чтения путь к этому каталогу, как он был предоставлен в fs.opendir()
, fs.opendirSync()
или fsPromises.opendir()
.
dir.read()
Добавлено в: v12.12.0
- Возвращает: <Promise> Выполняется с <fs.Dirent> | <null>
Асинхронно читает следующую запись каталога через readdir(3)
как <fs.Dirent>.
Возвращается promise, который будет выполнен с <fs.Dirent> или null
, если больше нет записей каталога для чтения.
Записи каталога, возвращаемые этой функцией, не имеют определенного порядка, как предоставляется базовыми механизмами каталогов операционной системы. Записи, добавленные или удаленные во время итерации по каталогу, могут не быть включены в результаты итерации.
dir.read(callback)
Добавлено в: v12.12.0
callback
<Function>err
<Error>dirent
<fs.Dirent> | <null>
Асинхронно читает следующую запись каталога через readdir(3)
как <fs.Dirent>.
После завершения чтения callback
будет вызван с <fs.Dirent> или null
, если больше нет записей каталога для чтения.
Записи каталога, возвращаемые этой функцией, не имеют определенного порядка, как предоставляется базовыми механизмами каталогов операционной системы. Записи, добавленные или удаленные во время итерации по каталогу, могут не быть включены в результаты итерации.
dir.readSync()
Добавлено в: v12.12.0
- Возвращает: <fs.Dirent> | <null>
Синхронно читает следующую запись каталога как <fs.Dirent>. См. документацию POSIX readdir(3)
для получения более подробной информации.
Если больше нет записей каталога для чтения, будет возвращено null
.
Записи каталога, возвращаемые этой функцией, не имеют определенного порядка, как предоставляется базовыми механизмами каталогов операционной системы. Записи, добавленные или удаленные во время итерации по каталогу, могут не быть включены в результаты итерации.
dir[Symbol.asyncIterator]()
Добавлено в: v12.12.0
- Возвращает: <AsyncIterator> Асинхронный итератор <fs.Dirent>
Асинхронно итерирует по директории, пока не будут прочитаны все записи. Более подробную информацию см. в документации 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
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Dirent> описывает блочное устройство.
dirent.isCharacterDevice()
Добавлено в: v10.10.0
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Dirent> описывает символьное устройство.
dirent.isDirectory()
Добавлено в: v10.10.0
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Dirent> описывает директорию файловой системы.
dirent.isFIFO()
Добавлено в: v10.10.0
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Dirent> описывает канал FIFO (first-in-first-out).
dirent.isFile()
Добавлено в: v10.10.0
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Dirent> описывает обычный файл.
dirent.isSocket()
Добавлено в: v10.10.0
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Dirent> описывает сокет.
dirent.isSymbolicLink()
Добавлено в: v10.10.0
- Возвращает: <boolean>
Возвращает 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
- Расширяет <EventEmitter>
Успешный вызов метода 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.
import { watch } from 'node:fs'
// Пример обработки через обработчик fs.watch()
watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
if (filename) {
console.log(filename)
// Выводит: <Buffer ...>
}
})
Событие: 'close'
Добавлено в: v10.0.0
Генерируется, когда наблюдатель прекращает отслеживание изменений. Закрытый объект <fs.FSWatcher> более не доступен в обработчике событий.
Событие: 'error'
Добавлено в: v0.5.8
error
<Error>
Генерируется при возникновении ошибки во время наблюдения за файлом. Объект <fs.FSWatcher> с ошибкой более не доступен в обработчике событий.
watcher.close()
Добавлено в: v0.5.8
Остановить наблюдение за изменениями в заданном <fs.FSWatcher>. После остановки объект <fs.FSWatcher> более не доступен.
watcher.ref()
Добавлено в: v14.3.0, v12.20.0
- Возвращает: <fs.FSWatcher>
При вызове запрашивает, чтобы цикл событий Node.js не завершался, пока активен <fs.FSWatcher>. Многократный вызов watcher.ref()
не будет иметь эффекта.
По умолчанию все объекты <fs.FSWatcher> имеют ссылку ("ref'ed"), поэтому обычно нет необходимости вызывать watcher.ref()
, если ранее не был вызван watcher.unref()
.
watcher.unref()
Добавлено в: v14.3.0, v12.20.0
- Возвращает: <fs.FSWatcher>
При вызове активный объект <fs.FSWatcher> не будет требовать, чтобы цикл событий Node.js оставался активным. Если нет другой активности, поддерживающей работу цикла событий, процесс может завершиться до вызова обратного вызова объекта <fs.FSWatcher>. Многократный вызов watcher.unref()
не будет иметь эффекта.
Класс: fs.StatWatcher
Добавлено в: v14.3.0, v12.20.0
- Расширяет <EventEmitter>
Успешный вызов метода fs.watchFile()
вернет новый объект <fs.StatWatcher>.
watcher.ref()
Добавлено в: v14.3.0, v12.20.0
- Возвращает: <fs.StatWatcher>
При вызове запрашивает, чтобы цикл событий Node.js не завершался, пока активен <fs.StatWatcher>. Многократный вызов watcher.ref()
не будет иметь эффекта.
По умолчанию все объекты <fs.StatWatcher> имеют ссылку ("ref'ed"), поэтому обычно нет необходимости вызывать watcher.ref()
, если ранее не был вызван watcher.unref()
.
watcher.unref()
Добавлен в: v14.3.0, v12.20.0
- Возвращает: <fs.StatWatcher>
После вызова активный объект <fs.StatWatcher> не будет требовать, чтобы цикл событий Node.js оставался активным. Если нет другой активности, поддерживающей работу цикла событий, процесс может завершиться до вызова обратного вызова объекта <fs.StatWatcher>. Многократный вызов watcher.unref()
не окажет никакого эффекта.
Класс: fs.ReadStream
Добавлен в: v0.1.93
- Расширяет: <stream.Readable>
Экземпляры <fs.ReadStream> создаются и возвращаются с помощью функции fs.createReadStream()
.
Событие: 'close'
Добавлен в: v0.1.93
Генерируется, когда базовый файловый дескриптор <fs.ReadStream> закрыт.
Событие: 'open'
Добавлен в: v0.1.93
fd
<целое число> Целочисленный файловый дескриптор, используемый <fs.ReadStream>.
Генерируется, когда файловый дескриптор <fs.ReadStream> открыт.
Событие: 'ready'
Добавлен в: v9.11.0
Генерируется, когда <fs.ReadStream> готов к использованию.
Вызывается сразу после 'open'
.
readStream.bytesRead
Добавлен в: v6.4.0
Количество байтов, прочитанных на данный момент.
readStream.path
Добавлен в: v0.1.93
Путь к файлу, из которого поток читает данные, как указано в первом аргументе 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
.
Stats {
dev: 2114,
ino: 48064969,
mode: 33188,
nlink: 1,
uid: 85,
gid: 100,
rdev: 0,
size: 527,
blksize: 4096,
blocks: 8,
atimeMs: 1318289051000.1,
mtimeMs: 1318289051000.1,
ctimeMs: 1318289051000.1,
birthtimeMs: 1318289051000.1,
atime: Mon, 10 Oct 2011 23:24:11 GMT,
mtime: Mon, 10 Oct 2011 23:24:11 GMT,
ctime: Mon, 10 Oct 2011 23:24:11 GMT,
birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
Версия с bigint
:
BigIntStats {
dev: 2114n,
ino: 48064969n,
mode: 33188n,
nlink: 1n,
uid: 85n,
gid: 100n,
rdev: 0n,
size: 527n,
blksize: 4096n,
blocks: 8n,
atimeMs: 1318289051000n,
mtimeMs: 1318289051000n,
ctimeMs: 1318289051000n,
birthtimeMs: 1318289051000n,
atimeNs: 1318289051000000000n,
mtimeNs: 1318289051000000000n,
ctimeNs: 1318289051000000000n,
birthtimeNs: 1318289051000000000n,
atime: Mon, 10 Oct 2011 23:24:11 GMT,
mtime: Mon, 10 Oct 2011 23:24:11 GMT,
ctime: Mon, 10 Oct 2011 23:24:11 GMT,
birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
stats.isBlockDevice()
Добавлен в: v0.1.10
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Stats> описывает блочное устройство.
stats.isCharacterDevice()
Добавлен в: v0.1.10
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Stats> описывает символьное устройство.
stats.isDirectory()
Добавлен в: v0.1.10
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Stats> описывает каталог файловой системы.
Если объект <fs.Stats> был получен вызовом fs.lstat()
для символической ссылки, которая разрешается в каталог, этот метод вернет false
. Это связано с тем, что fs.lstat()
возвращает информацию о самой символической ссылке, а не о пути, к которому она ведет.
stats.isFIFO()
Добавлен в: v0.1.10
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Stats> описывает именованный канал FIFO (first-in-first-out).
stats.isFile()
Добавлен в: v0.1.10
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Stats> описывает обычный файл.
stats.isSocket()
Добавлен в: v0.1.10
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Stats> описывает сокет.
stats.isSymbolicLink()
Добавлен в: v0.1.10
- Возвращает: <boolean>
Возвращает true
, если объект <fs.Stats> описывает символическую ссылку.
Этот метод действителен только при использовании fs.lstat()
.
stats.dev
Цифровой идентификатор устройства, содержащего файл.
stats.ino
Уникальный номер файла в файловой системе (Inode).
stats.mode
Битовое поле, описывающее тип и режим файла.
stats.nlink
Количество жёстких ссылок на файл.
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
(т.е. метку времени эпохи Unix0
). В этом случае это значение может быть больше, чем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
.
StatFs {
type: 1397114950,
bsize: 4096,
blocks: 121938943,
bfree: 61058895,
bavail: 61058895,
files: 999,
ffree: 1000000
}
Версия с bigint
:
StatFs {
type: 1397114950n,
bsize: 4096n,
blocks: 121938943n,
bfree: 61058895n,
bavail: 61058895n,
files: 999n,
ffree: 1000000n
}
statfs.bavail
Добавлено в: v19.6.0, v18.15.0
Количество свободных блоков, доступных непривилегированным пользователям.
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
- Расширяет <stream.Writable>
Экземпляры <fs.WriteStream> создаются и возвращаются с помощью функции fs.createWriteStream()
.
Событие: 'close'
Добавлено в: v0.1.93
Генерируется, когда базовый файловый дескриптор <fs.WriteStream> закрыт.
Событие: 'open'
Добавлено в: v0.1.93
fd
<integer> Целочисленный файловый дескриптор, используемый <fs.WriteStream>.
Генерируется, когда файл <fs.WriteStream> открыт.
Событие: 'ready'
Добавлено в: v9.11.0
Генерируется, когда <fs.WriteStream> готов к использованию.
Выполняется сразу после 'open'
.
writeStream.bytesWritten
Добавлено в: v0.4.7
Количество записанных байтов. Не включает данные, которые всё ещё находятся в очереди на запись.
writeStream.close([callback])
Добавлено в: v0.9.4
callback
<Function>err
<Error>
Закрывает writeStream
. Необязательно принимает обратный вызов, который будет выполнен после закрытия writeStream
.
writeStream.path
Добавлено в: v0.1.93
Путь к файлу, в который записывает поток, как указано в первом аргументе fs.createWriteStream()
. Если path
передаётся как строка, то writeStream.path
будет строкой. Если path
передаётся как <Buffer>, то writeStream.path
будет <Buffer>.
writeStream.pending
Добавлено в: v11.2.0
Это свойство имеет значение true
, если базовый файл ещё не открыт, т.е. до того, как будет отправлено событие 'ready'
.
fs.constants
Возвращает объект, содержащий часто используемые константы для операций файловой системы.
Константы FS
Следующие константы экспортируются fs.constants
и fsPromises.constants
.
Не все константы будут доступны в каждой операционной системе; это особенно важно для Windows, где многие определения, специфичные для POSIX, недоступны. Для переносимых приложений рекомендуется проверять их наличие перед использованием.
Чтобы использовать более одной константы, используйте побитовую операцию ИЛИ |
.
Пример:
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()
:
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)}`)
})
Важно правильно упорядочить операции, ожидая результатов одной перед вызовом другой:
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)
}
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()
:
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)}`)
})
})
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:
import { open } from 'node:fs/promises'
let fd
try {
fd = await open('/open/some/file.txt', 'r')
// Выполните какие-либо действия с файлом
} finally {
await fd?.close()
}
Пример использования относительного пути в POSIX (относительно process.cwd()
):
import { open } from 'node:fs/promises'
let fd
try {
fd = await open('file.txt', 'r')
// Выполните какие-либо действия с файлом
} finally {
await fd?.close()
}
Пути к файлам URL
Добавлено в: v7.6.0
Для большинства функций модуля node:fs
аргумент path
или filename
может быть передан как объект <URL> с использованием протокола file:
.
import { readFileSync } from 'node:fs'
readFileSync(new URL('file:///tmp/hello'))
URL file:
всегда представляют собой абсолютные пути.
Особенности разных платформ
В Windows URL file:
<URL> с именем узла преобразуются в пути UNC, а URL file:
<URL> с буквой диска преобразуются в локальные абсолютные пути. URL file:
<URL> без имени узла и буквы диска приведут к ошибке:
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> с именем узла не поддерживаются и приведут к ошибке:
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> с закодированными символами слэша приведут к ошибке на всех платформах:
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> с закодированным обратным слэшем приведут к ошибке:
import { readFileSync } from 'node:fs'
// В Windows
readFileSync(new URL('file:///C:/path/%5C'))
readFileSync(new URL('file:///C:/path/%5c'))
/* TypeError [ERR_INVALID_FILE_URL_PATH]: Путь URL файла не должен содержать закодированные
символы \ или / */
Пути в виде буферов
Пути, указанные с использованием <Buffer>, в основном полезны в некоторых POSIX-операционных системах, которые рассматривают пути к файлам как непрозрачные байтовые последовательности. В таких системах один путь к файлу может содержать подпоследовательности, использующие несколько кодировок символов. Как и в случае с текстовыми путями, пути <Buffer> могут быть относительными или абсолютными:
Пример использования абсолютного пути в POSIX:
import { open } from 'node:fs/promises'
import { Buffer } from 'node:buffer'
let fd
try {
fd = await open(Buffer.from('/open/some/file.txt'), 'r')
// Выполните действия с файлом
} finally {
await fd?.close()
}
Рабочие каталоги на каждый диск в Windows
В Windows Node.js следует концепции рабочего каталога для каждого диска. Это поведение можно наблюдать при использовании пути к диску без обратной косой черты. Например, fs.readdirSync('C:\\')
может возвращать другой результат, чем fs.readdirSync('C:')
. Для получения дополнительной информации см. эту страницу MSDN.
Дескрипторы файлов
В POSIX-системах ядро для каждого процесса поддерживает таблицу текущих открытых файлов и ресурсов. Каждому открытому файлу присваивается простой числовой идентификатор, называемый дескриптором файла. На системном уровне все операции файловой системы используют эти дескрипторы файлов для идентификации и отслеживания каждого конкретного файла. Системы Windows используют другой, но концептуально похожий механизм для отслеживания ресурсов. Для упрощения работы пользователей Node.js абстрагирует различия между операционными системами и присваивает всем открытым файлам числовой дескриптор файла.
Методы fs.open()
, основанные на обратных вызовах, и синхронные методы fs.openSync()
открывают файл и выделяют новый дескриптор файла. После выделения дескриптор файла может использоваться для чтения данных из файла, записи данных в файл или запроса информации о файле.
Операционные системы ограничивают количество дескрипторов файлов, которые могут быть открыты в любой момент времени, поэтому крайне важно закрыть дескриптор после завершения операций. В противном случае произойдет утечка памяти, которая в конечном итоге приведет к сбою приложения.
import { open, close, fstat } from 'node:fs'
function closeFd(fd) {
close(fd, err => {
if (err) throw err
})
}
open('/open/some/file.txt', 'r', (err, fd) => {
if (err) throw err
try {
fstat(fd, (err, stat) => {
if (err) {
closeFd(fd)
throw err
}
// используйте stat
closeFd(fd)
})
} catch (err) {
closeFd(fd)
throw err
}
})
API на основе промисов используют объект <FileHandle> вместо числового дескриптора файла. Эти объекты лучше управляются системой, чтобы гарантировать, что ресурсы не будут потеряны. Однако по-прежнему необходимо закрывать их после завершения операций:
import { open } from 'node:fs/promises'
let file
try {
file = await open('/open/some/file.txt', 'r')
const stat = await file.stat()
// используйте stat
} finally {
await file.close()
}
Использование пула потоков
Все коллбэки и 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
.
// 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()
.