Веб-сервер записывает каждый запрос в лог-файл. Через месяц файл весит 2 ГБ. Если открыть его через readFile, Node.js попытается загрузить в память все 2 ГБ сразу — программа замедлится или упадёт. В уроке «Основы Node.js» мы сохраняли заметки через readFile и writeFile; для маленьких файлов это правильно. В этом уроке вы освоите весь набор fs/promises, пути, работающие в любой системе, коды ошибок и потоки: поток обрабатывает данные по частям, поэтому даже файл в 2 ГБ в каждый момент занимает в памяти лишь несколько десятков килобайт.
fs/promises: чтение и запись файлов
Модуль node:fs/promises даёт версии файловых функций, возвращающие промисы, поэтому мы вызываем их с await (см. «Асинхронный JavaScript: колбэки, промисы, async/await»). Чаще всего нужны три: writeFile(путь, данные) создаёт файл или полностью заменяет его содержимое, appendFile дописывает в конец, а readFile(путь, 'utf8') возвращает содержимое строкой. Без кодировки ('utf8') readFile возвращает Buffer — сырые байты.
BufferОпределение
Тип Node.js для сырых двоичных данных: последовательность байтов (0–255) фиксированной длины. Файлы, сетевые пакеты и картинки приходят как Buffer; buffer.toString('utf8') превращает байты в текст, а Buffer.from(текст) — текст в байты.
// files.mjs
import { writeFile, appendFile, readFile } from 'node:fs/promises';
await writeFile('greeting.txt', 'Salam, dünya!\n');
await appendFile('greeting.txt', 'Hello, world!\n');
const text = await readFile('greeting.txt', 'utf8');
console.log(JSON.stringify(text));
console.log('characters:', text.length);
const bytes = await readFile('greeting.txt');
console.log('bytes:', bytes.length);
console.log(bytes.subarray(0, 10));
console.log(bytes.subarray(0, 10).toString('utf8'));
console.log(bytes.subarray(0, 9).toString('utf8'));Ожидаемый результат
"Salam, dünya!\nHello, world!\n" characters: 28 bytes: 29 <Buffer 53 61 6c 61 6d 2c 20 64 c3 bc> Salam, dü Salam, d�
node files.mjs в пустой папке. В UTF-8 буква ü занимает 2 байта, поэтому в файле 28 символов, но 29 байт. Если обрезать байты после 9-го, ü разрезается пополам, и обломок показывается как �.У каждой функции есть и синхронный близнец в node:fs: readFileSync, writeFileSync. Они блокируют цикл событий, пока диск не ответит. В коротком скрипте или при запуске программы это не страшно, а на сервере одно медленное чтение замораживает всех пользователей (см. «Цикл событий и конкурентность»). В старом коде встретится и стиль с колбэками: fs.readFile(путь, (err, data) => …).
| Функция | Что делает | Заметка |
|---|---|---|
readFile(p, 'utf8') | читает весь файл | без кодировки — Buffer |
writeFile(p, data) | создаёт или перезаписывает | { flag: 'wx' } — EEXIST, если файл есть |
appendFile(p, data) | дописывает в конец | создаёт файл, если его нет |
mkdir(p, { recursive: true }) | создаёт папку со всеми родителями | нет ошибки, если папка есть |
readdir(p, { withFileTypes: true }) | список содержимого папки | объекты Dirent с isFile(), isDirectory() |
stat(p) | сведения о файле | size, mtime, isFile() |
rm(p, { recursive: true, force: true }) | удаляет файл или всё дерево | отменить нельзя! |
Чтобы читать дальше, зарегистрируйся бесплатно
Остальные разделы урока, тест и заметки открываются с аккаунтом Educora. Регистрация занимает минуту, а прогресс сохраняется на всех твоих устройствах.
Папки, сведения о файлах и коды ошибок
Когда файловая операция не удаётся, Node.js выбрасывает ошибку с коротким кодом. Проверяйте error.code, а не сообщение: сообщения могут меняться, коды — нет. Самые частые: ENOENT — нет такого файла или папки; EEXIST — уже существует; EACCES и EPERM — нет прав; EISDIR — вместо файла передана папка; ENOTEMPTY — папка не пуста.
// folders.mjs
import { mkdtemp, mkdir, writeFile, readdir, stat, readFile, rm } from 'node:fs/promises';
import path from 'node:path';
import os from 'node:os';
const root = await mkdtemp(path.join(os.tmpdir(), 'demo-'));
await mkdir(path.join(root, 'reports', '2026'), { recursive: true });
await writeFile(path.join(root, 'notes.txt'), 'buy bread');
await writeFile(path.join(root, 'reports', '2026', 'oct.csv'), 'day,sales\n1,40\n');
for (const entry of await readdir(root, { withFileTypes: true })) {
const info = await stat(path.join(root, entry.name));
console.log(info.isFile() ? `${entry.name} (${info.size} B)` : `${entry.name}/`);
}
try {
await readFile(path.join(root, 'missing.txt'), 'utf8');
} catch (error) {
console.log(error.code, error.syscall);
}
try {
await mkdir(path.join(root, 'reports'));
} catch (error) {
console.log(error.code, error.syscall);
}
await rm(root, { recursive: true, force: true });
await stat(root).catch((error) => console.log('after rm:', error.code));Ожидаемый результат
notes.txt (9 B) reports/ ENOENT open EEXIST mkdir after rm: ENOENT
mkdtemp создаёт уникальную папку (например, demo-a1B2c3) во временной папке системы, поэтому пример не трогает ваши файлы. { recursive: true } создал и reports, и 2026 одним вызовом. В конце rm удаляет всё дерево, а stat подтверждает это кодом ENOENT.Пути: node:path и import.meta.dirname
Windows разделяет папки символом \, Linux и macOS — символом /. path.join ставит правильный разделитель и убирает части .. и лишние разделители. basename, extname и dirname режут путь на части, path.parse возвращает все части сразу, а path.relative показывает, как пройти от одного пути к другому.
// paths.mjs
import path from 'node:path';
const file = path.join('data', 'logs', '..', 'reports', 'oct.csv');
console.log(file);
console.log(path.basename(file), path.extname(file), path.basename(file, '.csv'));
console.log(path.dirname(file));
console.log(path.parse('/srv/app/server.mjs'));
console.log(path.isAbsolute('data/oct.csv'), path.isAbsolute('/srv/app'));
console.log(path.relative('/srv/app', '/srv/app/public/index.html'));
console.log(import.meta.dirname === path.dirname(import.meta.filename));Ожидаемый результат
data\reports\oct.csv
oct.csv .csv oct
data\reports
{
root: '/',
dir: '/srv/app',
base: 'server.mjs',
ext: '.mjs',
name: 'server'
}
false true
public\index.html
truedata/reports/oct.csv, а path.relative даёт public/index.html. Последняя строка: import.meta.dirname — это папка самого файла.Самое важное: относительный путь вроде 'data.json' отсчитывается не от папки скрипта, а от process.cwd() — папки, из которой запущен node. Один и тот же скрипт находит файл при запуске из одной папки и падает с ENOENT из другой. Пути к файлам рядом со скриптом стройте от его собственной папки: path.join(import.meta.dirname, 'data.json'). import.meta.dirname и import.meta.filename есть в ES-модулях начиная с Node.js 20.11; в CommonJS это __dirname и __filename.
| Как запущен | process.cwd() | path.resolve('data.json') | path.join(import.meta.dirname, 'data.json') |
|---|---|---|---|
cd app && node scripts/report.mjs | app | app/data.json | app/scripts/data.json |
cd app/scripts && node report.mjs | app/scripts | app/scripts/data.json | app/scripts/data.json |
app/scripts/report.mjs, запущенный из двух разных папок (пути сокращены). Неизменным остаётся только последний столбец.Потоки: данные по частям
readFile загружает всё сразу. Поток (stream) отдаёт данные кусками (chunk): поток чтения файла выдаёт по 64 КиБ, вы обрабатываете кусок и забываете его, и потребление памяти остаётся маленьким и постоянным при любом размере файла. В Node.js потоки повсюду: файлы, HTTP-запросы и ответы, process.stdin, сжатие.
| Вид | Смысл | Примеры |
|---|---|---|
| Readable | из него читают | fs.createReadStream, process.stdin, HTTP request |
| Writable | в него пишут | fs.createWriteStream, process.stdout, HTTP response |
| Transform | изменяет проходящие данные | zlib.createGzip() |
| Duplex | в обе стороны | сетевой сокет |
Поток чтения — это эмиттер событий (подробнее в «Node.js: события, процесс и инструменты командной строки»): он генерирует data для каждого куска, end, когда данные закончились, и error при сбое. Его можно читать и через for await (const chunk of stream) — часто так проще.
// chunks.mjs
import { createReadStream } from 'node:fs';
import { writeFile } from 'node:fs/promises';
await writeFile('big.txt', 'x'.repeat(1_000_000));
const stream = createReadStream('big.txt');
console.log('chunk size limit:', stream.readableHighWaterMark);
let chunks = 0;
let bytes = 0;
stream.on('data', (chunk) => {
chunks++;
bytes += chunk.length;
});
stream.on('end', () => console.log(`end: ${chunks} chunks, ${bytes} bytes`));
stream.on('error', (error) => console.log('error:', error.code));
const missing = createReadStream('no-such-file.txt');
missing.on('error', (error) => console.log('error:', error.code));Ожидаемый результат
chunk size limit: 65536 error: ENOENT end: 16 chunks, 1000000 bytes
error для отсутствующего файла пришло раньше: оба потока работают одновременно, а неудачное открытие выясняется быстрее, чем 16 чтений. Без слушателя error эта ошибка уронила бы программу.У записи обратная проблема. write() кладёт данные в буфер потока и возвращает false, когда буфер полон (для файлов по умолчанию 16 КиБ): диск медленнее вашего цикла. Если продолжать писать, память растёт — это называется игнорировать backpressure (обратное давление). Решение: когда write() вернул false, дождитесь события drain.
// write-log.mjs
import { createWriteStream } from 'node:fs';
import { once } from 'node:events';
const out = createWriteStream('access.log');
let waits = 0;
for (let i = 1; i <= 100_000; i++) {
const level = i % 25 === 0 ? 'ERROR' : 'INFO';
const ok = out.write(`2026-10-03 ${level} GET /api/items/${i % 40}\n`);
if (!ok) {
waits++;
await once(out, 'drain');
}
}
out.end();
await once(out, 'finish');
console.log('bytes written:', out.bytesWritten);
console.log('waited for drain:', waits, 'times');Ожидаемый результат
bytes written: 3379000 waited for drain: 206 times
once(out, 'finish') выполняется, когда все данные записаны на диск.Соединять потоки вручную — источник ошибок: если упал средний поток, остальные тоже нужно закрыть. pipeline из node:stream/promises соединяет любое число потоков, сам учитывает backpressure, при ошибке закрывает их все и возвращает промис. Шагом может быть и генератор async function*: он получает предыдущий поток и отдаёт куски через yield — самый простой способ написать своё преобразование.
// gzip.mjs
import { createReadStream, createWriteStream } from 'node:fs';
import { stat } from 'node:fs/promises';
import { pipeline } from 'node:stream/promises';
import { createGzip } from 'node:zlib';
let passed = 0;
async function* countBytes(source) {
for await (const chunk of source) {
passed += chunk.length;
yield chunk;
}
}
await pipeline(
createReadStream('access.log'),
countBytes,
createGzip(),
createWriteStream('access.log.gz'),
);
const { size } = await stat('access.log.gz');
console.log(`read ${passed} bytes, wrote ${size} bytes`);
console.log(`compressed to ${(size / passed * 100).toFixed(1)}%`);
await pipeline(createReadStream('missing.log'), createGzip(), createWriteStream('x.gz'))
.catch((error) => console.log('pipeline failed:', error.code));Ожидаемый результат
read 3379000 bytes, wrote 27272 bytes compressed to 0.8% pipeline failed: ENOENT
pipeline отклоняется с ENOENT и закрывает остальные потоки, но createWriteStream уже создал пустой x.gz — в настоящем коде удаляйте недоделанный файл.Большой файл построчно: проект сводки по логу
Логи, выгрузки CSV и файлы JSON Lines обрабатывают построчно. Куски не считаются со строками: кусок может закончиться посреди строки. Модуль node:readline собирает части и отдаёт целые строки; с for await цикл читает следующую строку, только когда вы готовы. crlfDelay: Infinity считает концы строк Windows (\r\n) одним переводом строки.
Временная папка
Создайте уникальную папку через
mkdtemp, чтобы проект не трогал ваши файлы.Пример лога
Запишите туда несколько строк формата
время уровень метод путь статус длительность.Статистика построчно
Читайте через
readlineи ведите счётчики: число строк, уровни, среднее время, самый медленный запрос, самый частый путь.Отчёт и уборка
Сохраните результат в JSON, а папку удалите в блоке
finally— даже если какой-то шаг упал.
// summarize.mjs
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
export async function summarize(file) {
const lines = createInterface({ input: createReadStream(file), crlfDelay: Infinity });
const levels = {};
const paths = new Map();
let total = 0;
let totalMs = 0;
let slowest = { ms: 0, request: '' };
for await (const line of lines) {
if (!line.trim()) continue;
const [, level, method, url, , duration] = line.split(' ');
const ms = parseInt(duration, 10);
total++;
totalMs += ms;
levels[level] = (levels[level] ?? 0) + 1;
paths.set(url, (paths.get(url) ?? 0) + 1);
if (ms > slowest.ms) slowest = { ms, request: `${method} ${url}` };
}
const [topPath] = [...paths].sort((a, b) => b[1] - a[1]);
return { total, levels, avgMs: Math.round(totalMs / total), slowest, topPath };
}line.split(' ') даёт [время, уровень, метод, url, статус, длительность]; пустые места в деструктуризации пропускают время и статус. parseInt('35ms', 10) читает число и останавливается на m. В памяти лишь одна строка и счётчики — файл может весить гигабайты.// report.mjs
import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
import path from 'node:path';
import os from 'node:os';
import { summarize } from './summarize.mjs';
const dir = await mkdtemp(path.join(os.tmpdir(), 'logs-'));
try {
const logFile = path.join(dir, 'app.log');
await writeFile(logFile, [
'2026-10-03T09:00:01Z INFO GET /api/products 200 35ms',
'2026-10-03T09:00:02Z INFO GET /api/products 200 41ms',
'2026-10-03T09:00:04Z WARN POST /api/orders 400 12ms',
'2026-10-03T09:00:05Z INFO GET /api/users/7 200 28ms',
'2026-10-03T09:00:09Z ERROR POST /api/orders 500 1203ms',
'2026-10-03T09:00:12Z INFO GET /api/products 200 37ms',
'',
].join('\n'));
const report = await summarize(logFile);
await writeFile(path.join(dir, 'report.json'), JSON.stringify(report, null, 2));
console.log(await readFile(path.join(dir, 'report.json'), 'utf8'));
} finally {
await rm(dir, { recursive: true, force: true });
}Ожидаемый результат
{
"total": 6,
"levels": {
"INFO": 4,
"WARN": 1,
"ERROR": 1
},
"avgMs": 226,
"slowest": {
"ms": 1203,
"request": "POST /api/orders"
},
"topPath": [
"/api/products",
3
]
}finally удаляет временную папку, даже если summarize выбросит ошибку.Задание
Поток режет текст на куски, не глядя на строки. Напишите генератор splitLines(chunks): незаконченный конец куска он хранит в rest, приклеивает к следующему куску и отдаёт через yield только целые строки; оставшийся в конце кусок тоже отдаётся. Именно это readline делает внутри.
const chunks = ['INFO sta', 'rt\nERROR db do', 'wn\nINFO ok\nWA', 'RN slow disk'];
function* splitLines(chunks) {
let rest = '';
// glue rest + chunk, split by '\n', keep the last part in rest
}
let n = 0;
for (const line of splitLines(chunks)) {
n++;
console.log(`${n}: ${line}`);
}Ожидаемый результат
1: INFO start 2: ERROR db down 3: INFO ok 4: WARN slow disk
Задание
Проверим логику сводки без файла. countLevels(lines) возвращает объект с числом строк каждого уровня, а slowRequests(lines, limitMs) — запросы дольше limitMs в виде строк МЕТОД /путь. Пустые строки пропускайте.
const log = [
'09:00:01 INFO GET /api/products 35ms',
'09:00:04 WARN POST /api/orders 12ms',
'09:00:09 ERROR POST /api/orders 1203ms',
'',
'09:00:12 INFO GET /api/products 37ms',
];
function countLevels(lines) {
// { INFO: 2, ... }
}
function slowRequests(lines, limitMs) {
// ['POST /api/orders', ...]
}
console.log(JSON.stringify(countLevels(log)));
console.log(slowRequests(log, 100));
console.log(slowRequests(log, 30).length);Ожидаемый результат
{"INFO":2,"WARN":1,"ERROR":1}
[ 'POST /api/orders' ]
3Запомни
fs/promises+await:readFile,writeFile(перезаписывает),appendFile,mkdir({ recursive: true }),readdir,stat,rm; без кодировкиreadFileвозвращает Buffer.- Различайте ошибки по
error.code:ENOENT,EEXIST,EACCES,EISDIR. Не проверяйте заранее — делайте и ловите. - Стройте пути через
path.joinиimport.meta.dirname; относительный путь зависит отprocess.cwd(). - Поток отдаёт данные кусками (64 КиБ при чтении файла), и памяти нужно мало; если
write()вернулfalse, ждитеdrain. - Соединяйте потоки через
pipeline(ошибки и backpressure учтены), а большие текстовые файлы читайте построчно черезreadline+for await.