Поле onwarn: фильтрация предупреждений

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

Во время анализа модулей Rollup формирует предупреждения (warnings), если обнаруживает неоднозначные конструкции, потенциальные ошибки или неоптимальные паттерны. По умолчанию эти предупреждения выводятся в консоль, однако поведение можно полностью перехватить с помощью onwarn.

Каждое предупреждение представлено объектом со структурой, включающей:

  • code — строковый идентификатор типа предупреждения
  • message — текст сообщения
  • id — путь к файлу, где возникло предупреждение (если применимо)
  • loc — позиция в файле (строка и колонка)
  • frame — фрагмент кода с подсветкой
  • plugin — имя плагина, если предупреждение сгенерировано плагином

Обработчик получает этот объект и вторым аргументом функцию warn, которую можно вызвать для стандартного вывода предупреждения.

Сигнатура onwarn

Базовая форма конфигурации выглядит следующим образом:

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  onwarn(warning, warn) {
    warn(warning);
  }
};

Параметры:

  • warning — объект предупреждения
  • warn — функция дефолтной обработки

Если warn не вызвать, предупреждение будет полностью подавлено.

Фильтрация предупреждений по коду

Наиболее распространённый сценарий использования onwarn — подавление конкретных типов предупреждений через поле code.

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

  • THIS_IS_UNDEFINED
  • CIRCULAR_DEPENDENCY
  • EVAL
  • MISSING_GLOBAL_NAME
  • UNRESOLVED_IMPORT

Пример фильтрации по коду

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'cjs'
  },
  onwarn(warning, warn) {
    if (warning.code === 'CIRCULAR_DEPENDENCY') {
      return;
    }

    warn(warning);
  }
};

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

Фильтрация по содержимому сообщения

Иногда код предупреждения отсутствует или недостаточно точен, тогда используется анализ message.

onwarn(warning, warn) {
  if (warning.message.includes('Use of eval')) {
    return;
  }

  warn(warning);
}

Подход менее строгий, чем проверка code, поскольку текст сообщения может изменяться между версиями Rollup.

Контекстное подавление предупреждений

Поле id позволяет фильтровать предупреждения по конкретным файлам или модулям.

onwarn(warning, warn) {
  if (warning.id && warning.id.includes('legacy/')) {
    return;
  }

  warn(warning);
}

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

Логирование и расширенная обработка

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

onwarn(warning, warn) {
  const base = `[Rollup warning] ${warning.code || ''}`;

  if (warning.plugin) {
    console.log(`${base} (plugin: ${warning.plugin}) ${warning.message}`);
  } else {
    console.log(`${base} ${warning.message}`);
  }

  warn(warning);
}

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

Подавление предупреждений от плагинов

Плагины также могут генерировать предупреждения, и они помечаются полем plugin. Это даёт возможность разделять источники проблем.

onwarn(warning, warn) {
  if (warning.plugin === 'rollup-plugin-terser') {
    return;
  }

  warn(warning);
}

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

Особенности поведения warn()

Функция warn, передаваемая вторым аргументом, выполняет стандартную обработку предупреждения. Вызов warn(warning) эквивалентен поведению Rollup по умолчанию.

Важно учитывать:

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

Комбинирование условий фильтрации

В реальных проектах фильтрация обычно комбинирует несколько критериев:

onwarn(warning, warn) {
  const ignoredCodes = new Set([
    'CIRCULAR_DEPENDENCY',
    'UNRESOLVED_IMPORT'
  ]);

  if (ignoredCodes.has(warning.code)) {
    return;
  }

  if (warning.id && warning.id.includes('vendor/')) {
    return;
  }

  warn(warning);
}

Такой подход формирует предсказуемую политику обработки предупреждений и снижает шум в логах.

Использование уровней важности

Хотя Rollup не предоставляет встроенную систему уровней логирования для предупреждений, её можно имитировать:

function getSeverity(warning) {
  switch (warning.code) {
    case 'CIRCULAR_DEPENDENCY':
      return 'low';
    case 'UNRESOLVED_IMPORT':
      return 'high';
    default:
      return 'medium';
  }
}

onwarn(warning, warn) {
  const severity = getSeverity(warning);

  if (severity === 'low') {
    return;
  }

  warn(warning);
}

Это упрощает интеграцию с CI/CD, где важно различать критичность сообщений.

Отличие onwarn в input и output конфигурации

onwarn может задаваться в корневой конфигурации и в секции output. При наличии нескольких конфигураций для разных форматов поведения могут различаться.

  • глобальный onwarn применяется ко всем сборкам
  • output.onwarn переопределяет обработчик для конкретного выходного формата
export default {
  input: 'src/index.js',
  onwarn(warning, warn) {
    warn(warning);
  },
  output: [
    {
      file: 'dist/cjs.js',
      format: 'cjs',
      onwarn() {}
    },
    {
      file: 'dist/esm.js',
      format: 'esm'
    }
  ]
};

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

Типичные ошибки при использовании onwarn

Распространённые проблемы:

  • полное подавление всех предупреждений без анализа контекста
  • использование только message.includes, что делает фильтрацию нестабильной
  • игнорирование предупреждений от плагинов без понимания их природы
  • отсутствие вызова warn, приводящее к «тихим» сбоям архитектуры

Корректная стратегия заключается в точечном подавлении с приоритетом на code и дополнительной проверкой контекста через id и plugin.

Практическая модель применения

В зрелых проектах onwarn становится частью инфраструктуры сборки. Он используется для:

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

Грамотно настроенный onwarn позволяет сохранить баланс между информативностью сборки и контролируемым уровнем сигналов о потенциальных проблемах в кодовой базе.

Оглавление