---
id: wiki-2026-0508-lighthouse
title: Lighthouse
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Google Lighthouse, Lighthouse CI, LHCI]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [web-performance, lighthouse, lhci, audit, cwv, treosh]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack: { language: js, framework: lighthouse/lhci }
---

# Lighthouse

## 매 한 줄
> **"매 lab metric 의 표준"**. Performance/A11y/SEO/Best Practices/PWA 5 카테고리 lab 감사, CI 게이트로 회귀 차단.

## 매 핵심
### 매 lab vs field
- **Lighthouse = lab**: 통제된 환경, 한 번 실행, deterministic-ish
- **CrUX/RUM = field**: 실 사용자, 분포, p75
- 둘 다 필요. Lab 은 회귀 catch, field 는 진실

### 매 카테고리
- Performance (LCP/CLS/TBT/SI/FCP) — TBT 가 lab proxy for INP
- Accessibility (axe-core 기반)
- Best Practices (HTTPS, console error, ...)
- SEO
- PWA (deprecated 진행 중)

### 매 응용
1. PR 마다 LHCI 게이트
2. Custom audit (회사 정책)
3. Multi-page coverage (여러 URL)
4. Budgets (size, count)
5. Treosh GitHub Action 으로 PR 코멘트

## 💻 패턴

### Pattern 1: CLI 기본
```bash
npm i -g lighthouse
lighthouse https://example.com \
  --output=json --output=html \
  --output-path=./report \
  --chrome-flags="--headless"
```

### Pattern 2: LHCI 설정
```js
// lighthouserc.cjs
module.exports = {
  ci: {
    collect: {
      url: ["http://localhost:3000/", "http://localhost:3000/about"],
      numberOfRuns: 3,
      startServerCommand: "npm run start",
    },
    assert: {
      assertions: {
        "categories:performance": ["error", { minScore: 0.9 }],
        "categories:accessibility": ["error", { minScore: 0.95 }],
        "largest-contentful-paint": ["error", { maxNumericValue: 2500 }],
        "cumulative-layout-shift": ["error", { maxNumericValue: 0.1 }],
      },
    },
    upload: { target: "temporary-public-storage" },
  },
};
```
```bash
npx lhci autorun
```

### Pattern 3: Treosh GitHub Action
```yaml
# .github/workflows/lhci.yml
- uses: treosh/lighthouse-ci-action@v12
  with:
    urls: |
      https://staging.example.com
      https://staging.example.com/products
    configPath: ./lighthouserc.cjs
    uploadArtifacts: true
    temporaryPublicStorage: true
```

### Pattern 4: Performance budget
```json
// budgets.json
[{
  "path": "/*",
  "resourceSizes": [
    { "resourceType": "script", "budget": 200 },
    { "resourceType": "image", "budget": 300 },
    { "resourceType": "total",  "budget": 800 }
  ],
  "resourceCounts": [
    { "resourceType": "third-party", "budget": 10 }
  ]
}]
```

### Pattern 5: Custom audit
```js
// custom-audit.js
const { Audit } = require("lighthouse");
class NoConsoleErrorAudit extends Audit {
  static get meta() {
    return { id: "no-console-error", title: "No console errors", scoreDisplayMode: "binary",
             requiredArtifacts: ["ConsoleMessages"] };
  }
  static audit(artifacts) {
    const errors = artifacts.ConsoleMessages.filter(m => m.level === "error");
    return { score: errors.length === 0 ? 1 : 0,
             details: { type: "table", items: errors } };
  }
}
module.exports = NoConsoleErrorAudit;
```

### Pattern 6: Programmatic API
```js
import lighthouse from "lighthouse";
import * as chromeLauncher from "chrome-launcher";

const chrome = await chromeLauncher.launch({ chromeFlags: ["--headless"] });
const result = await lighthouse("https://example.com", {
  port: chrome.port, output: "json", onlyCategories: ["performance"],
});
console.log(result.lhr.categories.performance.score);
await chrome.kill();
```

### Pattern 7: Multi-config (mobile + desktop)
```bash
lhci autorun --collect.settings.preset=desktop  # desktop
lhci autorun                                     # default mobile
```

## 매 결정 기준

| 상황 | Tool |
|---|---|
| Lab CI 게이트 | Lighthouse CI |
| 실제 사용자 측정 | RUM (web-vitals.js) |
| INP 진짜 디버깅 | LoAF (lab Lighthouse 만으론 부족) |
| Multi-page audit | LHCI urls[] |
| 빠른 1회 audit | Chrome DevTools Lighthouse panel |

**기본값**: LHCI + treosh action + budgets, 회귀시 PR block, RUM 으로 field 보완.

## 🔗 Graph
- 부모: [[Web_Performance]]
- 변형: [[PageSpeed Insights]]
- 응용: [[Core Web Vitals Optimization (INP, LCP, CLS)|Core_Web_Vitals]]
- Adjacent: [[Long Animation Frames API]], [[RUM]]

## 🤖 LLM 활용
**언제**: Lighthouse JSON 결과 → 우선순위 issue 정리, 해결 PR 초안.
**언제 X**: deterministic threshold (assertion config 직접 작성이 명확), 회귀 진단 (LoAF/profiler 가 정확).

## ❌ 안티패턴
- Lab 점수만 보고 production 판단 → field (CrUX) 다름
- 1회 실행으로 결정 → variance 큼, numberOfRuns >= 3
- Localhost CPU/network throttle 무시 → 실 환경 다른 결과
- Score 90 = "끝" → metric 자체 (LCP/CLS) 가 진짜 목표
- Custom audit 없이 회사 정책 강제 안 함 → 일관성 부재

## 🧪 검증 / 중복
- Verified (Lighthouse docs, LHCI docs, treosh/lighthouse-ci-action). 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — LHCI + budgets + custom audit + treosh patterns |