Jak generować raporty PageSpeed

Raporty wydajności to szybki sposób na wykrycie, dlaczego strona ładuje się zbyt wolno, przesuwa zawartość lub zjada zasoby użytkownika. Poniższa instrukcja prowadzi od prostego uruchomienia testu po pełną automatyzację, archiwizację i analizę zmian w czasie. Znajdziesz tu kroki z narzędzi przeglądarkowych, komend CLI, użycia API oraz wskazówki dla SPA i serwisów z logowaniem. Dzięki temu zbudujesz własny, powtarzalny proces generowania raportów, który wesprze codzienny development i decyzje biznesowe.

Przygotowanie do generowania raportów

Co faktycznie mierzymy

Na raport PageSpeed składa się kilka warstw. Najważniejsze to testy laboratoryjne bazujące na silniku Lighthouse (symulacja warunków sieci/urządzenia), dane terenowe z bazy CrUX (rzeczywiste doświadczenia użytkowników Chrome), a także metryki kluczowe dla doświadczeń użytkownika: LCP (Largest Contentful Paint), INP (Interaction to Next Paint), CLS (Cumulative Layout Shift), TBT (Total Blocking Time) i FCP (First Contentful Paint). Różnica między danymi „lab” (powtarzalne) i „field” (realne) jest istotna: pierwsze pomagają debugować, drugie – oceniać wpływ w realnym ruchu.

Wymagania narzędziowe

• Aktualna przeglądarka Chrome (stabilna wersja).
• Node.js LTS oraz npm – do instalacji i uruchamiania narzędzi w wierszu poleceń.
• Opcjonalnie Docker – dla odtwarzalnych środowisk testowych i izolacji zależności.
• Konto Google Cloud – jeśli planujesz korzystać z API PageSpeed (klucz i limity).

Instalacja podstawowych komponentów

• Zainstaluj Node.js (np. nvm install –lts; nvm use –lts).
• Zainstaluj Lighthouse CLI: npm i -g lighthouse.
• Sprawdź wersję: lighthouse –version.
• Upewnij się, że Chrome jest dostępny (w systemie Linux czasem potrzeba chromium).

Ustalenie zakresu i listy adresów

Przygotuj listę URL-i do testów: stronę główną, kluczowe landing pages, szablony kategorii/produktów, stronę koszyka i checkout, a także podstrony generowane dynamicznie (SPA). Warto trzymać je w pliku tekstowym (np. urls.txt), aby łatwo zautomatyzować przebiegi.

Generowanie raportów: przeglądarka, DevTools i wiersz poleceń

PageSpeed Insights w przeglądarce – najszybszy start

Wejdź na pagespeed.web.dev, wklej adres URL i uruchom analizę. Domyślnie pojawi się widok dla urządzeń mobilnych; przełącznik umożliwia ocenę wersji desktop. W sekcji „Diagnostics” i „Opportunities” znajdziesz konkretne zalecenia. Klikając „View TreeMap” przeanalizujesz ciężar bundli. Ten tryb jest idealny do ręcznej weryfikacji i nauki interpretacji metryk PSI, ale manualne testy nie wystarczą do monitoringu długoterminowego.

Chrome DevTools – Lighthouse lokalnie, z podglądem

• Otwórz stronę w Chrome.
• Uruchom DevTools (F12) i przejdź do zakładki Lighthouse.
• Wybierz kategorie (Performance, Accessibility, Best Practices, SEO) i urządzenie (Mobile/Desktop).
• Kliknij „Analyze page load”.

Ten tryb pozwala szybko iterować z kodem źródłowym i obserwować wpływ zmian, ale pamiętaj, że równoległe rozszerzenia przeglądarki mogą zakłócać wyniki. Dobrym nawykiem jest tryb incognito i wyłączone pluginy.

Lighthouse CLI – jednorazowe raporty i pełna kontrola

• Podstawowa komenda: lighthouse https://example.com –view –output html –output json –output-path=./reports/example.html.
• Wymuszenie profilu mobilnego: –emulated-form-factor=mobile.
• Symulowana sieć/CPU: –throttling-method=simulate –throttling.cpuSlowdownMultiplier=4.
• Wybór kategorii: –only-categories=performance.
• Wyłączenie buforów: –disable-storage-reset=false (domyślnie Lighthouse czyści storage – to dobre dla powtarzalności).

