Опция logLimit

Параметр logLimit в esbuild управляет количеством сообщений логирования, которые будут выведены для каждой категории предупреждений или ошибок до того, как последующие сообщения начнут подавляться. Это механизм ограничения «шумных» логов, возникающих при массовых однотипных проблемах в проекте.

Поведение и назначение

При сборке проекта esbuild может генерировать большое количество предупреждений одного типа, например:

  • неразрешённые импорты,
  • устаревшие синтаксические конструкции,
  • дублирующиеся предупреждения о пакетах,
  • повторяющиеся сообщения плагинов.

Без ограничения лог может быстро стать нечитаемым. logLimit решает эту проблему, ограничивая число выводимых сообщений на одну категорию.

Основная идея:

  • выводится только первые N сообщений одного типа;
  • остальные подавляются;
  • в конце добавляется краткая сводка о количестве скрытых сообщений.

Поведение при превышении лимита

Когда количество сообщений превышает установленный лимит:

  1. esbuild печатает первые logLimit сообщений;
  2. дальнейшие сообщения того же типа не выводятся;
  3. добавляется агрегированное уведомление вида:
  • сколько сообщений было скрыто;
  • к какой категории они относятся.

Это позволяет сохранить информативность, не перегружая терминал или CI-логи.

Сигнатура и место в конфигурации

logLimit задаётся как числовая опция в объекте конфигурации сборки:

import * as esbuild from "esbuild";

esbuild.build({
  entryPoints: ["src/index.js"],
  bundle: true,
  outfile: "dist/bundle.js",
  logLimit: 10
});

Тип значения

logLimit принимает:

  • целое положительное число;
  • ноль (в некоторых сценариях может означать подавление всех сообщений соответствующего типа после первого агрегирования);
  • большие значения, фактически отключающие агрессивное ограничение.

Влияние на категории логов

Ограничение применяется не глобально ко всем логам сразу, а по типу сообщения. Это означает:

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

Пример:

  • 20 предупреждений о missing imports → ограничение сработает отдельно;
  • 15 предупреждений от плагина CSS → считаются независимо.

Взаимодействие с logLevel

Параметр logLimit работает совместно с logLevel, который определяет:

  • какие уровни логов вообще выводятся (info, warning, error, silent);
  • в то время как logLimit регулирует объём уже разрешённых сообщений.

Логика взаимодействия:

  1. logLevel фильтрует типы сообщений;
  2. logLimit ограничивает количество оставшихся сообщений по категориям.

Практическое поведение в типичных сценариях

CI/CD пайплайны

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

Без logLimit лог может занимать тысячи строк.

С logLimit:

  • вывод остаётся компактным;
  • сохраняется информация о наличии массовой проблемы;
  • пайплайн не захламляется повторениями.

Разработка в режиме watch

При активной разработке esbuild --watch может многократно пересобирать проект и повторно генерировать одни и те же предупреждения.

logLimit предотвращает:

  • повторяющийся спам одинаковых сообщений при каждом триггере;
  • перегрузку терминала.

Пример с большим количеством предупреждений

esbuild.build({
  entryPoints: ["src/index.js"],
  bundle: true,
  outfile: "dist/app.js",
  logLimit: 5
});

Если один модуль вызывает 20 одинаковых предупреждений:

  • будут показаны только первые 5;
  • оставшиеся 15 будут скрыты;
  • появится сообщение о количестве подавленных предупреждений.

Использование в связке с плагинами

Плагины esbuild часто генерируют логи через API контекста сборки. При интенсивной работе плагинов:

  • один и тот же плагин может сообщать одинаковую проблему для множества файлов;
  • logLimit предотвращает лавинообразный вывод одинаковых сообщений.

Ограничения и особенности

  • не влияет на структурные ошибки сборки, приводящие к её остановке;
  • не изменяет фактическое количество ошибок — только их отображение;
  • не объединяет уникальные сообщения, только подавляет повторения;
  • не гарантирует глобальную уникальность логов, так как применяется по категориям.

Практическая настройка значений

Выбор значения зависит от характера проекта:

  • маленькие проекты: 5–10 достаточно;
  • средние приложения: 10–20;
  • крупные монорепозитории: 20–50;
  • отладка плагинов: увеличение или временное отключение ограничения.

Поведение при отсутствии явной настройки

Если logLimit не указан, используется встроенное значение по умолчанию, рассчитанное на баланс между информативностью и шумом логов в типичных сценариях сборки.

Оглавление