Lighthouse CI 2026: teljesítménybüdzsé és Core Web Vitals ellenőrzés minden pull requestben

Frissítve: 2026. július 15.

A Lighthouse CI egy Google által fejlesztett CLI és GitHub Action, amivel minden pull requesten automatikusan lefuttathatod a Lighthouse audit-ot, teljesítménybüdzsét kényszeríthetsz ki, és blokkolhatod azokat a merge-öket, amelyek rontanak a Core Web Vitals metrikákon. 2026 közepén a @lhci/cli stabil verziója 0.15.x, ami a Lighthouse 12.6.1 motorra épül, és havonta közel 2 millió npm letöltést generál. Ez ma a de facto szabvány szintetikus teljesítménytesztelésre CI-ben.

• A Lighthouse CI (LHCI) a @lhci/cli csomagot használja, ami jelenleg 0.15.x verziónál tart, és a Lighthouse 12.6.1 motort futtatja.
• A lighthouserc.js vagy lighthouserc.json fájlban definiálod a collect, assert és upload lépéseket. Ezt olvassa a lhci autorun.
• A budget.json resource-alapú, míg az assertions numerikus metrikákra (LCP < 2500 ms, CLS < 0.1, TBT < 300 ms) képesek fail-t adni.
• GitHub Actions-be a treosh/lighthouse-ci-action@v12 a legkényelmesebb. A fetch-depth: 20 nélkül azonban a git-ancestor detekció eltörik.
• Legalább 3 futtatás mediánján asszertálj, különben a lab metrikák természetes zaja miatt flaky lesz a build.
• A Lighthouse CI szintetikus lab-adatokat ad. Csak RUM-mal együtt látod a valódi felhasználói képet.

Mi az a Lighthouse CI és mikor használjuk?

A Lighthouse CI (röviden LHCI) a Google Chrome csapatának hivatalos eszközkészlete arra, hogy a Lighthouse audit-ot ne kelljen kézzel, DevTools-ból lefuttatni minden deploy előtt. Ehelyett a @lhci/cli CLI a build pipeline része lesz: elindítja a headless Chrome-ot, betölti az általad megadott URL-eket vagy egy statikus dist könyvtárat, elvégzi a Lighthouse futtatást, majd asszertálja a definiált küszöböket. Ha a Performance score 0.9 alá esik, vagy az LCP átlépi a 2500 ms-ot, a lépés hibával kilép, és a GitHub PR-en piros pipa jelenik meg.

A legfontosabb komponensek. Először: a @lhci/cli parancssori eszköz, ami tartalmazza a collect, assert, upload és autorun alparancsokat. Másodszor: a lighthouserc.js vagy lighthouserc.json konfigurációs fájl. Végül opcionálisan a @lhci/server, ami hosszú távon tárolja a jelentéseket egy PostgreSQL vagy SQLite adatbázisban. A Lighthouse CI-t akkor érdemes bevetni, ha a csapatod merge-elés előtt objektíven akarja mérni a lab teljesítményt. Bevallom, én is akkor kezdtem el használni, amikor egy release során egy ártatlannak tűnő third-party script másnap 20 ponttal rontotta a Lighthouse Performance kategóriát. Utólag kiderült, hogy egy chat widget dobta be, amiről senki nem szólt.

Lighthouse CI 2026: verziók, függőségek, breaking change-ek

2026 júliusában a stabil verziószámok a következők: @lhci/cli 0.15.x, ami belül a lighthouse 12.6.1 motort használja, illetve a @lhci/utils és @lhci/server csomagok is 0.15.x-en vannak. A Lighthouse 12-es sorozat óta a total-blocking-time asszertálása lett a standard INP-proxy lab környezetben (mivel az INP-t csak valódi user interakcióval lehet mérni, RUM-ban), és a Speculation Rules-nak megjelent egy dedikált audit-ja is (uses-speculation-rules).

Két breaking change-re érdemes figyelni, ha régebbi (0.13.x vagy korábbi) setupról frissítesz. Először: a puppeteerScript hook átnevezésre került, most már puppeteer-script néven konfigurálod a lighthouserc.js-ben. Másodszor: a Node 16 támogatás megszűnt, legalább Node 18 LTS kell, de 20-at ajánlott használni. A verzió-pinning fontos. A @lhci/cli@latest helyett mindig fix minor verziót telepíts (pl. @lhci/[email protected]), mert a Lighthouse motor apró változásai (audit súlyok újrakalibrálása) 2-3 ponttal is elmozdíthatják a scoret, ami hamis regressziónak látszik. A hivatalos GitHub Actions integrációhoz a Google Chrome LHCI repository és a közösségi Treosh Lighthouse CI Action a két megbízható forrás.

