Node.js: файловая система и потоки

Работа с файлами в Node.js: `fs/promises` для чтения, записи и папок, переносимые пути через `node:path`, коды ошибок вроде `ENOENT` и потоки — `pipeline`, gzip и построчное чтение большого лога через `readline`.

  • Продвинутый
  • 25 мин
  • 12 вопросов
  • Урок 34 из 39

В этом уроке ты узнаешь

  • Читать, записывать и дополнять файлы, управлять папками через fs/promises и обрабатывать ошибки по их code
  • Строить переносимые пути через node:path и import.meta.dirname, а не склеивать строки
  • Объяснять, почему потоки экономят память, и безопасно соединять их через stream.pipeline
  • Построчно обрабатывать большой файл через readline и строить сводку по логу

Веб-сервер записывает каждый запрос в лог-файл. Через месяц файл весит 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(текст) — текст в байты.

JavaScript
// 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 — папка не пуста.

JavaScript
// 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 показывает, как пройти от одного пути к другому.

JavaScript
// 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
true
Вывод в Windows. В Linux и macOS первая строка — data/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.mjsappapp/data.jsonapp/scripts/data.json
cd app/scripts && node report.mjsapp/scriptsapp/scripts/data.jsonapp/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) — часто так проще.

JavaScript
// 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
1 000 000 байт = 15 полных кусков по 65 536 байт + один кусок в 16 960 байт. Событие error для отсутствующего файла пришло раньше: оба потока работают одновременно, а неудачное открытие выясняется быстрее, чем 16 чтений. Без слушателя error эта ошибка уронила бы программу.

У записи обратная проблема. write() кладёт данные в буфер потока и возвращает false, когда буфер полон (для файлов по умолчанию 16 КиБ): диск медленнее вашего цикла. Если продолжать писать, память растёт — это называется игнорировать backpressure (обратное давление). Решение: когда write() вернул false, дождитесь события drain.

JavaScript
// 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
100 000 строк, 3 379 000 байт; цикл 206 раз ждал, пока диск догонит. once(out, 'finish') выполняется, когда все данные записаны на диск.

Соединять потоки вручную — источник ошибок: если упал средний поток, остальные тоже нужно закрыть. pipeline из node:stream/promises соединяет любое число потоков, сам учитывает backpressure, при ошибке закрывает их все и возвращает промис. Шагом может быть и генератор async function*: он получает предыдущий поток и отдаёт куски через yield — самый простой способ написать своё преобразование.

JavaScript
// 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
Лог с повторяющимися словами сжался меньше чем до 1 %. Когда исходного файла нет, pipeline отклоняется с ENOENT и закрывает остальные потоки, но createWriteStream уже создал пустой x.gz — в настоящем коде удаляйте недоделанный файл.

Большой файл построчно: проект сводки по логу

Логи, выгрузки CSV и файлы JSON Lines обрабатывают построчно. Куски не считаются со строками: кусок может закончиться посреди строки. Модуль node:readline собирает части и отдаёт целые строки; с for await цикл читает следующую строку, только когда вы готовы. crlfDelay: Infinity считает концы строк Windows (\r\n) одним переводом строки.

  1. Временная папка

    Создайте уникальную папку через mkdtemp, чтобы проект не трогал ваши файлы.

  2. Пример лога

    Запишите туда несколько строк формата время уровень метод путь статус длительность.

  3. Статистика построчно

    Читайте через readline и ведите счётчики: число строк, уровни, среднее время, самый медленный запрос, самый частый путь.

  4. Отчёт и уборка

    Сохраните результат в JSON, а папку удалите в блоке finally — даже если какой-то шаг упал.

JavaScript
// 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. В памяти лишь одна строка и счётчики — файл может весить гигабайты.
JavaScript
// 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
  ]
}
Среднее: (35 + 41 + 12 + 28 + 1203 + 37) / 6 = 1356 / 6 = 226 мс. Блок finally удаляет временную папку, даже если summarize выбросит ошибку.

Задание

Поток режет текст на куски, не глядя на строки. Напишите генератор splitLines(chunks): незаконченный конец куска он хранит в rest, приклеивает к следующему куску и отдаёт через yield только целые строки; оставшийся в конце кусок тоже отдаётся. Именно это readline делает внутри.

Задание · JavaScript
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 в виде строк МЕТОД /путь. Пустые строки пропускайте.

Задание · JavaScript
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.
Заметил ошибку или неточность в уроке?

Проверь себя

Вопросов: 12. Каждый правильный ответ приносит XP.

Вопрос 1 / 12

Вопрос 1 / 12. const data = await readFile('photo.png'); — что такое data?