Миграция между версиями

Основные принципы миграции

При переходе с одной версии Lighthouse на другую важно учитывать изменения в API, структуре отчётов и возможные изменения в настройках аудитов. Библиотека постоянно развивается, и новые версии могут вводить устранение устаревших функций, модификацию схем данных и корректировку методов запуска аудитов. Основной принцип миграции — анализ release notes и постепенная адаптация существующего кода под новую версию.

Обновление зависимости

Для проектов на Node.js обновление Lighthouse выполняется через npm или yarn:

npm install lighthouse@latest

или

yarn add lighthouse@latest

Важно проверять совместимость с версией Node.js, так как новые версии Lighthouse иногда требуют более современных версий среды выполнения.

Изменения в API

1. Методы запуска

В старых версиях для запуска аудита использовался синхронный метод:

const lighthouse = require('lighthouse');
const results = lighthouse(url, options, config);

В новых версиях предпочтение отдаётся асинхронной версии:

import lighthouse from 'lighthouse';
import chromeLauncher from 'chrome-launcher';

(async () => {
  const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
  const options = {port: chrome.port};
  const results = await lighthouse('https://example.com', options);
  await chrome.kill();
})();

Ключевой момент: port теперь является обязательным при запуске через удалённый экземпляр Chrome, а использование встроенного lighthouse() без ChromeLauncher может не поддерживаться.

2. Конфигурации аудитов

Конфигурации стали более гибкими. Старый способ:

const config = {
  extends: 'lighthouse:default',
  settings: {
    onlyCategories: ['performance']
  }
};

В новых версиях можно создавать кастомные конфиги с точечной настройкой аудитов:

import {config as defaultConfig} from 'lighthouse/lighthouse-core/config/default-config.js';

const customConfig = {
  ...defaultConfig,
  settings: {
    ...defaultConfig.settings,
    onlyAudits: ['first-contentful-paint', 'largest-contentful-paint'],
    throttlingMethod: 'simulate'
  }
};

Это позволяет запускать только нужные аудиты, экономя ресурсы и ускоряя анализ.

3. Структура отчётов

Ранее объект results содержал поля lhr и report:

const {lhr, report} = results;

С введением новых версий формат отчёта немного изменился:

  • lhr (Lighthouse Result) сохраняет все метрики и детали аудитов.
  • report может быть массивом или объектом, в зависимости от формата (json, html, csv).
  • categories внутри lhr теперь более строго типизированы, и некоторые ключи могут быть удалены или переименованы.

Необходимо проверять код, который обращается к метрикам, чтобы избежать ошибок undefined.

Обновление настроек аудита

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

const customConfig = {
  extends: 'lighthouse:default',
  settings: {
    onlyAudits: ['speed-index', 'interactive']
  }
};

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

Поддержка новых возможностей

Новые версии Lighthouse поддерживают расширенные методы анализа, например:

  • Throttling Simulation: эмуляция сетевых условий для тестирования мобильного и десктопного опыта.
  • Gather Mode: возможность разделять сбор данных и их анализ, что удобно для CI/CD.
  • Plugin System: добавление пользовательских аудитов и категорий.

Эти возможности требуют изучения новых интерфейсов, но позволяют гибко интегрировать Lighthouse в сложные пайплайны.

Практический подход к миграции

  1. Проверка зависимостей — убедиться, что версия Node.js и других библиотек совместима с новой версией Lighthouse.
  2. Анализ изменений в API — изучить release notes и определить устаревшие методы.
  3. Переписывание конфигураций — заменить disabledAudits на onlyAudits, проверить настройки категорий.
  4. Тестирование на текущих страницах — сравнить старые и новые результаты для выявления различий.
  5. Обновление CI/CD сценариев — если Lighthouse используется в автоматизации, проверить совместимость скриптов с новым API.

Советы по совместимости

  • Всегда хранить старую версию в package.json как резерв, чтобы можно было откатиться при критических ошибках.
  • Использовать отдельный branch для миграции и тестирования, чтобы не ломать продакшн.
  • Проверять логи и структуру lhr.categories после обновления, так как ключи могут измениться.

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

Оглавление