Az első Lighthouse CI setup lépésről lépésre

Nézzük végig egy tipikus Vite, Next.js vagy Astro projekt LHCI beállítását. Először telepítsd a CLI-t dev függőségként, így a CI runner ugyanazt a verziót fogja használni, mint amit a fejlesztők lokálisan tesztelnek:

# A pontos verzió pinelése kötelező, látni fogod miért a "Flaky" szekcióban
npm install --save-dev @lhci/[email protected]

# Első próba: futtasd a healthcheckert, hogy meggyőződj arról,
# hogy a Chrome / Chromium megtalálható a rendszeren
npx lhci healthcheck --fatal

Ezután hozd létre a lighthouserc.js-t a repó gyökerében. A collect szakaszban kétféleképp dolgozhatsz: vagy egy már futó URL-t auditálsz (url), vagy egy statikus build könyvtárat (staticDistDir), amit az LHCI belül elindít egy egyszerű HTTP szerveren. A statikus mód a gyorsabb és determinisztikusabb, használd, ahol lehet:

// lighthouserc.js, a legegyszerűbb, mégis production-ready alap
export default {
  ci: {
    collect: {
      // A build kimeneti könyvtárad, LHCI serverld ki egy tempóra
      staticDistDir: './dist',
      // 3 futtatás, mediánt asszertálunk, kevesebb flakyre okot ad
      numberOfRuns: 3,
      // Csak a landing és a leggyakrabban látogatott aloldal
      url: ['/', '/blog/'],
      settings: {
        // Csak mobil formfactor, Google is így pontoz CrUX-ban
        preset: 'desktop', // vagy hagyd üresen mobilhoz
        chromeFlags: '--no-sandbox --headless=new',
      },
    },
    upload: {
      // Kezdéshez ingyenes: a Google által biztosított temp storage
      target: 'temporary-public-storage',
    },
  },
}

Az első npx lhci autorun futtatás után a konzolon egy publikus URL-t kapsz, ahol megtekintheted a teljes Lighthouse riportot. Ez a kezdeti baseline: itt látod, hogy a jelenlegi build milyen scoreokat produkál, és ez alapján tudsz értelmes küszöböket beállítani az assert szakaszban. Ne asszertálj kitalált célértékekre. Mindig a jelenlegi teljesítményhez kalibrálj.

Teljesítménybüdzsé (budget.json) konfigurálása

A teljesítménybüdzsé (performance budget) egy explicit szerződés a csapaton belül arról, mennyi adat, hány szkript és mekkora kép terhelheti az oldalt. A budget.json a Lighthouse által natívan értett formátum, és két dimenzió mentén korlátozhatsz: resourceSizes (kbyte-ban, resource-típusonként) és resourceCounts (darabszámban). Az LHCI a performance-budget auditba táplálja be, és ha bármelyik URL átlépi, a build fail-t ad.

// budget.json, a resource-alapú felső határok
[
  {
    "path": "/*",
    "resourceSizes": [
      { "resourceType": "document", "budget": 20 },
      { "resourceType": "stylesheet", "budget": 60 },
      { "resourceType": "script", "budget": 300 },
      { "resourceType": "image", "budget": 500 },
      { "resourceType": "font", "budget": 100 },
      { "resourceType": "third-party", "budget": 200 },
      { "resourceType": "total", "budget": 1500 }
    ],
    "resourceCounts": [
      { "resourceType": "third-party", "budget": 10 },
      { "resourceType": "script", "budget": 15 }
    ]
  },
  {
    "path": "/blog/*",
    "resourceSizes": [
      { "resourceType": "image", "budget": 800 }
    ]
  }
]

A path mezőben glob mintákat használhatsz, így külön küdzsét adhatsz a landingnek, a blogpostoknak és mondjuk a checkout flow-nak, ahol nyilván kevesebb third-party engedélyezett. A resourceType lehet document, stylesheet, script, image, media, font, third-party vagy total. Egy általános szabály: az image és a script a két legvalószínűbb regressziós forrás. A design csapat valakit egy ki nem optimalizált WebP-vel, a frontend csapat egy új analytics SDK-val.

