Опция logOverride: управление уровнем конкретных сообщений

В стандартном режиме сборщик формирует единый поток логов, управляемый глобальной настройкой logLevel. Это удобно для общего контроля вывода, но недостаточно гибко, когда требуется тонко регулировать поведение отдельных типов сообщений: часть предупреждений может быть критичной в одном проекте и полностью шумовой в другом.

Опция logOverride вводит механизм точечной переоценки уровня логирования для конкретных сообщений. Она работает поверх глобального logLevel и позволяет переопределять поведение отдельных категорий логов без изменения общей конфигурации сборки.

Модель логирования и место logOverride в ней

Система логов в esbuild устроена иерархически:

  • глобальный уровень (logLevel)
  • категории сообщений (warnings, errors, info, verbose)
  • конкретные типы сообщений (message kinds)

logOverride вмешивается на последнем уровне, перезаписывая поведение отдельных типов сообщений.

Если глобально задано:

logLevel: "warning"

то по умолчанию:

  • предупреждения показываются
  • информационные сообщения скрыты

Но при этом logOverride может включить или выключить конкретные предупреждения независимо от этого правила.

Синтаксис и структура logOverride

Опция задаётся как объект, где ключ — тип сообщения, а значение — уровень логирования.

logOverride: {
  "this-is-a-message-type": "silent",
  "another-message-type": "error",
  "some-warning-type": "info"
}

Допустимые значения уровней:

  • silent — полностью скрыть сообщение
  • info — показать как информационное
  • warning — показать как предупреждение
  • error — интерпретировать как ошибку

Типы сообщений и их идентификаторы

Каждое сообщение в esbuild имеет внутренний идентификатор (message kind). Он определяет источник и смысл сообщения.

Примеры категорий, которые могут встречаться:

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

Эти идентификаторы стабильны в рамках major-версий, что позволяет использовать logOverride как инструмент долгосрочной настройки поведения сборки.

Приоритеты: logLevel против logOverride

Поведение определяется следующим порядком:

  1. Проверяется конкретный logOverride для типа сообщения
  2. Если нет переопределения — применяется глобальный logLevel

Это означает, что logOverride всегда имеет более высокий приоритет.

Пример:

{
  logLevel: "warning",
  logOverride: {
    "package.json": "silent"
  }
}

Даже если сообщение относится к предупреждениям, оно будет скрыто.

Практические сценарии использования

Подавление шумных предупреждений

В монорепозиториях часто встречаются повторяющиеся предупреждения о пакетных конфигурациях.

logOverride: {
  "package.json": "silent"
}

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

Усиление отдельных сигналов

Иногда информационные сообщения важно поднять до уровня предупреждений.

logOverride: {
  "unsupported-bare-import": "warning"
}

Это полезно при постепенной миграции старого кода.

Превращение предупреждений в ошибки

Для строгих CI-сборок часть предупреждений переводится в ошибки:

logOverride: {
  "css-syntax-error": "error"
}

Такой режим позволяет остановить сборку при появлении некорректных CSS-вставок.

Полное отключение специфических событий

Некоторые сообщения носят исключительно информационный характер и не влияют на результат сборки:

logOverride: {
  "metafile-generated": "silent"
}

Используется для уменьшения объёма логов в автоматизированных системах.

Влияние на CI/CD и автоматические пайплайны

В сборочных системах logOverride становится инструментом управления сигналами качества кода.

Типичные стратегии:

  • строгий режим: все важные предупреждения → error
  • стабильный режим: шумные сообщения → silent
  • диагностический режим: всё → info

Пример строгой конфигурации:

{
  logLevel: "warning",
  logOverride: {
    "unused-variable": "error",
    "deprecated-api": "error",
    "css-syntax-error": "error"
  }
}

Такой подход превращает часть предупреждений в формальные блокирующие условия.

Взаимодействие с другими лог-опциями

logLevel

logLevel задаёт базовую политику вывода. Без logOverride он определяет всё поведение логов.

logLimit

Ограничивает количество сообщений. Даже при активном logOverride сообщения могут быть обрезаны по количеству.

metafile и аналитические данные

Некоторые сообщения, связанные с metafile, могут переопределяться через logOverride, но не влияют на структуру самого файла метаданных.

Особенности применения в больших проектах

В крупных приложениях на esbuild количество предупреждений может расти нелинейно. Основная проблема — деградация сигнала: полезные сообщения теряются в потоке второстепенных.

logOverride решает эту проблему за счёт:

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

Конфигурационные паттерны

Базовый шаблон

export default {
  logLevel: "warning",
  logOverride: {
    "package.json": "silent"
  }
}

Строгая проверка качества кода

export default {
  logLevel: "info",
  logOverride: {
    "unused-import": "error",
    "missing-export": "error",
    "css-syntax-error": "error"
  }
}

Минимизация вывода

export default {
  logLevel: "error",
  logOverride: {
    "bundle-size": "silent",
    "rebuild": "silent"
  }
}

Ограничения механизма

  • работает только с известными типами сообщений
  • не влияет на пользовательские onEnd/onStart callbacks
  • не заменяет глобальную стратегию логирования
  • требует знания конкретных message kinds для точной настройки

Роль в архитектуре сборки

logOverride фактически превращает систему логов в настраиваемую матрицу приоритетов, где каждый тип сообщения получает собственный уровень важности. Это позволяет адаптировать поведение сборщика под разные контексты: разработка, тестирование, CI, production-сборка.

Оглавление