Обработка ошибок

Библиотека Lighthouse для JavaScript предоставляет средства для анализа веб-страниц и генерации отчетов о производительности, доступности, SEO и других аспектах. Поскольку работа с веб-ресурсами сопряжена с сетевыми задержками, некорректными данными и различными непредвиденными ситуациями, грамотная обработка ошибок является критически важной частью при интеграции Lighthouse в проекты.

Типы ошибок в Lighthouse

  1. Сетевые ошибки Возникают при невозможности загрузки страницы или ресурсов. Классические примеры: таймаут соединения, отказ в доступе, недоступность сервера.

    Особенности обработки:

    • Использование try...catch для асинхронных вызовов, таких как lighthouse(url, options).
    • Логирование с указанием URL и времени возникновения ошибки для последующего анализа.

  2. Ошибки конфигурации Возникают при неправильных настройках объекта LighthouseFlags или LighthouseConfig. Примеры: неверно указан outputPath, некорректный port, конфликт настроек аудитов.

    Рекомендации:

    • Проверка валидности конфигурационного объекта перед вызовом lighthouse().
    • Использование типов и схем в TypeScript или библиотеках валидации JSON, чтобы исключить неправильные значения до запуска анализа.

  3. Ошибки выполнения аудитов Lighthouse выполняет множество аудитов, включая анализ DOM, Lighthouse Performance Metrics и Accessibility Checks. Ошибки могут возникать из-за:

    • Некорректного DOM-структуры
    • Скриптов, блокирующих загрузку
    • Несовместимости с API браузера

    Стратегии обработки:

    • Перехват исключений при работе с отдельными аудитами через try...catch.
    • Фильтрация результатов и отметка неудачных аудитов отдельным статусом для последующего анализа, вместо остановки всей проверки.

Асинхронная обработка ошибок

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

const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');

async function runLighthouse(url, options, config) {
    let chrome;
    try {
        chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
        options.port = chrome.port;
        const result = await lighthouse(url, options, config);
        return result.lhr; // Lighthouse Report
    } catch (err) {
        console.error('Ошибка выполнения Lighthouse:', err.message);
        throw err;
    } finally {
        if (chrome) {
            await chrome.kill();
        }
    }
}

Ключевые моменты:

  • finally гарантирует освобождение ресурсов (например, закрытие экземпляра Chrome), даже если возникла ошибка.
  • Ошибки логируются с понятным сообщением, что облегчает отладку.

Логирование и диагностика

Для отладки и анализа ошибок в Lighthouse важна подробная информация о состоянии:

  • Стек вызовов (err.stack) помогает определить, на каком этапе произошел сбой.
  • Статус аудитов: отдельное хранение результатов, даже если часть аудитов не прошла, позволяет сохранить полезные данные.
  • Временные метки фиксируют моменты возникновения ошибки, что важно при сетевых таймаутах или медленных страницах.

Пользовательские обработчики ошибок

В случаях массового анализа страниц удобно создавать унифицированный обработчик ошибок, который:

  • Преобразует ошибки Lighthouse в стандартизированные объекты
  • Хранит ошибки в базе или JSON-файлах для последующего анализа
  • Позволяет повторно запускать неудачные проверки без прерывания общего процесса

Пример структуры объекта ошибки:

{
    url: 'https://example.com',
    type: 'NetworkError', // NetworkError, ConfigError, AuditError
    message: 'Не удалось загрузить страницу',
    timestamp: '2026-03-23T12:45:00Z',
    stack: 'Error stack trace...'
}

Обработка специфических сценариев

  1. Таймауты Настройка параметра maxWaitForLoad или использование Promise.race() для ограничения времени ожидания загрузки страницы.

  2. Недоступность ресурсов Логи записываются с указанием URL недоступных ресурсов, что позволяет различать критические и незначительные ошибки.

  3. Ошибки при рендеринге Иногда скрипты страницы вызывают исключения при рендеринге. В таких случаях полезно сохранять скриншоты или HAR-файлы, чтобы точно диагностировать проблему.

Интеграция с CI/CD

При запуске Lighthouse в CI/CD пайплайне важно, чтобы ошибки:

  • Не останавливали весь процесс сборки без необходимости
  • Отправлялись в отдельный лог или дашборд
  • Позволяли создавать отчеты с неполными результатами, но с метками ошибок

Это достигается комбинацией асинхронного try...catch, стандартизированных объектов ошибок и централизованного логирования.

Оглавление