Конфигурационные файлы

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

Конфигурация может задаваться:

  • через CLI (параметры командной строки),
  • через JavaScript-объект при использовании Node API,
  • в виде отдельного файла конфигурации.

Наиболее мощный и расширяемый способ — использование конфигурационного файла.

Структура конфигурации

Конфигурация представляет собой JavaScript-объект, экспортируемый из файла. Базовая структура включает следующие ключевые поля:

module.exports = {
  extends: 'lighthouse:default',
  settings: {},
  passes: [],
  audits: [],
  categories: {},
  plugins: []
};

Основные разделы:

  • extends — наследование стандартной конфигурации
  • settings — глобальные параметры запуска
  • passes — этапы сбора данных
  • audits — список аудитов
  • categories — группировка аудитов в отчёте
  • plugins — подключение внешних расширений

Наследование конфигурации

Поле extends позволяет использовать предопределённые конфигурации Lighthouse:

extends: 'lighthouse:default'

Доступные варианты:

  • lighthouse:default — полный набор аудитов
  • lighthouse:recommended — сокращённый набор
  • lighthouse:no-pwa — без PWA-аудитов

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

Раздел settings

Определяет глобальное поведение Lighthouse.

settings: {
  onlyCategories: ['performance'],
  throttlingMethod: 'simulate',
  emulatedFormFactor: 'mobile',
  locale: 'ru'
}

Важные параметры:

onlyCategories Ограничивает аудит определёнными категориями:

onlyCategories: ['performance', 'seo']

onlyAudits Позволяет запускать конкретные аудиты:

onlyAudits: ['first-contentful-paint']

skipAudits Исключает определённые аудиты:

skipAudits: ['uses-http2']

throttlingMethod Метод эмуляции сети:

  • simulate — симуляция (быстрее)
  • devtools — реальное замедление

emulatedFormFactor Тип устройства:

  • mobile
  • desktop
  • none

throttling Настройки сети:

throttling: {
  rttMs: 150,
  throughputKbps: 1600,
  cpuSlowdownMultiplier: 4
}

Раздел passes

Определяет, какие данные и как собираются во время аудита. Каждый pass — это отдельный проход по странице.

passes: [
  {
    passName: 'defaultPass',
    gatherers: ['css-usage', 'js-usage'],
    recordTrace: true,
    useThrottling: true
  }
]

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

  • passName — уникальное имя
  • gatherers — список сборщиков данных
  • recordTrace — запись трассировки
  • useThrottling — использование эмуляции

Pass’ы позволяют точно контролировать этапы анализа.

Gatherers (сборщики данных)

Gatherers — это модули, собирающие данные из браузера. Они используются в разделе passes.

Пример подключения:

passes: [
  {
    passName: 'customPass',
    gatherers: [
      require.resolve('./gatherers/my-gatherer')
    ]
  }
]

Собранные данные затем используются аудитами.

Раздел audits

Определяет список проверок, которые будут выполняться.

audits: [
  'first-contentful-paint',
  'largest-contentful-paint',
  require.resolve('./audits/custom-audit')
]

Можно подключать:

  • встроенные аудиты,
  • пользовательские аудиты.

Пользовательские аудиты

Кастомный аудит — это класс, наследующий базовый аудит Lighthouse.

Пример:

class MyAudit {
  static get meta() {
    return {
      id: 'my-audit',
      title: 'Мой аудит',
      failureTitle: 'Ошибка в аудите',
      description: 'Описание проверки',
      requiredArtifacts: ['MyArtifact']
    };
  }

  static audit(artifacts) {
    return {
      score: 1,
      numericValue: 100
    };
  }
}

module.exports = MyAudit;

Раздел categories

Категории формируют структуру итогового отчёта.

categories: {
  performance: {
    title: 'Производительность',
    auditRefs: [
      { id: 'first-contentful-paint', weight: 3 },
      { id: 'my-audit', weight: 1 }
    ]
  }
}

Параметры:

  • title — название категории
  • auditRefs — список аудитов
  • weight — вес аудита в итоговой оценке

Вес влияет на итоговый score категории.

Подключение плагинов

Плагины позволяют расширять функциональность Lighthouse.

plugins: [
  'lighthouse-plugin-publisher-ads'
]

Плагин может добавлять:

  • новые аудиты,
  • новые категории,
  • дополнительные настройки.

Использование конфигурации через CLI

Конфигурационный файл можно передать через параметр:

lighthouse https://example.com --config-path=./lighthouse.config.js

Использование через Node API

const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');
const config = require('./lighthouse.config.js');

(async () => {
  const chrome = await chromeLauncher.launch();
  const result = await lighthouse('https://example.com', {
    port: chrome.port
  }, config);

  await chrome.kill();
})();

Переопределение стандартных настроек

Можно частично изменить стандартную конфигурацию:

module.exports = {
  extends: 'lighthouse:default',
  settings: {
    onlyCategories: ['performance']
  }
};

Или более гибко:

const defaultConfig = require('lighthouse/lighthouse-core/config/default-config');

module.exports = {
  ...defaultConfig,
  settings: {
    ...defaultConfig.settings,
    locale: 'ru'
  }
};

Разделение конфигурации на модули

Для крупных проектов конфигурацию удобно разбивать:

const settings = require('./config/settings');
const audits = require('./config/audits');

module.exports = {
  extends: 'lighthouse:default',
  settings,
  audits
};

Условная конфигурация

Можно динамически менять конфигурацию:

const isCI = process.env.CI === 'true';

module.exports = {
  settings: {
    throttlingMethod: isCI ? 'simulate' : 'devtools'
  }
};

Типичные сценарии использования

Оптимизация производительности:

settings: {
  onlyCategories: ['performance']
}

SEO-аудит:

settings: {
  onlyCategories: ['seo']
}

Тестирование конкретных метрик:

settings: {
  onlyAudits: [
    'largest-contentful-paint',
    'cumulative-layout-shift'
  ]
}

Ошибки и отладка

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

  • Неверные пути к кастомным аудитам
  • Отсутствие requiredArtifacts
  • Конфликты между passes и audits

Для диагностики используется режим:

lighthouse https://example.com --verbose

Практические рекомендации

  • Использование extends вместо полной конфигурации с нуля
  • Минимизация количества passes для ускорения
  • Чёткое разделение gatherers и audits
  • Использование кастомных аудитов только при необходимости
  • Версионирование конфигурации вместе с проектом

Расширенные возможности

Комбинирование конфигураций:

const base = require('./base.config');
const perf = require('./perf.config');

module.exports = {
  ...base,
  ...perf
};

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

  • проверка порогов
  • автоматическое падение сборки

Пороговые значения:

assert: {
  assertions: {
    'categories:performance': ['error', { minScore: 0.9 }]
  }
}

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

Оглавление