Уровни логирования: infrastructureLogging

webpack использует многоуровневую систему логирования, разделяя сообщения на пользовательские логи сборки, логи компилятора и инфраструктурные сообщения, которые генерируются внутренними подсистемами. Параметр infrastructureLogging отвечает за управление уровнем и форматом логов, относящихся к внутренней инфраструктуре webpack: файловым наблюдателям, кешированию, resolver’ам модулей, плагинам и процессам компиляции.

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

  • сообщения file system watcher’а (следит за изменениями файлов)
  • операции resolver’а (поиск модулей)
  • события кеширования
  • диагностика внутренних оптимизаций
  • сообщения плагинов, использующих инфраструктурный logger

Эти логи предназначены для отладки поведения сборщика, а не для конечного пользователя сборки.

Структура настройки infrastructureLogging

Конфигурация задаётся в объекте webpack.config.js:

module.exports = {
  infrastructureLogging: {
    level: 'info'
  }
};

Полная форма включает дополнительные параметры:

module.exports = {
  infrastructureLogging: {
    level: 'info',
    debug: false,
    colors: true,
    appendOnly: false
  }
};

Каждый параметр влияет на способ вывода диагностической информации.

Уровни логирования

Параметр level управляет детализацией сообщений инфраструктуры. Webpack поддерживает несколько уровней, упорядоченных по возрастанию количества выводимой информации:

none

Полное отключение инфраструктурных логов.

infrastructureLogging: {
  level: 'none'
}

Используется в production-сборках, где важно минимизировать любой дополнительный вывод и ускорить выполнение.

error

Вывод только критических ошибок инфраструктуры. Сюда относятся сбои файловой системы, невозможность чтения кеша, ошибки resolver’а.

infrastructureLogging: {
  level: 'error'
}

Подходит для стабильных окружений, где требуется фиксировать только сбои.

warn

Добавляет предупреждения к ошибкам. Например, deprecated-опции внутренних модулей или потенциально проблемные операции кеширования.

infrastructureLogging: {
  level: 'warn'
}

Этот уровень часто используется в CI-средах для контроля качества конфигурации.

info

Информационный уровень, включающий основные события инфраструктуры: инициализацию watcher’ов, создание кеша, подключение resolver’ов.

infrastructureLogging: {
  level: 'info'
}

Является балансом между диагностикой и шумом в консоли.

log

Расширенный уровень логирования. Добавляет детализированные сообщения о внутренних операциях webpack.

infrastructureLogging: {
  level: 'log'
}

Применяется при глубокой отладке поведения сборки, особенно при сложных конфигурациях с множеством плагинов.

verbose

Максимально подробный режим.

infrastructureLogging: {
  level: 'verbose'
}

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

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

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

infrastructureLogging не заменяет stats.logging, так как они управляют разными слоями вывода:

  • stats.logging — логика сборки (chunks, modules, assets)
  • infrastructureLogging — внутренняя инфраструктура webpack

Пример комбинированной настройки:

module.exports = {
  stats: {
    logging: 'normal'
  },
  infrastructureLogging: {
    level: 'warn'
  }
};

Такая конфигурация позволяет видеть только предупреждения инфраструктуры, не перегружая вывод данными сборки.

Параметр debug

Параметр debug включает отладочные сообщения для выбранных инфраструктурных категорий.

infrastructureLogging: {
  level: 'info',
  debug: ['Resolver', 'Compilation']
}

Возможные значения элементов массива зависят от внутренних namespace webpack. На практике используются:

  • Resolver
  • Compilation
  • FileSystemInfo
  • Watching
  • Cache

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

Управление цветами вывода

Параметр colors контролирует использование ANSI-цветов в логах:

infrastructureLogging: {
  level: 'log',
  colors: true
}

При false вывод становится монохромным, что полезно для CI-сред и логирования в файлы.

appendOnly режим

Опция appendOnly изменяет поведение вывода логов в консоль:

infrastructureLogging: {
  level: 'info',
  appendOnly: true
}

При включении сообщения не перерисовывают строки в терминале, а выводятся последовательно. Это важно для сред, где отсутствует поддержка динамического обновления консоли (например, Docker logs или CI pipelines).

Примеры поведения уровней

Минимальный production-конфиг

module.exports = {
  infrastructureLogging: {
    level: 'none'
  }
};

Инфраструктурные сообщения полностью подавлены, остаются только критические ошибки системы.

Отладка resolver’а модулей

module.exports = {
  infrastructureLogging: {
    level: 'log',
    debug: ['Resolver']
  }
};

Позволяет отслеживать процесс поиска модулей, включая алиасы, расширения и fallback-цепочки.

Анализ проблем кеширования

module.exports = {
  infrastructureLogging: {
    level: 'verbose',
    debug: ['Cache', 'Compilation']
  }
};

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

Особенности поведения в разных режимах webpack

В development-режиме webpack чаще использует инфраструктурные сообщения для информирования о пересборках, изменениях файлов и активности watcher’а. В production большинство этих сообщений подавляется независимо от конфигурации, если уровень установлен слишком низко.

Hot Module Replacement также генерирует инфраструктурные события, которые можно отследить через verbose или log уровень.

Влияние на производительность

Высокие уровни логирования (log, verbose) увеличивают нагрузку на консольный вывод и могут снижать скорость сборки при больших проектах. Основные причины:

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

В больших монорепозиториях это может быть заметно при частых пересборках.

Связь с FileSystemCache и Persistent Cache

При использовании persistent cache инфраструктурные логи становятся особенно важными:

module.exports = {
  cache: {
    type: 'filesystem'
  },
  infrastructureLogging: {
    level: 'info',
    debug: ['Cache']
  }
};

В этом режиме можно наблюдать:

  • попадания в кеш (cache hit)
  • промахи кеша (cache miss)
  • сериализацию модулей
  • восстановление состояния компиляции

Поведение в кастомных плагинах

Плагины webpack могут использовать инфраструктурный logger через compilation.getLogger:

class MyPlugin {
  apply(compiler) {
    compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
      const logger = compilation.getLogger('MyPlugin');

      logger.info('Initialization step');
      logger.debug('Internal state updated');
    });
  }
}

Вывод этих сообщений зависит от infrastructureLogging.level, что позволяет централизованно управлять диагностикой без изменения кода плагина.

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

Изоляция логов для CI

module.exports = {
  infrastructureLogging: {
    level: 'warn',
    colors: false,
    appendOnly: true
  }
};

Глубокая отладка монорепозитория

module.exports = {
  infrastructureLogging: {
    level: 'verbose',
    debug: ['Resolver', 'Cache', 'Watching', 'Compilation'],
    colors: true
  }
};

Минимизация шума в production

module.exports = {
  infrastructureLogging: {
    level: 'error'
  }
};

Такой подход оставляет только критические сообщения, не влияя на производительность и не засоряя логи.

Оглавление