A budget.json-t a lighthouserc.js-ben a collect.settings.budgetsPath-szal töltöd be, vagy a treosh/lighthouse-ci-action budgetPath inputjával. Ha csak resource-alapú korlátaid vannak, ez az egyszerűbb út. Bonyolultabb, metrika-alapú küszöbökhöz viszont az assertions szintaxis kell, amit a következő szekcióban tárgyalunk. A képek méretkorlátozásához a képoptimalizálás AVIF és WebP formátumokkal a kiindulópont, a budget csak a végeredményt méri, nem old meg semmit.

Core Web Vitals assertions a lighthouserc-ben

A resource budget-nél sokkal finomabb kontrollt adnak az assertions. Itt közvetlenül a Lighthouse audit-jaira és a Core Web Vitals metrikákra tudsz numerikus küszöböt adni, három szinten: off, warn (a build nem fail-el, de warning-ot ír), error (fail-el). A 2026-os "jó" Core Web Vitals sáv: LCP optimalizálás 2500 ms alá, CLS < 0.1, INP mérés 200 ms alá. Mivel az INP-t lab-ban nem lehet mérni (kell hozzá valós user interakció), a TBT (Total Blocking Time) < 300 ms a legjobb proxy. Ha itt átmész, a legtöbb esetben az INP is jó lesz production-ben.

// lighthouserc.js, production-ready assertions blokk
export default {
  ci: {
    collect: {
      staticDistDir: './dist',
      numberOfRuns: 3,
      url: ['/', '/pricing/', '/blog/'],
    },
    assert: {
      // A "no-pwa" preset kikapcsolja a PWA-specifikus audit-okat
      preset: 'lighthouse:no-pwa',
      assertions: {
        // Kategória-szintű scoreok, 0 és 1 közötti minScore
        'categories:performance': ['error', { minScore: 0.9 }],
        'categories:accessibility': ['error', { minScore: 0.95 }],
        'categories:best-practices': ['warn', { minScore: 0.9 }],
        'categories:seo': ['error', { minScore: 0.95 }],

        // Core Web Vitals metrikák, millisekundumban vagy pontszámban
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'total-blocking-time': ['error', { maxNumericValue: 300 }],
        'first-contentful-paint': ['warn', { maxNumericValue: 1800 }],
        'speed-index': ['warn', { maxNumericValue: 3400 }],

        // Resource-alapú finomhangolások az assertions-ön belül
        'resource-summary:script:size': ['error', { maxNumericValue: 300000 }],
        'resource-summary:image:size': ['warn', { maxNumericValue: 500000 }],
        'resource-summary:third-party:count': ['warn', { maxNumericValue: 12 }],

        // Kifejezetten irreleváns audit-ok kikapcsolása
        'uses-http2': 'off',
        'canonical': 'off',
      },
    },
    upload: { target: 'temporary-public-storage' },
  },
}

Néhány gyakorlati elv az assertions körül. Először: soha ne asszertálj olyan küszöbre, amit a jelenlegi build 90%-ban épp csak teljesít. Ha az LCP tipikusan 2400-2600 ms között ingadozik, akkor 2500 ms-os error asszertálással minden második build hamisan fog fail-elni. Inkább emeld a küszöböt 2800-ra, és tegyél a codebase-be egy külön issue-t az LCP optimalizálására. Másodszor: kezdd mindent warn-ként két hétig, gyűjtsd a jelentéseket, és utána váltsd át azokat error-ra, amelyek stabilnak bizonyulnak. Ez a "kalibrációs időszak" megelőzi, hogy a csapat elveszítse a Lighthouse CI-be vetett bizalmát az első 20 flaky fail után. Én személy szerint az első hónapban végig warn-on tartom, aztán szelektíven húzom fel a küszöböket.

Lighthouse CI integrálása GitHub Actions-be

A GitHub Actions integrációnak két útja van. Az egyik a @lhci/cli direkt hívása egy workflow lépésben, ami maximum kontrollt ad. A másik a közösségi treosh/lighthouse-ci-action@v12, ami elrejti a boilerplate-t: automatikusan feltölti az artifact-eket, PR statuszokat állít, és kezeli a Chromium telepítést. Kis-közepes projekteknek a treosh action a gyorsabb megoldás. Alul mindkét megközelítés production-ready példáját mutatjuk.

# .github/workflows/lighthouse.yml, treosh action, statikus build
name: Lighthouse CI
on:
  pull_request:
    branches: [main]
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # KRITIKUS: sekély checkout eltöri a git-ancestor detekciót
          fetch-depth: 20
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - name: Lighthouse CI audit
        uses: treosh/lighthouse-ci-action@v12
        with:
          # A build kimenete, amit az LHCI belül serverld ki
          configPath: './lighthouserc.js'
          budgetPath: './budget.json'
          uploadArtifacts: true
          temporaryPublicStorage: true
          runs: 3

