Anleitung zum Hinzufügen von Lighthouse zu einem Continuous-Integration-System wie GitHub Actions.
Lighthouse CI ist eine Suite von Tools zur Verwendung von Lighthouse während der Continuous Integration. Lighthouse CI lässt sich auf viele verschiedene Arten in Entwicklungsworkflows einbinden. In diesem Leitfaden werden die folgenden Themen behandelt:
- Über die Lighthouse-CI-CLI
- CI-Anbieter zum Ausführen von Lighthouse CI konfigurieren
- GitHub-Aktion und Statusprüfung für Lighthouse CI einrichten Dadurch werden in GitHub-Pull-Anfragen automatisch Lighthouse-Ergebnisse angezeigt.
- Leistungsdashboard und Datenspeicher für Lighthouse-Berichte erstellen
Überblick
Lighthouse CI ist eine Suite kostenloser Tools, die die Verwendung von Lighthouse zur Leistungsüberwachung erleichtern. Ein einzelner Lighthouse-Bericht bietet einen Überblick über die Leistung einer Webseite zum Zeitpunkt der Ausführung. Lighthouse CI zeigt, wie sich diese Ergebnisse im Laufe der Zeit verändert haben. Dies kann verwendet werden, um die Auswirkungen bestimmter Codeänderungen zu ermitteln oder dafür zu sorgen, dass die Leistungsgrenzwerte bei kontinuierlichen Integrationsprozessen eingehalten werden. Obwohl die Leistungsüberwachung der häufigste Anwendungsfall für Lighthouse CI ist, kann sie auch zur Überwachung anderer Aspekte des Lighthouse-Berichts verwendet werden, z. B. SEO oder Barrierefreiheit.
Die Hauptfunktion von Lighthouse CI wird über die Lighthouse-CI-Befehlszeile bereitgestellt. (Hinweis: Dies ist ein separates Tool als die Lighthouse-Befehlszeile.) Die Lighthouse CI-Befehlszeile bietet eine Reihe von Befehlen zur Verwendung von Lighthouse CI. Mit dem Befehl autorun
werden beispielsweise mehrere Lighthouse-Ausführungen ausgeführt, der Medianwert für Lighthouse-Bericht ermittelt und der Bericht zum Speichern hochgeladen. Dieses Verhalten lässt sich stark anpassen, indem Sie zusätzliche Flags übergeben oder die Konfigurationsdatei lighthouserc.js
von Lighthouse CI anpassen.
Obwohl die Hauptfunktion von Lighthouse CI primär in der Lighthouse CI-CLI enthalten ist, wird Lighthouse CI in der Regel durch einen der folgenden Ansätze verwendet:
- Lighthouse CI im Rahmen der Continuous Integration ausführen
- Verwendung einer Lighthouse-CI-GitHub-Aktion, die bei jeder Pull-Anfrage ausgeführt und kommentiert wird
- Die Leistung wird im Zeitverlauf über das von Lighthouse Server bereitgestellte Dashboard erfasst.
Alle Ansätze basieren auf der Lighthouse CI CLI.
Alternativen zu Lighthouse CI können etwa Dienste zur Leistungsüberwachung von Drittanbietern oder das Schreiben eines eigenen Skripts zur Erfassung von Leistungsdaten während des CI-Prozesses sein. Sie sollten die Nutzung eines Drittanbieterdienstes in Betracht ziehen, wenn Sie die Verwaltung Ihres Servers und Ihrer Testgeräte für die Leistungsüberwachung lieber von einer anderen Person übernehmen lassen möchten oder wenn Sie Benachrichtigungsfunktionen wie E-Mail- oder Slack-Integration nutzen möchten, ohne diese Features selbst erstellen zu müssen.
Lighthouse CI lokal verwenden
In diesem Abschnitt wird erläutert, wie Sie die Lighthouse-CI-CLI lokal ausführen und installieren und wie Sie lighthouserc.js
konfigurieren. Die lokale Ausführung der Lighthouse-CI-CLI ist die einfachste Methode, um sicherzustellen, dass Ihr lighthouserc.js
richtig konfiguriert ist.
Installieren Sie die Lighthouse CI-CLI.
npm install -g @lhci/cli
Lighthouse CI wird konfiguriert, indem eine
lighthouserc.js
-Datei im Stammverzeichnis Ihres Projekts platziert wird. Diese Datei ist obligatorisch und enthält Konfigurationsinformationen zu Lighthouse CI. Obwohl Lighthouse CI für die Verwendung ohne Git-Repository konfiguriert werden kann, wird in der Anleitung in diesem Artikel davon ausgegangen, dass Ihr Projekt-Repository für die Verwendung von Git konfiguriert ist.Erstellen Sie im Stammverzeichnis Ihres Repositorys eine
lighthouserc.js
-Konfigurationsdatei.touch lighthouserc.js
Fügen Sie
lighthouserc.js
den folgenden Code hinzu. Dieser Code ist eine leere Lighthouse CI-Konfiguration. Sie werden diese Konfiguration in späteren Schritten hinzufügen.module.exports = { ci: { collect: { /* Add configuration here */ }, upload: { /* Add configuration here */ }, }, };
Bei jeder Ausführung von Lighthouse CI wird ein Server für Ihre Website gestartet. Dieser Server sorgt dafür, dass Lighthouse deine Website auch dann laden kann, wenn keine anderen Server ausgeführt werden. Wenn Lighthouse CI fertig ist, wird der Server automatisch heruntergefahren. Damit die Bereitstellung ordnungsgemäß funktioniert, sollten Sie entweder die Attribute
staticDistDir
oderstartServerCommand
konfigurieren.Wenn deine Website statisch ist, füge dem
ci.collect
-Objekt das AttributstaticDistDir
hinzu, um anzugeben, wo sich deine statischen Dateien befinden. Lighthouse CI verwendet einen eigenen Server, um diese Dateien beim Testen Ihrer Website bereitzustellen. Wenn deine Website nicht statisch ist, füge demci.collect
-Objekt das AttributstartServerCommand
hinzu, um den Befehl anzugeben, der deinen Server startet. Lighthouse CI startet während des Tests einen neuen Serverprozess und fährt ihn anschließend herunter.// Static site example collect: { staticDistDir: './public', }
// Dynamic site example collect: { startServerCommand: 'npm run start', }
Fügen Sie dem Objekt
ci.collect
das Attributurl
hinzu, um die URLs anzugeben, für die Lighthouse CI Lighthouse ausführen soll. Der Wert des Attributsurl
sollte als URL-Array angegeben werden. Dieses Array kann eine oder mehrere URLs enthalten. Standardmäßig führt Lighthouse CI Lighthouse dreimal für jede URL aus.collect: { // ... url: ['http://localhost:8080'] }
Fügen Sie dem Objekt
ci.upload
das Attributtarget
hinzu und legen Sie den Wert auf'temporary-public-storage'
fest. Die von Lighthouse CI erfassten Lighthouse-Berichte werden in einen temporären öffentlichen Speicher hochgeladen. Der Bericht bleibt sieben Tage lang dort und wird dann automatisch gelöscht. In diesem Einrichtungsleitfaden wird die Uploadoption "temporärer öffentlicher Speicher" verwendet, weil sie schnell eingerichtet werden kann. Informationen zu anderen Möglichkeiten zum Speichern von Lighthouse-Berichten finden Sie in der Dokumentation.upload: { target: 'temporary-public-storage', }
Der Speicherort des Berichts sieht in etwa so aus:
https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.html
(Diese URL funktioniert nicht, da der Bericht bereits gelöscht wurde.)
Führen Sie die Lighthouse-CI-CLI über das Terminal mit dem Befehl
autorun
aus. Dadurch wird Lighthouse dreimal ausgeführt und der Median-Lighthouse-Bericht hochgeladen.lhci autorun
Wenn Sie Lighthouse CI richtig konfiguriert haben, sollte die Ausgabe dieses Befehls in etwa so aussehen:
✅ .lighthouseci/ directory writable ✅ Configuration file found ✅ Chrome installation found ⚠️ GitHub token not set Healthcheck passed! Started a web server on port 65324... Running Lighthouse 3 time(s) on http://localhost:65324/index.html Run #1...done. Run #2...done. Run #3...done. Done running Lighthouse! Uploading median LHR of http://localhost:65324/index.html...success! Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591720514021-82403.report.html No GitHub token set, skipping GitHub status check. Done running autorun.
Sie können die
GitHub token not set
-Meldung in der Konsolenausgabe ignorieren. Ein GitHub-Token ist nur erforderlich, wenn Sie Lighthouse CI mit einer GitHub-Aktion verwenden möchten. Wie Sie eine GitHub-Aktion einrichten, wird weiter unten in diesem Artikel erläutert.Wenn Sie in der Ausgabe auf den Link klicken, der mit
https://storage.googleapis.com...
beginnt, gelangen Sie zum Lighthouse-Bericht, der der Median-Lighthouse-Ausführung entspricht.Die von
autorun
verwendeten Standardeinstellungen können über die Befehlszeile oderlighthouserc.js
überschrieben werden. Die folgendelighthouserc.js
-Konfiguration gibt beispielsweise an, dass bei jeder Ausführung vonautorun
fünf Lighthouse-Ausführungen erfasst werden sollen.Aktualisieren Sie
lighthouserc.js
, um das AttributnumberOfRuns
zu verwenden:module.exports = { // ... collect: { numberOfRuns: 5 }, // ... }, };
Führen Sie den Befehl
autorun
noch einmal aus:lhci autorun
Die Terminalausgabe sollte anzeigen, dass Lighthouse fünfmal ausgeführt wurde und nicht die Standard drei:
✅ .lighthouseci/ directory writable ✅ Configuration file found ✅ Chrome installation found ⚠️ GitHub token not set Healthcheck passed! Automatically determined ./dist as `staticDistDir`. Set it explicitly in lighthouserc.json if incorrect. Started a web server on port 64444... Running Lighthouse 5 time(s) on http://localhost:64444/index.html Run #1...done. Run #2...done. Run #3...done. Run #4...done. Run #5...done. Done running Lighthouse! Uploading median LHR of http://localhost:64444/index.html...success! Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591716944028-6048.report.html No GitHub token set, skipping GitHub status check. Done running autorun.
Informationen zu anderen Konfigurationsoptionen finden Sie in der Konfigurationsdokumentation zu Lighthouse CI.
CI-Prozess zum Ausführen von Lighthouse CI einrichten
Lighthouse CI kann mit Ihrem bevorzugten CI-Tool verwendet werden. Der Abschnitt CI-Anbieter konfigurieren der Lighthouse-CI-Dokumentation enthält Codebeispiele, die zeigen, wie Lighthouse CI in die Konfigurationsdateien gängiger CI-Tools eingebunden wird. Diese Codebeispiele zeigen insbesondere, wie Lighthouse CI ausgeführt wird, um während des CI-Prozesses Leistungsmessungen zu erfassen.
Die Verwendung von Lighthouse CI zur Erfassung von Leistungsmessungen ist ein guter Ausgangspunkt für die Leistungsüberwachung. Fortgeschrittene Nutzer möchten möglicherweise noch einen Schritt weiter gehen und Lighthouse CI verwenden, um Builds zu scheitern, wenn sie vordefinierte Kriterien nicht erfüllen, z. B. das Bestehen bestimmter Lighthouse-Prüfungen oder das Erreichen aller Leistungsbudgets. Dieses Verhalten wird über das Attribut assert
der Datei lighthouserc.js
konfiguriert.
Lighthouse CI unterstützt drei Assertion-Ebenen:
off
: Assertions ignorierenwarn
: Druckfehler in stderrerror
: Druckfehler an stderr und Beenden von Lighthouse CI mit einem Exit-Code ungleich null
Im Folgenden finden Sie ein Beispiel für eine lighthouserc.js
-Konfiguration, die Assertions enthält. Sie legt Assertions für die Punktzahlen der Leistungs- und Barrierefreiheitskategorien von Lighthouse fest. Fügen Sie zum Ausprobieren die unten gezeigten Assertions in die Datei lighthouserc.js
ein und führen Sie Lighthouse CI noch einmal aus.
module.exports = {
ci: {
collect: {
// ...
},
assert: {
assertions: {
'categories:performance': ['warn', {minScore: 1}],
'categories:accessibility': ['error', {minScore: 1}]
}
},
upload: {
// ...
},
},
};
Die generierte Konsolenausgabe sieht so aus:
Weitere Informationen zu Lighthouse-CI-Assertions finden Sie in der Dokumentation.
GitHub-Aktion zum Ausführen von Lighthouse CI einrichten
Zum Ausführen von Lighthouse CI kann eine GitHub-Aktion verwendet werden. Dadurch wird jedes Mal, wenn eine Codeänderung an einen Zweig eines GitHub-Repositorys übertragen wird, ein neuer Lighthouse-Bericht erstellt. Verwenden Sie dies zusammen mit einer Statusprüfung, um die Ergebnisse für jede Pull-Anfrage anzuzeigen.
Erstellen Sie im Stammverzeichnis Ihres Repositorys ein Verzeichnis mit dem Namen
.github/workflows
. Die Workflows für Ihr Projekt werden in dieses Verzeichnis abgelegt. Ein Workflow ist ein Prozess, der zu einem festgelegten Zeitpunkt ausgeführt wird (z. B. beim Senden von Code) und aus einer oder mehreren Aktionen besteht.mkdir .github mkdir .github/workflows
Erstellen Sie in
.github/workflows
eine Datei mit dem Namenlighthouse-ci.yaml
. Diese Datei enthält die Konfiguration für einen neuen Workflow.touch lighthouse-ci.yaml
Fügen Sie
lighthouse-ci.yaml
den folgenden Text hinzu.name: Build project and run Lighthouse CI on: [push] jobs: lhci: name: Lighthouse CI runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - name: Use Node.js 10.x uses: actions/setup-node@v1 with: node-version: 10.x - name: npm install run: | npm install - name: run Lighthouse CI run: | npm install -g @lhci/cli@0.3.x lhci autorun --upload.target=temporary-public-storage || echo "LHCI failed!"
Mit dieser Konfiguration wird ein Workflow eingerichtet, der aus einem einzigen Job besteht, der immer dann ausgeführt wird, wenn neuer Code an das Repository übertragen wird. Dieser Job besteht aus vier Schritten:
- Repository ansehen, für das Lighthouse CI ausgeführt wird
- Node installieren und konfigurieren
- Erforderliche npm-Pakete installieren
- Führen Sie Lighthouse CI aus und laden Sie die Ergebnisse in den temporären öffentlichen Speicher hoch.
Übernehmen Sie die Änderungen und übertragen Sie sie per Push an GitHub. Wenn Sie die obigen Schritte korrekt ausgeführt haben, wird durch das Übertragen von Code an GitHub der gerade hinzugefügte Workflow ausgeführt.
Auf dem Tab Aktionen Ihres Projekts können Sie prüfen, ob Lighthouse CI ausgelöst wurde, und den generierten Bericht aufrufen. Unter Ihrem letzten Commit sollte der Workflow Projekt erstellen und Lighthouse CI ausführen angezeigt werden.
Auf dem Tab Aktionen können Sie den Lighthouse-Bericht für einen bestimmten Commit aufrufen. Klicken Sie auf den Commit und dann auf den Workflowschritt Lighthouse CI. Maximieren Sie dann die Ergebnisse des Schritts Lighthouse CI ausführen.
Sie haben gerade eine GitHub-Aktion zum Ausführen von Lighthouse CI eingerichtet. Dies ist am nützlichsten, wenn es in Verbindung mit einer GitHub-Statusprüfung verwendet wird.
GitHub-Statusprüfung einrichten
Eine Statusprüfung, sofern konfiguriert, ist eine Nachricht, die in jeder PR-Benachrichtigung angezeigt wird und in der Regel Informationen wie die Ergebnisse eines Tests oder den Erfolg eines Builds enthält.
In den folgenden Schritten wird erläutert, wie Sie eine Statusprüfung für Lighthouse CI einrichten.
Rufen Sie die Seite der Lighthouse CI GitHub-Anwendung auf und klicken Sie auf Konfigurieren.
(Optional) Wenn Sie zu mehreren Organisationen auf GitHub gehören, wählen Sie die Organisation aus, zu der das Repository gehört, für das Sie Lighthouse CI verwenden möchten.
Wählen Sie Alle Repositories aus, wenn Sie Lighthouse in allen Repositories aktivieren möchten, oder wählen Sie Nur Repositories auswählen aus, wenn Sie das Tool nur in bestimmten Repositories verwenden möchten. Wählen Sie anschließend die Repositories aus. Klicken Sie dann auf Install & Authorize (Installieren und autorisieren).
Kopieren Sie das angezeigte Token. Sie benötigen sie im nächsten Schritt.
Rufen Sie zum Hinzufügen des Tokens die Seite Einstellungen des GitHub-Repositorys auf, klicken Sie auf Secrets und dann auf Neues Secret hinzufügen.
Legen Sie das Feld Name auf
LHCI_GITHUB_APP_TOKEN
und das Feld Wert auf das Token fest, das Sie im letzten Schritt kopiert haben. Klicken Sie dann auf die Schaltfläche Secret hinzufügen.Rufen Sie die Datei
lighthouse-ci.yaml
auf und fügen Sie dem Befehl „Lighthouse CI ausführen“ das neue Umgebungs-Secret hinzu.
- name: run Lighthouse CI
run: |
npm install -g @lhci/cli@0.3.x
lhci autorun --upload.target=temporary-public-storage || echo "LHCI failed!"
+ env:
+ LHCI_GITHUB_APP_TOKEN: $
- Die Statusprüfung ist einsatzbereit. Erstellen Sie eine neue Pull-Anfrage oder übertragen Sie einen Commit an eine vorhandene Pull-Anfrage, um dies zu testen.
Lighthouse-CI-Server einrichten
Der Lighthouse-CI-Server bietet ein Dashboard zum Untersuchen historischer Lighthouse-Berichte. Er kann auch als privater, langfristiger Datenspeicher für Lighthouse-Berichte dienen.
- Wählen Sie die zu vergleichenden Commits aus.
- Der Wert, um den sich der Lighthouse-Wert zwischen den beiden Commits geändert hat.
- In diesem Abschnitt werden nur Messwerte angezeigt, die sich zwischen den beiden Commits geändert haben.
- Regressionen sind rosa hervorgehoben.
- Verbesserungen sind blau hervorgehoben.
Der Lighthouse CI Server eignet sich am besten für Nutzer, die mit der Bereitstellung und Verwaltung ihrer eigenen Infrastruktur vertraut sind.
Informationen zum Einrichten des Lighthouse-CI-Servers, einschließlich Anleitungen für die Verwendung von Heroku und Docker für die Bereitstellung, finden Sie in instructions.