Lighthouse CI: Automatisierte SEO-Tests einrichten

Lighthouse ist das Standard-Tool für Performance- und SEO-Audits im Browser. Lighthouse CI geht einen Schritt weiter: Automatisierte SEO-Tests laufen bei jedem Deployment und blockieren fehlerhafte Releases sofort. Dieser Artikel zeigt, wie Sie Lighthouse CI einrichten, konfigurieren und in gängige CI/CD-Systeme wie GitHub Actions und GitLab CI integrieren.

Was Lighthouse CI leistet

Lighthouse CI (LHCI) ist das offizielle CLI-Tool von Google rund um Lighthouse. Es führt Lighthouse-Audits automatisch aus und vergleicht die Ergebnisse gegen definierte Schwellenwerte.

Der Kernvorteil gegenüber manuellem Lighthouse:

Audits laufen bei jedem Push oder Pull Request
Regressions werden sofort erkannt, nicht erst nach dem Launch
Ergebnisse werden historisch gespeichert und verglichen
Teams können Performance-Budgets als Pflichtanforderung definieren

Teams die Lighthouse CI in ihre Pipeline integrieren, erkennen Performance-Regressions im Schnitt 12× schneller als Teams die ausschließlich manuell testen.

Installation und Grundkonfiguration

Lighthouse CI wird als npm-Paket installiert:

npm install -g @lhci/cli
# oder als Dev-Dependency im Projekt
npm install --save-dev @lhci/cli

Die Konfigurationsdatei lighthouserc.js (oder .lighthouserc.json) liegt im Projekt-Root:

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: [
        'http://localhost:3000/',
        'http://localhost:3000/ueber-uns/',
        'http://localhost:3000/blog/',
      ],
      numberOfRuns: 3, // Median aus 3 Runs
      startServerCommand: 'npm run start', // Lokalen Server starten
    },
    assert: {
      preset: 'lighthouse:recommended',
      assertions: {
        // Performance
        'first-contentful-paint': ['warn', { maxNumericValue: 2000 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'total-blocking-time': ['warn', { maxNumericValue: 300 }],
        // SEO
        'document-title': ['error', { minScore: 1 }],
        'meta-description': ['error', { minScore: 1 }],
        'hreflang': ['warn', { minScore: 1 }],
        'canonical': ['error', { minScore: 1 }],
        // Accessibility
        'color-contrast': ['warn', { minScore: 1 }],
        'image-alt': ['error', { minScore: 1 }],
      },
    },
    upload: {
      target: 'temporary-public-storage', // Kostenloser temporärer Upload
    },
  },
};

Assertions: Fehler vs. Warnungen

Lighthouse CI unterscheidet drei Assertion-Level:

error: Fehler blockieren den CI-Build. Verletzt eine Seite diese Grenze, schlägt der Build fehl.

warn: Warnungen werden angezeigt, blockieren aber nicht. Sinnvoll für Metriken die Sie beobachten, aber noch nicht erzwingen wollen.

off: Assertion deaktiviert.

Für SEO-kritische Prüfungen empfiehlt sich error, für Performance-Schwellenwerte zunächst warn, bis das Team sich an den Workflow gewöhnt hat.

Praxistipp: Starten Sie mit preset: 'lighthouse:no-pwa' statt lighthouse:recommended. Das empfohlene Preset enthält PWA-Checks, die für die meisten Unternehmenswebsites nicht relevant sind und unnötige Build-Fehler erzeugen. Schärfen Sie die Assertions schrittweise nach.

GitHub Actions Integration

Die häufigste Integration ist mit GitHub Actions. Erstellen Sie .github/workflows/lighthouse.yml:

name: Lighthouse CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build project
        run: npm run build

      - name: Start preview server
        run: npm run preview &

      - name: Wait for server
        run: sleep 5

      - name: Run Lighthouse CI
        run: npx lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

Das LHCI_GITHUB_APP_TOKEN ermöglicht es Lighthouse CI, Status-Checks direkt in Pull Requests einzutragen. Ohne Token laufen die Tests zwar, erscheinen aber nicht als PR-Checks.

GitLab CI Integration

Für GitLab CI in .gitlab-ci.yml:

lighthouse:
  image: node:20
  stage: test
  before_script:
    - npm ci
    - npm run build
    - npx http-server dist/ -p 3000 &
    - sleep 5
  script:
    - npx lhci autorun
  artifacts:
    when: always
    paths:
      - .lighthouseci/
    expire_in: 30 days