Ha csak npm scriptet akarsz futtatni (pl. mert monorepo-ban vagy, és a Chromium már telepítve van a base image-ben), a manuális megközelítés is működik:

# .github/workflows/lighthouse-manual.yml, CLI-alapú, több kontrollal
name: Lighthouse CI
on: [pull_request]
jobs:
  lhci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 20 }
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: 'npm' }
      - run: npm ci
      - run: npm run build
      # A pontos LHCI verzió az npm cache-ből jön, nem globálisan
      - name: Run Lighthouse CI
        run: npx lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

A LHCI_GITHUB_APP_TOKEN egy külön GitHub App token, amit a Lighthouse CI GitHub App ad ki, ha a repóra rátelepíted. Ez fogja az egyes URL-ek melletti státuszcheckeket kirakni a PR-be, direkt linkkel a részletes riporthoz. Ne használj personal access tokent (PAT). A GitHub App tokenek 8 óránként lejárnak, és fine-grained scope-jaik vannak, ezért publikus repókban is biztonságosak. Ha a Lighthouse CI mellé end-to-end user flow méréseket is akarsz, olvasd el a Playwright teljesítménytesztek 2026-os útmutatót. A kettő együtt teljes lefedettséget ad.

Lighthouse CI vs Playwright: melyiket használjuk?

Ez a leggyakoribb kérdés, amikor egy csapat CI-teljesítménymérést vezet be. Röviden: a kettő nem alternatívája egymásnak, hanem komplementer. A Lighthouse CI szintetikus, single-page audit-ot ad a Google által súlyozott metrikákkal, pontosan azt méri, amit a Chrome UX Report és a Google Search Console lát. A Playwright viszont valós felhasználói flow-kat futtat (login, kosárba tesz, checkout), és képes az INP-t is valósan mérni a web-vitals.js-en keresztül. Az alábbi tábla a fő döntési dimenziókat foglalja össze.

Dimenzió	Lighthouse CI	Playwright (web-vitals-szel)
Elsődleges use case	Single-page lab audit, Google score	Multi-step user flow, valódi INP
Metrikák	LCP, CLS, TBT, FCP, SI, TTI + score	LCP, CLS, INP (valós), TTFB
INP mérés	Csak proxy (TBT)	Valós, click/tap eventből
Setup komplexitás	Alacsony (5 perc)	Közepes (30-60 perc)
Futási idő (3 URL)	~2 perc	~30-90 másodperc
Flakiness	Közepes (medián kell)	Alacsony (több sample)
PR kommentek	Beépített (GitHub App)	Custom action kell
Historikus adatok	@lhci/server	Custom megoldás

Az ajánlott stratégia: futtass Lighthouse CI-t minden PR-en 2-3 kritikus URL-en (landing, product, checkout landing), teljesítménybüdzsével és error-szintű CWV asszertálással. Emellett futtass Playwrightot a legkritikusabb 2-3 user flow-ra (regisztráció, checkout, keresés), és ott mérd az INP-t. A kettő együtt letakarja a "static page speed" és a "real interaction latency" világot is. Production-ben pedig már csak a RUM adatokkal a p75 percentileken kell összevetni, hogy a lab értékek ne térjenek el drasztikusan a field p75 értékektől.

LHCI Server és a történeti trendek

A temporary-public-storage upload target csak 7 napig őrzi meg a jelentéseket, és nincs benne trend-elemzés. Ha a csapatod hosszabb távon szeretné látni, hogyan alakul az LCP heteken át, telepítsd a @lhci/server-t. Ez egy Node.js szerver PostgreSQL vagy SQLite backenddel, ami minden build eredményét eltárolja, és egy webes UI-n megjeleníti a trendeket, PR-ek közti diffet, és a top regressziót okozó audit-okat.

# A LHCI Server elindítása egy Docker konténerben
docker run --publish 9001:9001 \
  --volume /var/lhci-data:/data \
  patrickhulce/lhci-server:0.15

A lighthouserc.js-ben ezután a upload.target-et állítsd át lhci-ra, és add meg a szerver URL-jét plusz egy build token-t (amit a szerver admin UI-ban generálsz). A szerver havonta 200-500 MB adatot tárol egy közepes forgalmú projektnél, tehát egy 2 GB-os EBS volume vagy hasonló méret elég. Az extra karbantartás cserébe: 6 hónapos historikus grafikonok, per-commit diff, és a Slack vagy Discord webhook integráció, ami akkor pingel, ha egy metrika 10%-nál nagyobbat mozdul.

