Опция logLevel: verbose, debug, info, warning, error, silent

В системе сборки esbuild логирование играет ключевую роль при отладке, мониторинге и интеграции в CI/CD-процессы. Опция logLevel определяет, какие сообщения будут выводиться во время выполнения сборки: от подробных диагностических данных до полного подавления вывода.

Эта настройка влияет только на стандартный вывод esbuild и не затрагивает пользовательские обработчики (onStart, onEnd) или внешние системы логирования.

Базовая структура настройки

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

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  logLevel: 'info'
});

Также применима в CLI:

esbuild src/index.js --bundle --outfile=dist/bundle.js --log-level=info

Поддерживаемые значения logLevel

verbose

Наиболее подробный уровень логирования. Используется при глубокой отладке сборки и диагностики внутренних процессов.

Содержит:

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

Характеристика уровня:

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

Пример использования:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  logLevel: 'verbose'
});

debug

Уровень, ориентированный на разработку и отладку поведения сборки.

Содержит:

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

Отличие от verbose заключается в меньшем количестве внутренних технических деталей.

Пример:

esbuild.build({
  entryPoints: ['src/app.js'],
  bundle: true,
  outfile: 'dist/app.js',
  logLevel: 'debug'
});

info

Стандартный режим вывода, используемый по умолчанию.

Содержит:

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

Особенности:

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

Пример:

esbuild.build({
  entryPoints: ['src/main.js'],
  bundle: true,
  outfile: 'dist/main.js',
  logLevel: 'info'
});

warning

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

Содержит:

  • предупреждения о потенциальных проблемах
  • сообщения о deprecated-API или некорректных практиках
  • ошибки компиляции

Не содержит:

  • информации о процессе сборки
  • статистики и промежуточных этапов

Используется для минимизации шума при стабильной сборке.

Пример:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/index.js',
  logLevel: 'warning'
});

error

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

Содержит:

  • критические ошибки сборки
  • ошибки синтаксиса
  • ошибки резолвинга модулей

Особенности:

  • минимальный объём вывода
  • подходит для production-сценариев, где важны только сбои

Пример:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/index.js',
  logLevel: 'error'
});

silent

Полное отключение встроенного логирования esbuild.

Не выводится:

  • информация о сборке
  • предупреждения
  • ошибки (в стандартный поток вывода)

Ошибки при этом не исчезают — они возвращаются через API (reject promise или callback error), но не печатаются в консоль.

Применяется в случаях:

  • интеграции с собственными системами логирования
  • тестовых окружениях
  • CI, где вывод контролируется внешними инструментами

Пример:

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/index.js',
  logLevel: 'silent'
});

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

Уровни логирования образуют иерархию:

verbose → debug → info → warning → error → silent

Каждый следующий уровень уменьшает количество выводимой информации.

  • verbose включает всё
  • debug исключает часть внутренних деталей
  • info ограничивается базовыми сообщениями
  • warning оставляет только предупреждения и ошибки
  • error оставляет только ошибки
  • silent отключает вывод полностью

Влияние на ошибки и исключения

Важно различать логирование и обработку ошибок:

  • logLevel не отключает ошибки выполнения
  • ошибки всегда доступны через API esbuild
  • silent не делает сборку «безошибочной», он лишь скрывает вывод

Пример:

try {
  await esbuild.build({
    entryPoints: ['src/index.js'],
    bundle: true,
    outfile: 'dist/index.js',
    logLevel: 'silent'
  });
} catch (e) {
  console.error('Сборка завершилась с ошибкой');
}

Поведение в CLI и Node.js API

CLI

esbuild src/index.js --bundle --outfile=dist.js --log-level=debug
  • параметр строго соответствует значениям API
  • регистр и формат фиксированы

Node.js API

import * as esbuild from 'esbuild';

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/index.js',
  logLevel: 'info'
});
  • принимает строковое значение
  • применяется на уровне всей сборки
  • влияет только на стандартный вывод процесса

Типичные сценарии применения уровней

Отладка сборки и плагинов

Используются verbose и debug:

  • анализ резолвинга модулей
  • диагностика ошибок плагинов
  • исследование трансформаций

Разработка приложения

Используется info:

  • контроль процесса сборки
  • минимальный шум в консоли
  • отображение предупреждений

CI/CD

Используются warning или error:

  • фокус на проблемах
  • игнорирование информационного шума
  • упрощённый лог пайплайна

Интеграция с внешними лог-системами

Используется silent:

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

Взаимодействие с предупреждениями

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

  • неиспользуемые импорты
  • несовместимость синтаксиса с целевой платформой
  • оптимизационные ограничения

При logLevel: warning и выше они становятся ключевым источником диагностической информации, при error — полностью скрываются, если не переходят в критическую ошибку.

Особенности производительности

Уровень логирования влияет на производительность косвенно:

  • verbose может замедлять вывод из-за объёма логов
  • silent минимизирует I/O операции
  • info и warning находятся в среднем диапазоне нагрузки

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

Ограничения и поведение по умолчанию

  • если logLevel не указан, используется info
  • значение применяется ко всей сборке целиком
  • невозможно задать разные уровни для разных частей сборки
  • не влияет на пользовательские callback-логики

Сочетание с другими параметрами

logLevel часто используется совместно с:

  • minify — уменьшение итогового кода, при котором логирование может быть менее важным
  • sourcemap — диагностика ошибок через исходный код
  • define — управление окружением, влияющим на предупреждения
  • plugins — источники дополнительных логов при debug и verbose

В связке эти параметры формируют общий профиль поведения сборки и диагностики.

Оглавление