stats: управление детализацией вывода

Механизм stats в Webpack представляет собой централизованный способ контроля объёма и структуры информации, которая выводится во время сборки. Он влияет на консольный вывод, содержимое JSON-отчётов, а также на данные, которые используются плагинами и внешними инструментами анализа сборки.

Основная цель stats — баланс между информативностью и производительностью: от минимального логирования до максимально подробного отчёта о каждом модуле, чанке и зависимости.

Общая структура stats

Объект stats формируется после завершения компиляции и содержит агрегированную информацию:

  • модули (modules)
  • чанки (chunks)
  • ассеты (assets)
  • зависимости (dependencies)
  • ошибки и предупреждения
  • метаданные сборки

Внутренне stats строится из инстанса компилятора и может быть преобразован в JSON через:

compilation.getStats().toJson();

Или через CLI:

webpack --stats

Режимы (presets) stats

Webpack поддерживает предустановленные режимы детализации, которые задаются строкой:

stats: "none"

Полное отключение вывода.

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

stats: "errors-only"

Отображаются только ошибки.

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

stats: "minimal"

Минимальный информативный режим:

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

stats: "normal"

Стандартный режим (по умолчанию).

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

stats: "detailed"

Расширенный режим:

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

stats: "verbose"

Максимальная детализация:

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

Тонкая настройка StatsOptions

Помимо пресетов используется объект StatsOptions, который позволяет управлять отдельными секциями вывода.

Управление модулями

stats: {
  modules: true,
  modulesSpace: 10,
  chunkModules: true
}
  • modules — отображение списка модулей
  • chunkModules — модули внутри чанков
  • modulesSpace — форматирование вывода

При больших проектах включение modules: true резко увеличивает объём вывода и может замедлить сериализацию stats.

Чанки (chunks)

stats: {
  chunks: true,
  chunkOrigins: true,
  chunkRelations: true
}
  • chunks — базовая информация о чанках
  • chunkOrigins — откуда чанк был создан
  • chunkRelations — связи между чанками

Особенно полезно при анализе code splitting и динамических импортов.

Ассеты (assets)

stats: {
  assets: true,
  assetsSort: "size"
}
  • assets — список файлов результата сборки
  • assetsSort — сортировка (например, по размеру)

Позволяет выявлять самые тяжёлые файлы бандла.

Причины включения модулей (reasons)

Один из ключевых диагностических инструментов:

stats: {
  reasons: true
}

Выводит цепочку:

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

Это критически важно для анализа «почему этот код попал в сборку».

Данные о зависимостях

stats: {
  dependencies: true
}

Позволяет увидеть низкоуровневые связи между модулями, включая:

  • import/require связи
  • контекстные зависимости
  • динамические выражения

Управление уровнем логирования

Stats тесно связан с системой логирования компилятора:

stats: {
  logging: "verbose"
}

Возможные уровни:

  • none — отсутствие логов
  • error — только ошибки
  • warn — предупреждения и ошибки
  • info — общая информация
  • log — стандартные сообщения
  • verbose — максимально подробные логи

Цвет и форматирование вывода

Webpack поддерживает управление визуальным представлением:

stats: {
  colors: true,
  context: "/project/root"
}
  • colors — включение цветного вывода
  • context — базовый путь для сокращения абсолютных путей

Контекст особенно важен для уменьшения «шума» в путях модулей.

JSON-режим stats

Одно из ключевых применений stats — генерация JSON:

const stats = compilation.getStats().toJson({
  all: false,
  assets: true,
  modules: true
});

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

  • используется для анализа сборки
  • применяется в CI/CD
  • интеграция с dashboard-системами
  • возможность постобработки

Фильтрация данных (all, exclude, include)

Начиная с гибких конфигураций, используется параметр all:

stats: {
  all: false,
  assets: true,
  modules: true
}
  • all: false — отключает всё по умолчанию
  • далее включаются только нужные части

Это наиболее эффективный способ контроля размера stats-вывода.

Производительность stats

Избыточный stats напрямую влияет на:

  • время сериализации JSON
  • нагрузку на память
  • скорость CLI-вывода
  • работу плагинов анализа

Особенно затратны параметры:

  • modules: true
  • reasons: true
  • chunkModules: true
  • optimizationBailout: true

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

Оптимизационные поля

Webpack может включать дополнительную диагностическую информацию:

stats: {
  optimizationBailout: true,
  providedExports: true,
  usedExports: true
}

Значение:

  • usedExports — показывает, какие экспорты реально используются
  • providedExports — какие экспорты предоставляет модуль
  • optimizationBailout — причины отказа от оптимизаций

Эти поля используются при анализе tree-shaking.

Stats для разработки и production

Разработка

Обычно используется минимальная конфигурация:

  • быстрый вывод
  • только ошибки
  • отсутствие глубокой детализации

Production

Используются расширенные stats:

  • анализ размера бандла
  • проверка tree-shaking
  • аудит зависимостей
  • интеграция с аналитикой

Внутреннее преобразование stats

Процесс формирования stats включает несколько этапов:

  1. Сбор данных из compilation
  2. Фильтрация по StatsOptions
  3. Сериализация объектов
  4. Преобразование в JSON или строку
  5. Форматирование CLI вывода

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

Использование stats в плагинах

Плагины Webpack часто используют stats для:

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

Пример:

compiler.hooks.done.tap("MyPlugin", (stats) => {
  const json = stats.toJson({
    modules: true
  });
});

Частые проблемы при работе со stats

Перегрузка вывода

Включение слишком детализированных опций приводит к:

  • огромному JSON
  • медленной сериализации
  • падению производительности CLI

Несовместимость с CI

Некоторые CI-системы ограничивают размер логов, и verbose stats может приводить к:

  • обрезанию вывода
  • потере информации
  • нестабильной интерпретации результата

Ошибочная интерпретация данных

При включении reasons и dependencies легко неверно интерпретировать цепочку импортов, особенно при:

  • barrel exports
  • dynamic imports
  • alias resolution
Оглавление