fs и fs-promises - синхронные и асинхронные операции
На этой странице
fs - встроенный модуль Node.js для работы с файловой системой: файлами, папками, правами, метаданными и потоками чтения/записи. fs/promises - promise-версия этого API, которую удобно использовать вместе с async/await.
Синхронные операции fs блокируют выполнение JavaScript до завершения работы с диском. Асинхронные операции отдают задачу Node.js и позволяют event loop продолжать обрабатывать другие события.
Вопрос
Что такое fs и fs/promises и чем синхронные операции отличаются от асинхронных?
Главное определение
В браузере JavaScript не имеет прямого доступа к диску пользователя. В Node.js такой доступ есть через модуль node:fs.
У fs есть несколько стилей API:
| Стиль | Пример | Когда использовать |
|---|---|---|
| Callback API | fs.readFile(path, cb) | В старом коде и библиотеках |
| Promise API | await fs.readFile(path) из node:fs/promises | В современном приложении |
| Sync API | fs.readFileSync(path) | В CLI, скриптах и при старте приложения |
| Stream API | fs.createReadStream(path) | Для больших файлов |
Пример чтения файла
import { readFile } from 'node:fs/promises';
const text = await readFile('notes.txt', 'utf8');
console.log(text);Если не указать 'utf8', Node вернет Buffer, а не строку.
const data = await readFile('image.png');
console.log(Buffer.isBuffer(data)); // trueПочему лучше начинать с fs/promises?
fs/promises проще читать, легче комбинируется с try/catch и не создает вложенность callback-функций.
import { writeFile } from 'node:fs/promises';
try {
await writeFile('result.txt', 'Готово', 'utf8');
console.log('Файл записан');
} catch (error) {
console.error('Не удалось записать файл:', error.message);
}Sync и async: что блокирует event loop
В Node.js один основной поток выполняет JavaScript-код. Если вызвать синхронную операцию, этот поток будет ждать диск.
import { readFileSync } from 'node:fs';
const config = readFileSync('config.json', 'utf8');
console.log(config);Пока файл читается, сервер не сможет обрабатывать новые запросы.
Асинхронная версия не блокирует основной поток:
import { readFile } from 'node:fs/promises';
const config = await readFile('config.json', 'utf8');
console.log(config);await приостанавливает текущую async-функцию, но не весь Node.js-процесс.
Когда sync API допустим?
Синхронные операции нормальны, если код выполняется редко и не обслуживает пользователей прямо сейчас:
- чтение конфига при запуске;
- одноразовый скрипт миграции;
- CLI-утилита;
- генерация файлов в build step.
На HTTP-сервере в обработчике запроса sync API обычно считается плохой практикой.
import { readFileSync } from 'node:fs';
import http from 'node:http';
http.createServer((req, res) => {
const page = readFileSync('index.html', 'utf8'); // блокирует все запросы
res.end(page);
});Собеседовательный нюанс
Асинхронность в fs не означает, что файл читается самим JavaScript. Node.js использует возможности ОС и libuv, а часть операций может выполняться через thread pool.
Что важно помнить
- Sync-методы блокируют event loop — в обработчиках запросов их не используют.
readFileчитает файл целиком в память; для больших файлов нужны streams.- Ошибки
fsсодержатcode:ENOENT(нет файла),EACCES(нет прав),EEXIST. mkdir(path, { recursive: true })иrm(path, { recursive: true, force: true })удобны для работы с папками.
Мини-шпаргалка
node:fs- базовый модуль файловой системы.node:fs/promises- современный promise-интерфейс.readFileчитает файл целиком в память.writeFileсоздает или перезаписывает файл.- Для больших файлов лучше использовать streams.
SyncAPI блокирует event loop.- Async API лучше для серверов.
- Sync API допустим при старте приложения и в простых скриптах.
awaitне блокирует весь процесс.- В обработчиках HTTP-запросов избегай
readFileSync.