Lighthouse
Google Lighthouse를 실행하여 웹 품질을 측정하고, 수정 사항이 실제로 지표를 개선했는지 검증합니다. Lighthouse는 URL을 감사하여 Performance(성능), Accessibility(접근성), SEO, Best Practices(모범 사례) 카테고리별로 0–100점 점수와 특정 지침을 제공하는 실패한 감사 목록을 반환합니다.
이 스킬을 사용해야 할 때
이 스킬은 측정합니다. 형제 품질 스킬이 수정합니다. 워크플로는 루프입니다:
측정 (이 스킬) → 수정 (성능 / 접근성 / SEO / 모범 사례) → 재측정
이 스킬이 필요할 때: 기준 점수 확인, 특정 실패 감사 항목 파악, 성능 예산 설정, CI에서 빌드 게이트, 또는 변경 사항이 지표를 개선(또는 악화)했는지 증명합니다. 개선 사항을 추측하지 말고 — 측정하고, 한 가지를 변경한 후, 다시 측정하세요.
작동 방식
- 대상 URL 선택 — 배포된 URL 또는 로컬 개발/미리보기 서버 (
http://localhost:3000). - Lighthouse 실행 —
scripts/run-lighthouse.sh <url>사용을 권장합니다. 여러 번 실행하고 중앙값을 취하며, 컴팩트 JSON을 내보냅니다 (전체 보고서는 너무 커서 컨텍스트 낭비). - JSON에서 카테고리 점수 + 실패 감사 항목 읽기.
- 각 실패 감사 항목을 관련 품질 스킬을 사용한 수정 사항과 매핑.
- 재실행하고 전후 차이 보고.
설치 및 실행 (CLI)
Lighthouse 문서는 전역 설치를 권장합니다 (Node 22 LTS+ 필요). 또한 로컬 Chrome/Chromium이 설치되어 있어야 합니다:
npm install -g lighthouse
# 또는: yarn global add lighthouse
lighthouse https://example.com --view # 기본 실행; --view는 HTML 보고서 열기
Lighthouse는 설치된 Chrome을 자동 감지합니다. CHROME_PATH 환경 변수로 특정 바이너리를 지정할 수 있습니다.
전역 설치 없이 빠르게 한 번 실행하려면 npx lighthouse <url>도 작동합니다 — 공식 문서는 전역 설치만 다루지만, 게시된 CLI 바이너리는 이를 지원합니다.
에이전트용 기계 판독 가능 실행 (JSON 파일, quiet, 헤드리스):
npx lighthouse https://example.com \
--quiet \
--chrome-flags="--headless=new" \
--only-categories=performance,accessibility,seo,best-practices \
--output=json --output-path=./lh.json
래퍼 스크립트 (권장)
scripts/run-lighthouse.sh는 CLI를 래핑하여 N번 실행하고 중앙값 실행을 선택합니다 (Lighthouse 자체 권장 사항으로 변동성 감소). 그리고 stdout에 컴팩트 JSON만 출력합니다 — 카테고리 점수와 실패한 감사 항목만 포함합니다. 사람이 읽는 로그는 stderr로 출력됩니다.
# 사용법: run-lighthouse.sh <url> [runs] [categories]
skills/lighthouse/scripts/run-lighthouse.sh https://example.com 3
skills/lighthouse/scripts/run-lighthouse.sh http://localhost:3000 5 performance,accessibility
출력 예시:
{
"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" }
]
}
주요 플래그
| 플래그 | 목적 |
|---|---|
| `--output=json | html |
--output-path=<path> | 보고서 저장 경로 |
--only-categories=… | performance,accessibility,seo,best-practices로 제한 |
--preset=desktop | 데스크톱 설정 (기본값은 모바일: 에뮬레이션된 중간급 폰 + 느린 4G) |
--chrome-flags="--headless=new" | 헤드리스 실행 (CI/서버) |
--budget-path=budget.json | 성능 예산 적용 (LightWallet) |
| `--throttling-method=simulate | devtools |
--quiet | 진행 로그 억제 |
--view | 완료 후 HTML 보고서 열기 |
JSON 읽기
점수는 categories 아래에 0–1 실수(float)로 표시됩니다. 감사 세부 정보는 audits 아래에 있습니다.
# 카테고리 점수 (0–1) → 익숙한 점수로 100 곱하기
jq '.categories | to_entries | map({(.key): (.value.score)}) | add' lh.json
# Core Web Vitals 실험실 값
jq '.audits | {
LCP: .["largest-contentful-paint"].displayValue,
CLS: .["cumulative-layout-shift"].displayValue,
TBT: .["total-blocking-time"].displayValue
}' lh.json
# 조치가 필요한 실패/기회 감사 항목
jq '[.audits[] | select(.score != null and .score < 0.9)
| {id, score, displayValue}]' lh.json
성능 예산 (LightWallet)
자산 또는 타이밍이 임계값을 초과하면 실행을 실패 처리합니다. 이 스킬과 함께 편집 가능한 examples/budget.json가 제공됩니다. 형태는 다음과 같습니다:
[
{
"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
크기는 KB, 타이밍은 ms 단위입니다. 예산 결과는 JSON의 performance-budget 및 timing-budget 감사 항목에 포함됩니다.
실험실 vs 현장 — 숫자를 신뢰하기 전에 읽어야 할 내용
Lighthouse는 실험실(lab) 도구입니다: 합성 로드 한 번, 에뮬레이션된 하드웨어, 시뮬레이션된 스로틀링. 재현 가능하고 회귀를 잡는 데 좋지만, 실제 사용자가 경험하는 것과는 다릅니다.
- 변동성은 현실입니다. 단일 실행은 ±5–10점 정도 흔들릴 수 있습니다. 최소 3번 실행하고 중앙값을 취하세요 (래퍼 스크립트가 이렇게 합니다).
- 실제 사용자 데이터가 필요하면 현장(field) 소스를 사용하세요: CrUX, PageSpeed Insights (실험실 + 현장 데이터 모두 표시), Search Console의 Core Web Vitals 보고서, 또는 분석 도구에 보고하는
web-vitals라이브러리. - INP는 단일 Lighthouse 로드로 측정할 수 없습니다 — 실제 상호작용이 필요합니다. Lighthouse는 Total Blocking Time (TBT)을 실험실 프록시로 보고합니다. 현장 INP를 진실의 원천으로 취급하세요.
Lighthouse v13 참고 (Insight Audits)
v13부터 (2025년 10월+), Lighthouse는 Performance를 Insight Audits로 마이그레이션했습니다. 여러 레거시 기회 감사 ID가 병합되거나 제거되었습니다 (예: CLS 관련 감사 → cls-culprits-insight, 이미지 감사 → image-delivery-insight). 조언 자체는 변경되지 않았으며, 감사 ID와 보고서 그룹화만 변경되었습니다. 이전 보고서를 구문 분석할 때는 모순이 아닌 상위 집합으로 취급하세요. CI에서 Lighthouse 버전을 고정하여 사용하는 감사 ID가 안정적으로 유지되도록 하세요.
Performance 점수 구성 방식
Performance 점수는 실험실 지표의 가중치 혼합입니다 (버전 간 가중치 변동). 최근 버전 기준 주요 지표는 대략 다음과 같습니다:
| 지표 | 대략적 가중치 |
|---|---|
| Total Blocking Time (TBT) | ~30% |
| Largest Contentful Paint (LCP) | ~25% |
| Cumulative Layout Shift (CLS) | ~25% |
| First Contentful Paint (FCP) | ~10% |
| Speed Index | ~10% |
TBT/LCP/CLS가 지배적이므로, 이들을 수정하면 점수가 가장 많이 움직입니다. Lighthouse 점수 계산기를 사용하여 지표 변경이 점수에 어떻게 매핑되는지 정확히 확인하세요.
CI 및 프로그래매틱 API
집중을 위해 참조 문서에 보관합니다:
- 지속적 통합 —
@lhci/cli,lighthouserc.js어설션, GitHub Actions 워크플로: references/CI.md - 프로그래매틱 (Node) API —
chrome-launcher로 Lighthouse를 구동하여 사용자 정의 흐름, 사용자 플로우, 대량 실행: references/PROGRAMMATIC-API.md
감사 항목을 수정 사항에 매핑
| Lighthouse 카테고리 | 수정 스킬 |
|---|---|
| Performance / Core Web Vitals | 성능 또는 Core Web Vitals 스킬 |
| Accessibility | 접근성 / WCAG 스킬 |
| SEO | SEO 스킬 |
| Best Practices | 보안 / 모범 사례 스킬 |
이 스킬을 addyosmani/web-quality-skills과 함께 사용하여 측정-수정 루프를 완성하세요.