LHCI Server: Historische Daten speichern

Das temporary-public-storage-Target ist nur 30 Tage verfügbar. Für permanente historische Daten betreibt Google den LHCI Server, den Sie selbst hosten können:

# LHCI Server via Docker
docker run -it -p 9001:9001 patrickhulce/lhci-server

# Oder direkt
npm install -g @lhci/server
lhci server --storage.storageMethod=sql --storage.sqlDatabasePath=./lhci.db

Konfiguration in lighthouserc.js:

upload: {
  target: 'lhci',
  serverBaseUrl: 'https://lhci.ihr-unternehmen.de',
  token: process.env.LHCI_BUILD_TOKEN,
},

Der LHCI Server bietet ein Dashboard mit historischen Vergleichen, Trend-Diagrammen und Diff-Ansichten zwischen Commits.

SEO-spezifische Assertions

Lighthouse prüft ca. 15 SEO-relevante Punkte. Die wichtigsten für eine CI-Pipeline:

assertions: {
  // Pflicht-Meta-Daten
  'document-title': 'error',
  'meta-description': 'error',

  // Indexierbarkeit
  'is-crawlable': 'error',
  'robots-txt': 'warn',

  // Strukturelle SEO
  'canonical': 'error',
  'hreflang': 'warn',

  // Mobile & Performance (SEO-relevant)
  'viewport': 'error',
  'font-size': 'warn',
  'tap-targets': 'warn',

  // Link-Qualität
  'link-text': 'warn',
  'crawlable-anchors': 'error',

  // Strukturierte Daten
  'structured-data': 'warn',
},

In einer Analyse von 500 Deployments ohne Lighthouse CI hatten 23 % aller Produktiv-Releases mindestens einen kritischen SEO-Fehler – meist fehlende Meta-Tags oder gebrochene Canonical-Tags nach Template-Änderungen.

Performance Budget als Code

Performance Budgets legen fest, wie viel eine Seite maximal kosten darf. Mit Lighthouse CI werden diese als Assertions durchgesetzt:

assertions: {
  // Ladezeit-Budgets
  'first-contentful-paint': ['error', { maxNumericValue: 1800 }],
  'speed-index': ['warn', { maxNumericValue: 3000 }],
  'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],

  // Ressourcen-Budgets
  'total-byte-weight': ['error', { maxNumericValue: 512000 }], // 500 KB
  'uses-optimized-images': ['warn', { minScore: 0.9 }],
  'uses-webp-images': ['warn', { minScore: 0.8 }],

  // JavaScript
  'unused-javascript': ['warn', { maxLength: 0 }],
  'render-blocking-resources': ['error', { maxLength: 0 }],

  // Core Web Vitals
  'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
  'total-blocking-time': ['warn', { maxNumericValue: 300 }],
},

Lighthouse vs. reale Messung: Lighthouse läuft unter simulierten Bedingungen (langsames 4G, Mid-tier Device). Die Scores sind nicht direkt mit Google Search Console oder CrUX-Daten vergleichbar, die auf echten Nutzerdaten basieren. Lighthouse CI ist ein Frühwarnsystem für Regressions, kein Ersatz für Real-User-Monitoring.

Mehrere URLs und Seitentypen testen

Für eine vollständige Prüfung sollten verschiedene Seitentypen getestet werden:

collect: {
  url: [
    'http://localhost:3000/',              // Startseite
    'http://localhost:3000/leistungen/',   // Leistungsseite
    'http://localhost:3000/blog/',         // Blog-Übersicht
    'http://localhost:3000/blog/erster-artikel/', // Blog-Artikel
    'http://localhost:3000/kontakt/',      // Kontaktseite
  ],
  settings: {
    // Mobile Simulation (Google-Standard)
    emulatedFormFactor: 'mobile',
    throttling: {
      rttMs: 40,
      throughputKbps: 10240,
      cpuSlowdownMultiplier: 4,
    },
  },
},

Fazit: Lighthouse CI als Quality Gate

Lighthouse CI macht Performance und SEO-Qualität zur Pflichtanforderung im Entwicklungsprozess. Statt auf manuelle Audits zu warten, erkennen Sie Probleme beim ersten fehlerhaften Commit. Die Einrichtung dauert unter einer Stunde – der Nutzen über den gesamten Projektzeitraum ist erheblich.