Gyakori hibák és flaky assertions kezelése

A Lighthouse CI kettes számú frusztráció-forrása (az elsőt mindjárt írom) a flaky assertions. A lab metrikák természetüknél fogva zajosak: ugyanaz a build ugyanazon a runneren futtatva 5-10%-os szórással hozhat különböző LCP értékeket, mert a Chromium warmup, a runner CPU kontenció és a network stub finoman ingadozik. Két védelmi vonal van. Először: mindig numberOfRuns: 3 vagy 5, hogy mediánt asszertálj. Másodszor: az assertions küszöbeit ne a legjobb, hanem a p95-ös futtatott értékre kalibráld.

A második leggyakoribb hiba a Chromium indulási hiba GitHub Actions Ubuntu runneren. Két tünet szokott felbukkanni. Egyik a Failed to launch the browser process, ami majdnem mindig a hiányzó --no-sandbox flag miatt van. A másik a Timeout waiting for target to be ready, ami sekély RAM miatt jön, ha nagy oldalt tesztelsz (az ubuntu-latest runnernek 7 GB RAM-ja van, ami elég, de párhuzamos build-eknél kioszthatod magad alól). A megoldás: állítsd be a workflow-ban a concurrency group-ot, hogy egyszerre csak egy Lighthouse build fusson repónként. Végül, ha a build 3-4 percnél tovább tart, valószínűleg túl sok URL-t auditálsz. 2-3 kritikus oldal elég, a többit egy nightly, teljesebb LHCI run-ban futtasd, ami nem blokkolja a PR-eket. Ezt a hibát én is elkövettem az első projektemnél, ahol 12 URL-t akartam auditálni PR-enként. Két hét után mindenki utálta a Lighthouse CI-t.

Gyakran ismételt kérdések

Mi az a Lighthouse CI és miben különbözik a sima Lighthouse-tól?

A Lighthouse CI a Lighthouse audit-motort csomagolja be egy CI-barát CLI-be (@lhci/cli), amely automatizáltan futtat, asszertál küszöböket és feltölti a jelentéseket. A DevTools-ban futtatható sima Lighthouse egyszeri, kézi mérés; az LHCI ugyanezt teszi minden pull requesten és blokkolja a merge-t regresszió esetén.

Melyik Lighthouse CI verziót használjuk 2026-ban?

2026 közepén a stabil @lhci/cli 0.15.x, ami a Lighthouse 12.6.1 motort futtatja. Mindig pineld a minor verziót (@lhci/[email protected]), és Node 18+ szükséges, mivel a Node 16 támogatás megszűnt.

Milyen Core Web Vitals küszöböket állítsunk be az assertions-ben?

A "jó" 2026-os sáv: LCP < 2500 ms, CLS < 0.1, INP < 200 ms. Mivel az INP-t lab-ban nem lehet közvetlenül mérni, a TBT < 300 ms a legjobb proxy. Kezdd warn-ként, gyűjts 1-2 hét adatot, és csak azt válts error-ra, ami stabilnak bizonyul.

Miért fail-elnek véletlenszerűen a Lighthouse CI build-jeim?

A lab metrikák természetesen 5-10%-ot ingadoznak a runner CPU-terhelése miatt. Használj numberOfRuns: 3 vagy 5 futtatást, hogy mediánt asszertálj, és állítsd be a küszöböket a jelenlegi build p95-ös értékére, ne a legjobbra. A fetch-depth: 20 a checkout lépésnél is kötelező.

Lighthouse CI vagy Playwright, melyiket válasszam?

Mindkettőt. A Lighthouse CI single-page lab audit, ami a Google-scoreokat és a resource budget-et kényszeríti ki. A Playwright multi-step user flow-kat mér, és képes a valós INP-t is elkapni. Egy komplett CI-teljesítménystack mindkettőt tartalmazza, plusz RUM-ot production-ben.

Kell-e LHCI Server, vagy elég a temporary-public-storage?

Első 1-2 hónapban elég a temporary-public-storage, ami 7 napig őrzi a jelentéseket. Ha a csapat hosszú távú trendeket szeretne látni (heti/havi regressziót, per-commit diff-et), akkor telepítsd a @lhci/server-t egy 2 GB-os VPS-re vagy Docker konténerbe. Ekkor kapsz web UI-t, Slack webhookot és 6+ hónapos historikus adatot.