Lighthouse
Führen Sie Google Lighthouse aus, um die Webqualität zu messen und zu überprüfen, ob Korrekturen die Kennzahlen tatsächlich verbessert haben. Lighthouse prüft eine URL in den Bereichen Performance, Barrierefreiheit, SEO und Best Practices und gibt einen Score von 0–100 pro Kategorie sowie eine Liste der fehlgeschlagenen Audits mit spezifischen Anleitungen zurück.
Wann dieses Skill verwendet werden sollte
Dieses Skill misst. Verwandte Qualitätsskills beheben. Der Workflow ist eine Schleife:
messen (dieses Skill) → beheben (Performance / Barrierefreiheit / SEO / Best Practices) → erneut messen
Greifen Sie auf dieses Skill zu, um: einen Basis-Score zu erhalten, die spezifischen fehlgeschlagenen Audits zu finden, ein Performance-Budget festzulegen, einen Build in CI abzusichern oder zu beweisen, dass eine Änderung eine Metrik verbessert (oder verschlechtert) hat. Raten Sie nicht bei Verbesserungen – messen Sie, ändern Sie eine Sache, messen Sie erneut.
Funktionsweise
- Wählen Sie eine Ziel-URL – eine bereitgestellte URL oder einen lokalen Entwicklungs-/Vorschau-Server (
http://localhost:3000). - Führen Sie Lighthouse aus – bevorzugt mit
scripts/run-lighthouse.sh <url>; es führt mehrere Läufe durch, nimmt den Median und gibt kompaktes JSON aus (vollständige Berichte sind riesig und verschwenden Kontext). - Lesen Sie die Kategorie-Scores + fehlgeschlagenen Audits aus dem JSON.
- Ordnen Sie jedes fehlgeschlagene Audit einer Korrektur zu mit dem entsprechenden Qualitätsskill.
- Führen Sie erneut aus und melden Sie das Vorher/Nachher-Delta.
Installation und Ausführung (CLI)
Die Lighthouse-Readme installiert es global (benötigt Node 22 LTS+), und es benötigt ein lokales Chrome/Chromium, das Sie installiert haben müssen:
npm install -g lighthouse
# oder: yarn global add lighthouse
lighthouse https://example.com --view # einfacher Lauf; --view öffnet den HTML-Bericht
Lighthouse erkennt automatisch ein installiertes Chrome; Sie können es mit der Umgebungsvariablen CHROME_PATH auf ein bestimmtes Binary verweisen.
Für einen schnellen Einzellauf ohne globale Installation funktioniert auch npx lighthouse <url> – die veröffentlichte CLI-Bin unterstützt dies, obwohl die offizielle Dokumentation nur die globale Installation abdeckt.
Maschinenlesbarer Lauf für einen Agenten (JSON in eine Datei, ruhig, headless):
npx lighthouse https://example.com \
--quiet \
--chrome-flags="--headless=new" \
--only-categories=performance,accessibility,seo,best-practices \
--output=json --output-path=./lh.json
Das Wrapper-Skript (empfohlen)
scripts/run-lighthouse.sh kapselt die CLI, führt N Läufe durch, wählt den Median (Lighthouses eigene Empfehlung zur Reduzierung der Varianz) und gibt kompaktes JSON auf stdout aus – nur die Kategorie-Scores und die fehlgeschlagenen Audits. Menschliche Logs gehen nach stderr.
# Verwendung: run-lighthouse.sh <url> [läufe] [kategorien]
skills/lighthouse/scripts/run-lighthouse.sh https://example.com 3
skills/lighthouse/scripts/run-lighthouse.sh http://localhost:3000 5 performance,accessibility
Beispielausgabe:
{
"success": true,
"url": "https://example.com",
"runs": 3,
"lighthouseVersion": "13.x",
"scores": { "performance": 78, "accessibility": 95, "seo": 92, "best-practices": 96 },
"failingAudits": [
{ "id": "largest-contentful-paint", "score": 0.4, "displayValue": "4.2 s" },
{ "id": "unused-javascript", "score": 0.3, "displayValue": "Potential savings of 180 KiB" }
]
}
Wichtige Flags
| Flag | Zweck |
|---|---|
--output=json|html|csv | Berichtsformat (für mehrere wiederholen) |
--output-path=<pfad> | Wohin der Bericht geschrieben wird |
--only-categories=… | Einschränken auf performance,accessibility,seo,best-practices |
--preset=desktop | Desktop-Konfiguration (Standard ist mobil: emuliertes Mittelklasse-Telefon + langsames 4G) |
--chrome-flags="--headless=new" | Headless ausführen (CI/Server) |
--budget-path=budget.json | Ein Performance-Budget erzwingen (LightWallet) |
--throttling-method=simulate|devtools|provided | Drosselungsmethode (simulate ist die Standard-Lab-Drosselung) |
--quiet | Fortschrittsprotokollierung unterdrücken |
--view | Den HTML-Bericht nach Abschluss öffnen |
Das JSON lesen
Scores sind 0–1-Gleitkommazahlen unter categories; Audit-Details sind unter audits.
# Kategorie-Scores (0–1) → mit 100 multiplizieren für den bekannten Score
jq '.categories | to_entries | map({(.key): (.value.score)}) | add' lh.json
# Core Web Vitals-Lab-Werte
jq '.audits | {
LCP: .["largest-contentful-paint"].displayValue,
CLS: .["cumulative-layout-shift"].displayValue,
TBT: .["total-blocking-time"].displayValue
}' lh.json
# Fehlgeschlagene/Chancen-Audits, die es wert sind, bearbeitet zu werden
jq '[.audits[] | select(.score != null and .score < 0.9)
| {id, score, displayValue}]' lh.json
Performance-Budgets (LightWallet)
Lassen Sie den Lauf fehlschlagen, wenn Assets oder Zeitüberschreitungen einen Schwellwert überschreiten. Ein bereit zum Bearbeiten examples/budget.json wird mit diesem Skill ausgeliefert; die Struktur ist:
[
{
"path": "/*",
"timings": [
{ "metric": "largest-contentful-paint", "budget": 2500 },
{ "metric": "interactive", "budget": 3800 }
],
"resourceSizes": [
{ "resourceType": "script", "budget": 300 },
{ "resourceType": "stylesheet", "budget": 100 },
{ "resourceType": "image", "budget": 500 },
{ "resourceType": "total", "budget": 1500 }
],
"resourceCounts": [
{ "resourceType": "third-party", "budget": 10 }
]
}
]
lighthouse https://example.com --budget-path=budget.json --output=json --output-path=./lh.json
Größen sind in KB, Zeitangaben in ms. Budget-Ergebnisse landen unter den Audits performance-budget und timing-budget im JSON.
Lab vs. Feld – lesen Sie dies, bevor Sie einer Zahl vertrauen
Lighthouse ist ein Lab-Tool: ein synthetischer Ladevorgang, auf emulierter Hardware, mit simulierter Drosselung. Es ist reproduzierbar und eignet sich hervorragend zum Erkennen von Regressionen, aber es ist nicht das, was echte Benutzer erleben.
- Varianz ist real. Ein einzelner Lauf kann um ±5–10 Punkte schwanken. Führen Sie mindestens 3 Läufe durch und nehmen Sie den Median (das Wrapper-Skript macht dies).
- Für echte Benutzerdaten verwenden Sie stattdessen Feld-Quellen: CrUX, PageSpeed Insights (das sowohl Lab- als auch Felddaten anzeigt), den Core Web Vitals-Bericht der Search Console oder die
web-vitals-Bibliothek, die an Ihre Analysen berichtet. - INP kann mit einem einzigen Lighthouse-Lauf nicht gemessen werden – es erfordert echte Interaktionen. Lighthouse meldet Total Blocking Time (TBT) als seinen Lab-Stellvertreter; behandeln Sie das Feld-INP als Quelle der Wahrheit.
Hinweis zu Lighthouse v13 (Insight Audits)
Seit v13 (Okt. 2025+) hat Lighthouse Performance auf Insight Audits migriert. Mehrere ältere gelegenheitsspezifische Audit-IDs wurden zusammengeführt oder entfernt (z.B. CLS-bezogene Audits → cls-culprits-insight, Bild-Audits → image-delivery-insight). Der Rat bleibt unverändert; nur Audit-IDs und Berichtsgruppierung haben sich geändert. Behandeln Sie ältere Berichte beim Parsen als Obermenge, nicht als Widerspruch. Fixieren Sie eine Lighthouse-Version in CI, damit die Audit-IDs, auf die Sie sich stützen, stabil bleiben.
Wie der Performance-Score berechnet wird
Der Performance-Score ist eine gewichtete Mischung aus Lab-Metriken (Gewichte verschieben sich zwischen den Versionen). In aktuellen Versionen sind die Schwergewichte ungefähr:
| Metrik | Ungefähres Gewicht |
|---|---|
| Total Blocking Time (TBT) | ~30% |
| Largest Contentful Paint (LCP) | ~25% |
| Cumulative Layout Shift (CLS) | ~25% |
| First Contentful Paint (FCP) | ~10% |
| Speed Index | ~10% |
Da TBT/LCP/CLS dominieren, verschiebt die Behebung dieser den Score am meisten. Verwenden Sie den Lighthouse Scoring Calculator, um genau zu sehen, wie sich eine Metrikänderung auf Punkte auswirkt.
CI und die programmatische API
In Referenzen gehalten, um fokussiert zu bleiben:
- Continuous Integration —
@lhci/cli,lighthouserc.js-Behauptungen und ein GitHub Actions-Workflow: references/CI.md - Programmatische (Node) API — Lighthouse mit
chrome-launcherfür benutzerdefinierte Abläufe, Benutzerflüsse und Bulk-Läufe: references/PROGRAMMATIC-API.md
Audits Korrekturen zuordnen
| Lighthouse-Kategorie | Beheben mit |
|---|---|
| Performance / Core Web Vitals | einem Performance- oder Core Web Vitals-Skill |
| Barrierefreiheit | einem Barrierefreiheits-/WCAG-Skill |
| SEO | einem SEO-Skill |
| Best Practices | einem Sicherheits-/Best-Practices-Skill |
Kombinieren Sie dieses Skill mit addyosmani/web-quality-skills für die Korrekturseite der Schleife.