HTML zapewnia czytelny podgląd, JSON jest kluczowy do automatycznego przetwarzania. Ustal strukturę katalogów raportów (np. ./reports/YYYY-MM-DD/), aby łatwo archiwizować i porównywać wyniki.

Wskazówki dla stabilności wyników

• Zamknij inne aplikacje obciążające CPU podczas testów.
• Wykonuj testy co najmniej 3 razy i licz medianę – pojedynczy przebieg bywa niereprezentatywny.
• Używaj stałych parametrów throttlingu dla porównań w czasie.
• Jeśli to możliwe, testuj na maszynie w chmurze o stałych zasobach.

Automatyzacja: API, skrypty i harmonogramy

API PageSpeed Insights – szybkie zapytania masowe

Uzyskaj klucz w Google Cloud i włącz usługę PageSpeed Online API. Wywołanie (przykład):

• GET https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=https://example.com&strategy=mobile&category=PERFORMANCE&category=SEO&key=TWÓJ_KLUCZ

Otrzymasz obiekt JSON zawierający „lighthouseResult” (dane „lab”) oraz sekcję danych terenowych, jeśli dostępne. Wnioski: API jest świetne do szybkich odpytań wielu adresów i zaciągania wyników do bazy, jednak nie daje pełnej kontroli nad symulacją jak CLI.

Lighthouse programistycznie w Node.js

Gdy potrzebujesz głębszej kontroli, skorzystaj z pakietu lighthouse w kodzie Node. Ogólny schemat:

• Zainstaluj zależności: npm i lighthouse chrome-launcher.
• Uruchom Chrome headless (chrome-launcher), następnie wywołaj funkcję lighthouse z URL, opcjami (form-factor, throttling, kategorie) i configiem.
• Odbierz wynik (lhr – Lighthouse Result), zapisz JSON i wygeneruj HTML rendererem raportów.
• Wyniki umieść w katalogu z datą i znacznikiem commit/wersji.

Taki skrypt łatwo rozszerzysz o odczyt listy URL z pliku, równoległe kolejki z kontrolą współbieżności, a nawet własne adnotacje (np. numer sprintu czy flaga eksperymentu A/B).

Harmonogram w systemie lub chmurze

• CRON na serwerze: uruchamiaj skrypty co noc, zapisuj JSON/HTML z datą.
• GitHub Actions: workflow na push lub według harmonogramu (cron), który instaluje Node, odpala testy i publikuje artefakty.
• GitLab CI, Jenkins lub inne narzędzia CI/CD: pozwalają łączyć testy z deploymentem oraz blokować wdrożenia, jeśli budżety są przekroczone.

Budżety wydajności i reguły jakości

Lighthouse obsługuje plik budgets.json. Przykładowe reguły: maksymalna suma JavaScript, maksymalny czas do interakcji, liczba requestów. W CLI użyj: –budgets-path=budgets.json. Dzięki temu pipeline może przerwać wdrożenie, gdy np. paczka JS przekroczy 300 kB lub TBT wzrośnie ponad określoną wartość.

Przechowywanie raportów i wersjonowanie

• Trzymaj JSON i HTML w repo lub w obiekcie chmurowym (S3/GCS) z polityką retencji.
• Dodawaj metadane: środowisko (prod/stage), commit SHA, wersja aplikacji, region.
• Przygotuj indeks (CSV/NDJSON) – przydatny do szybkiej agregacji bez parsowania całych raportów.

Raporty dla SPA, wersji z logowaniem i nietypowych scenariuszy

Testowanie SPA – właściwy moment pomiaru

W aplikacjach SPA initial paint i interakcje zależą od hydratacji i routingu po stronie klienta. Użyj opcji Lighthouse: –max-wait-for-load=60000, –wait-for-cpu-idle, albo skonfiguruj puppeteer do nawigacji i interakcji (np. kliknięcie w zakładkę) przed rozpoczęciem audytu. Dzięki temu raport obejmie rzeczywiście ważny ekran, a nie jedynie widok szkieletu.

