Lighthouse ist das Standard-Tool für Performance- und SEO-Audits im Browser - eine ausführliche Einführung finden Sie im Artikel Google Lighthouse erklärt. 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, sehen eine Performance-Regression im Pull Request statt Wochen später im Monitoring. Um wie viel schneller genau, hängt davon ab, wie oft vorher überhaupt manuell gemessen wurde.
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/cliDie 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 daysLHCI 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.dbKonfiguration 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',
},Ohne automatisierte Prüfung fallen fehlende Meta-Tags und gebrochene Canonical-Tags meist erst Wochen später auf, wenn die Rankings schon nachgeben. Entstanden sind sie fast immer bei Template-Änderungen, die im Review inhaltlich unauffällig aussahen.
Performance Budget als Code
Performance Budgets legen fest, wie viel eine Seite maximal kosten darf - wie Sie ein solches Budget systematisch planen, zeigt unser Artikel Pagespeed Budget definieren. 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
Wer die Grundlagen von Lighthouse selbst noch vertiefen möchte, findet im Artikel Google Lighthouse erklärt alle Details zu den einzelnen Scores. Auch die Font-Loading-Optimierung lässt sich per Lighthouse CI-Assertions überwachen, um font-bezogene CLS-Regressions zu verhindern.
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.
