Многопоточная сборка

Статья обновлена 4 сентября 2026 г.

Сборщик умеет обрабатывать страницы документации параллельно, в нескольких потоках. Это ускоряет сборку больших проектов: обработка страниц - самая долгая часть сборки и она упирается в процессор.

По умолчанию режим выключен: сборка идёт в один поток.

Как включить

Передайте ключ --jobs:

# 4 рабочих потока
yfm build -i ./input-folder -o ./output-folder --jobs 4

# число потоков выберется автоматически: количество ядер минус один
yfm build -i ./input-folder -o ./output-folder -j

Значение 1 и меньше равносильно выключенному режиму: рабочие потоки не запускаются.

Сколько потоков указывать:

на своей машине подойдёт -j без числа;
в CI ориентируйтесь на число доступных агенту ядер, а не на число ядер физической машины: в контейнере с двумя ядрами восемь потоков только замедлят сборку;
на проекте в несколько десятков страниц многопоточность может не окупиться - запуск потоков сам по себе занимает время.

Что ускоряется, а что нет

Параллельно выполняется обработка отдельных страниц: разбор YFM, подстановка переменных, вставки, рендеринг в конечный файл.

Последовательно, в один поток, выполняется всё остальное:

подготовка проекта и разбор оглавлений;
сбор поискового индекса;
одностраничная сборка и генерация PDF;
запись манифестов, редиректов и карты файлов.

Поэтому ускорение не линейно числу потоков: на проекте с тяжёлым оглавлением и большим поисковым индексом выигрыш будет скромнее, чем на проекте из множества простых страниц.

Расход памяти

Каждый рабочий поток держит собственную копию данных проекта, поэтому расход памяти растёт вместе с числом потоков. Если сборка падает по нехватке памяти, уменьшите число потоков или ограничьте каждый поток ключом --worker-max-old-space:

yfm build -i ./input-folder -o ./output-folder --jobs 4 --worker-max-old-space 2048

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

Ограничения

Watch-режим работает в один поток. Первая сборка может идти в несколько потоков, но после перехода в режим слежения потоки останавливаются, и пересборки выполняются последовательно.
Порядок записи файлов не определён. В однопоточной сборке страницы обрабатываются в предсказуемом порядке, в многопоточной - нет. На результат сборки это не влияет, но порядок строк в логах от запуска к запуску будет разным.
Сторонние расширения могут быть к этому не готовы. Расширение выполняется внутри рабочих потоков, и не всякая логика переживает такой запуск. Если после включения --jobs расширение перестало работать, сравните результат с однопоточной сборкой и загляните в статью Многопоточность и хуки.

Если что-то пошло не так

Сравните сборку с --jobs и без него: если результаты отличаются, дело в многопоточности, и до выяснения причины режим лучше отключить.

Строка Threads setup timed out в логе означает, что рабочие потоки не успели запуститься за 30 секунд. Сборка при этом не падает - она молча продолжается в один поток. Обычно это признак нехватки ресурсов на машине сборки.