Logowanie i stany użytkownika

Jeśli oceniasz widok tylko dla zalogowanych, przygotuj skrypt, który:

• Loguje się programowo (puppeteer: wypełnienie formularza, submit, oczekiwanie na selektor „zalogowany”).
• Zdejmuje ciasteczka sesyjne i przekazuje je do Lighthouse (ustawiając nagłówki/cookies w requestach lub testując w tym samym profilu przeglądarki).
• Dopiero potem uruchamia audyt konkretnego widoku (np. /account/orders).

Pamiętaj o bezpieczeństwie: trzymaj dane logowania w zmiennych środowiskowych i rotuj konta testowe.

Omijanie blokad i fluktuacji sieci

• Niektóre serwery blokują ruch z botów; ustaw nagłówek User-Agent zbliżony do realnego Chrome i rozważ whitelistę IP.
• Dla stabilnych wyników używaj stałego regionu – różne odległości do serwera czy węzła CDN mogą wpływać na times-to-first-byte i LCP.
• W testach powtórz przebieg z „ciepłą” pamięcią podręczną, jeśli to scenariusz realny (druga wizyta).

Testy wielu podstron i crawl po mapie witryny

Prosty mechanizm: pobierz sitemap.xml, wyfiltruj najważniejsze adresy (np. do 200), a następnie w pętli uruchamiaj Lighthouse z ograniczeniem równoległości (np. 2–3 jednoczesne testy). Loguj błędy i czasy; z długiej listy łatwo wyłapiesz wzorce (np. konkretna kategoria zawsze spada przez ciężkie zdjęcia).

Ergonomia i debug: trace, filmstrips, network

W raportach Lighthouse przejrzyj zakładki filmstrip (ramki ładowania) i network waterfall – zobaczysz, który zasób blokuje render, gdzie dochodzi do długich zadań JS oraz kiedy pojawia się największy element LCP. Jeśli ciężko namierzyć winowajcę, włącz dodatkowy trace i przeanalizuj go w Performance Panel DevTools.

Analiza, metryki i wizualizacja wyników

Interpretacja metryk krok po kroku

• LCP: najcięższy element nad linią zaniku (obraz/hero text). Optymalizuj: kompresja obrazów, preload kluczowego hero, serwowanie w next-gen (AVIF/WebP), skrócenie TTFB.
• INP: responsywność na interakcje. Skracaj długie zadania JS, dziel bundel, używaj schedulerów (requestIdleCallback/rozbicie na mikro-zadania), lazy-load ciężkich modułów.
• CLS: skoki layoutu. Rezerwuj wymiary dla obrazów/iframes, ustaw font-display: swap, unikaj wtrącania dynamicznych banerów bez miejsca.
• TBT: czas blokowania głównego wątku w lab. Koreluje z INP – zmniejsz JS, unikaj ciężkich synchronizacji, przenieś prace na web workers.
• FCP: pierwsze malowanie. Minimalizuj CSS-blocking, inline krytyczny CSS, eliminuj nieużywane style.

Powiązania: poprawa TBT często pcha w górę INP; zmniejszenie TTFB i optymalizacja obrazów zwykle poprawia LCP i FCP. W danych terenowych przeglądaj rozkłady percentyli (p75) w panelu CrUX lub Search Console, bo progi „dobry/umiarkowany/zły” bazują na p75.

Porównywanie wyników i trendy

• Przechowuj metryki i score wraz z timestamp, commit SHA i wersją aplikacji.
• Porównuj medianę z 3–5 przebiegów dla każdego URL.
• Wykreślaj wykresy: LCP/INP/CLS w czasie, łącząc dema (prod/stage) z release notes – łatwiej skorelować skoki z konkretną zmianą.

Jeśli wyniki fluktuują, sprawdź: obciążenie serwera, zmiany w cache, nowe skrypty tag managera lub A/B testing. Zadbaj o stałą konfigurację throttlingu, aby laboratorium było powtarzalne.

Wizualizacja i dashboardy

• Prosty CSV: wyciągnij z JSON kluczowe pola (score, LCP, INP, CLS, FCP, TBT) i wczytaj do arkusza.
• Bazy danych: trwale przechowuj JSON w S3/GCS, a wybrane metryki w BigQuery; stamtąd podłącz Looker Studio do regularnych wykresów.
• Alerty: gdy score spadnie o X lub LCP przekroczy próg, wyślij powiadomienie na Slack/Email (Cloud Functions/Lambda lub webhook z pipeline).

Najczęstsze błędy i ich weryfikacja

• Niestabilne środowisko testowe: zmienny CPU, inne rozszerzenia, niestandardowe proxy. Rozwiązanie: headless, stałe maszyny, kontenery.
• Kolidujące eksperymenty: testy A/B, skrypty marketingowe ładowane losowo. Rozwiązanie: osobny profil lub środowisko bez tagów, albo parametryzacja requestów.
• Przedwczesne wnioski z jednego przebiegu: uśredniaj, trzymaj serie czasowe.
• Pominięcie danych terenowych: wysokie wyniki lab nie gwarantują dobrego p75. Zawsze zestawiaj wyniki z danymi real-user (panel Search Console, raporty CrUX).

Mapowanie zaleceń na konkretne zadania

• „Reduce JavaScript execution time” → podziel bundel, tree-shaking, code-splitting, usuwanie nieużywanego kodu.
• „Eliminate render-blocking resources” → critical CSS inline, defer/async dla skryptów, consolidate CSS.
• „Serve images in next-gen formats” → pipeline do AVIF/WebP, automatyczna transformacja na brzegu CDN.
• „Preload key requests” → rel=preload dla fontów i hero image; pilnuj priorytetów zasobów.

Różnice środowisk: lokalnie vs produkcja

Lokalny build może być szybszy (mniej tagów, brak reklam, bliskość serwera). Zawsze utrzymuj testy na produkcji lub na stagingu odwzorowującym produkcję: ta sama konfiguracja cache, identyczne nagłówki, ten sam region. Jeżeli ruch jest globalny, uruchamiaj cykle per region (np. EU/US/APAC) i porównuj wyniki – metryki w USA mogą różnić się od EU przez routing i położenie węzłów CDN.

Łączenie wyników lab i field

Scenariusz pracy:

• Sprawdź dane terenowe (p75 LCP/INP/CLS) – jeśli problematyczne, wybierz strony o największym ruchu.
• Uruchom testy lab na tych URL-ach, aby zidentyfikować konkretne zasoby/fragmenty kodu.
• Wdróż poprawki i zweryfikuj regresję w lab.
• Obserwuj zmiany w danych terenowych (aktualizacja bywa opóźniona – zwykle dni/tydzień).

Praktyczny przepływ pracy end-to-end

1) Zbierasz listę kluczowych URL. 2) Budujesz skrypt CLI uruchamiający Lighthouse dla mobile i desktop, 3 przebiegi każdy, zapis JSON/HTML. 3) Pipeline w CI/CD porównuje wyniki z budżetami i zatrzymuje wdrożenie przy regresji. 4) JSON trafia do magazynu i jest parsowany do CSV/BigQuery. 5) Dashboard rysuje trendy LCP/INP/CLS/TBT/score per URL i środowisko. 6) Alerty powiadamiają o skokach. 7) Co sprint utrwalasz rekomendacje jako zadania w backlogu.

Rozszerzenia i alternatywy

• Konfiguracja Lighthouse (custom config) – wyłączanie/łączenie audytów, własne ustawienia throttlingu.
• Wtyczki i skanery map witryny – automatyczne zbieranie URL.
• Integracje z monitorowaniem syntetycznym – uruchamianie testów z wielu punktów świata o stałych parametrach.

Na koniec pamiętaj: raport to nie wyrok, a wskazówka. Metryki zmieniają się wraz z kodem, ruch rośnie, biblioteki ewoluują. Utrzymuj proces, a nie jednorazowy wynik – i świadomie wykorzystuj sygnały z Lighthouse, danych PSI oraz baz real-user, by priorytetyzować prace dające największy wpływ na doświadczenie i konwersje.