GoogleChrome/lighthouse 딥다이브
— "내 웹사이트, 얼마나 건강한가"를 자동으로 검진하는 도구

1한 줄 정체

Lighthouse는 웹페이지를 대상으로 하는 자동 건강검진기다. URL 하나를 주면 ① 실제 크롬 브라우저를 뒤에서 띄워 그 페이지를 로딩하고, ② 로딩되는 동안 벌어지는 일(네트워크 요청, 화면이 그려지는 순간, 자바스크립트 실행 시간 등)을 기록하고, ③ 그 기록을 미리 정해둔 171개의 검사 규칙(Audit)에 대입해 점수를 매기고, ④ 사람이 읽을 수 있는 리포트(HTML·JSON)로 뽑아준다.

리포트는 크게 네 개(+신규 하나) 카테고리로 나뉜다: Performance(성능), Accessibility(접근성 — 시각·청각 장애인도 쓸 수 있는가), Best Practices(웹 개발 모범 사례), SEO(검색엔진 최적화), 그리고 2026년에 새로 생긴 Agentic Browsing(AI 에이전트 대응력). 각 카테고리는 0~100점 게이지 하나로 요약된다.

중요한 점은 Lighthouse가 독립 실행형 앱이 아니라 재사용되는 엔진이라는 것이다. 크롬 개발자도구의 "Lighthouse" 탭, 구글의 PageSpeed Insights 웹사이트, 터미널의 lighthouse 명령어, Node.js 코드에서 쓰는 프로그래밍 API가 모두 저장소 core/ 아래의 같은 엔진 코드를 공유한다.

2왜 지금 주목받는가

Lighthouse는 2016년에 나온 오래된 프로젝트지만, 2026년 현재도 계속 주목받는 이유가 뚜렷하다. 크게 세 가지 흐름이 겹쳐 있다.

① Core Web Vitals가 "느낌"이 아니라 "숫자"가 됐다

구글은 Core Web Vitals(핵심 웹 바이탈)라는 세 가지 성능 지표 — LCP(가장 큰 콘텐츠가 그려지는 시각)·CLS(레이아웃이 갑자기 흔들리는 정도)·INP(사용자 조작에 반응하는 속도) — 를 검색 순위에도 영향을 주는 공식 지표로 삼았다. "우리 사이트 느린 것 같다"는 감이 아니라 구체적인 밀리초 숫자로 관리해야 하는 시대가 됐고, Lighthouse는 이 숫자를 재는 가장 표준적인 무료 도구다.

② "AI 에이전트가 웹을 읽는다"는 새로운 과제 — Agentic Browsing

실제 소스코드를 보면 2026년에 새로 생긴 agentic-browsing 카테고리와 webmcp-* 감사 규칙들을 확인할 수 있다(core/audits/webmcp-schema-validity.js 등, 저작권 표기 2026년). 이건 "사람이 아니라 AI 에이전트가 이 페이지를 방문했을 때 제대로 이해하고 조작할 수 있는가"를 검사하는 완전히 새로운 관점이다. /llms.txt 파일이 있는지 확인하는 감사, WebMCP(웹용 Model Context Protocol) 스키마가 올바른지 검증하는 감사가 대표적이다. "검색엔진 최적화(SEO)" 다음으로 "에이전트 최적화"라는 새 과제가 등장했음을 보여주는 신호다.

③ "한 번의 측정"이 아니라 "파이프라인에 박아 넣는" 문화

성능 예산(performance budget)을 CI(지속적 통합)에 넣어 "이 커밋이 페이지를 느리게 만들면 빌드를 막는다"는 문화가 자리잡으면서, Lighthouse는 사람이 가끔 눌러보는 도구에서 자동화 파이프라인의 부품으로 역할이 커졌다. Node API·CI 액션·Lighthouse CI 같은 주변 생태계가 이런 흐름을 뒷받침한다.

3무엇을 해결하나

Lighthouse 이전, 웹 성능·접근성 점검은 개발자가 직접 개발자도구를 열고, 눈으로 로딩을 지켜보고, 감으로 판단하는 일이 많았다. "이 페이지 느린 것 같다"는 말은 있어도 "왜 느린지, 얼마나 느린지, 무엇부터 고쳐야 하는지"를 숫자로 답하기는 어려웠다. Lighthouse가 푸는 문제는 크게 세 가지다.

① 체크리스트의 자동화

"이미지에 대체 텍스트가 있는가", "HTTPS를 쓰는가", "메타 description이 있는가" 같은 항목은 사람이 페이지마다 일일이 확인하기엔 지루하고 실수하기 쉽다. Lighthouse는 이런 171개 항목을 크롬으로 페이지를 열어본 뒤 기계적으로, 빠짐없이 확인한다.

② "몇 번을 재도 비슷한 숫자가 나오게" 만드는 재현성

같은 페이지라도 회선 상태·기기 성능에 따라 로딩 시간이 매번 다르게 느껴진다. Lighthouse는 가상의 느린 회선·느린 CPU를 시뮬레이션(뒤에서 설명할 Lantern)해서, 인터넷 환경이 다른 두 사람이 같은 페이지를 재도 비교적 비슷한 점수가 나오도록 만든다. 완벽하진 않지만(9번 섹션에서 한계도 다룬다), "감"보다는 훨씬 일관된 기준선을 제공한다.

③ "어디서든 같은 엔진" — 도구 파편화 방지

Lighthouse가 하나의 공용 엔진으로 자리잡으면서, 크롬 개발자도구·PageSpeed Insights·터미널 CLI·CI 파이프라인이 서로 다른 도구인데 같은 채점 기준을 쓰게 됐다. 이는 "이 도구에선 90점인데 저 도구에선 60점"이라는 혼란을 크게 줄여준다.

4전체 구조

실제 저장소를 열어보면 Lighthouse의 구조는 정확히 4단 파이프라인으로 나뉘어 있고, 각 단계가 폴더 하나씩과 정확히 대응한다. 이건 문서의 설명이 아니라 core/ 디렉터리를 직접 열어 확인한 사실이다.

즉 "수집(Gather) → 판정(Audit) → 점수화(Category/Scoring) → 보고(Report)"라는 4단계가 폴더 구조 그대로 드러난다. 각 단계는 다음 단계가 필요로 하는 딱 그만큼의 데이터만 넘겨주는 방식으로 느슨하게 연결돼 있어서, 예를 들어 "감사 규칙 하나만 새로 추가"하는 작업이 나머지 세 단계를 건드리지 않고 가능하다.

5핵심 설계 · 동작 원리

이 섹션이 이 문서에서 가장 두꺼운 이유는, Lighthouse의 진짜 가치가 "무엇을 검사하는가"보다 "어떻게 하면 브라우저를 매번 다르게 만들지 않고 일관되게 관찰할 것인가"라는 엔지니어링 문제를 정면으로 풀고 있기 때문이다. 하나씩 실제 코드로 확인해보자.

① Gatherer — "관찰만 하고 판단은 안 한다"는 원칙

core/gather/base-gatherer.js를 열어보면 모든 Gatherer가 상속하는 베이스 클래스가 놀랍도록 단순하다. startInstrumentation(관찰 시작) → startSensitiveInstrumentation(민감한 구간 관찰 시작) → stopSensitiveInstrumentation → stopInstrumentation(관찰 종료) → getArtifact(최종 데이터 반환), 이 다섯 개 메서드 뼈대뿐이다. "민감한(sensitive)" 계측을 따로 분리해둔 이유는 Lighthouse 자신이 페이지에 끼치는 영향을 최소화하려는 것 — 성능을 재는 도구 자신이 성능을 왜곡하면 안 되기 때문이다.

// core/gather/base-gatherer.js (뼈대만 발췌)
class BaseGatherer {
  meta = {supportedModes: []};  // navigation / timespan / snapshot 중 어디서 쓰이는지

  startInstrumentation(passContext) { }          // 관찰 시작
  startSensitiveInstrumentation(passContext) { }  // 성능에 민감한 구간만 별도로 시작
  stopSensitiveInstrumentation(passContext) { }
  stopInstrumentation(passContext) { }
  getArtifact(passContext) { }                    // 최종 데이터 반환
}

실제로 core/gather/gatherers/ 아래에는 accessibility.js(axe-core 실행 결과)·console-messages.js(콘솔 로그)·trace.js(성능 추적 파일)·image-elements.js(이미지 태그 정보) 등 약 30여 개의 Gatherer가 있으며, 각자 정확히 한 가지 원재료만 책임진다. 하나의 페이지 로딩 동안 이 Gatherer들이 동시에 관찰을 진행한다.

② Audit — 점수는 항상 0~1 사이, "적용 불가"라는 특수 처리가 있다

core/audits/audit.js의 Audit.SCORING_MODES를 보면 각 감사는 NUMERIC(숫자 기준 점수)·BINARY(통과/실패)·NOT_APPLICABLE(이 페이지엔 해당 없음)·INFORMATIVE(정보 제공용, 채점 안 함)·MANUAL(사람이 직접 확인해야 함) 중 하나로 동작한다. NOT_APPLICABLE·INFORMATIVE·MANUAL인 항목은 가중치가 강제로 0이 돼 최종 점수 계산에서 빠진다 — 예를 들어 페이지에 표(table)가 없으면 "표 관련 접근성 감사"는 채점에서 제외되고 리포트엔 "해당 없음"으로만 표시된다.

③ Category/Scoring — 성능 점수의 실제 가중치 (문서보다 코드가 먼저다)

카테고리 점수가 어떻게 계산되는지는 core/scoring.js의 ReportScoring.arithmeticMean() 딱 한 함수에 담겨 있다. 원리는 단순한 가중평균이다: 감사마다 정해진 weight(가중치)를 곱해 합산하고, 가중치 합으로 나눈다. 앞서 말한 대로 "해당 없음" 판정을 받은 감사는 가중치가 0으로 바뀌어 이 계산에서 자동으로 빠진다.

// core/scoring.js — 가중평균 산식 (실제 코드 그대로)
static arithmeticMean(items) {
  items = items.filter(item => item.weight > 0);      // 가중치 0은 애초에 제외
  if (items.some(item => item.score === null)) return null;

  const results = items.reduce((result, item) => ({
    weight: result.weight + item.weight,
    sum: result.sum + item.score * item.weight,
  }), {weight: 0, sum: 0});

  return clampTo2Decimals(results.sum / results.weight || 0);
}

그리고 core/config/default-config.js에서 실제로 확인한 2026년 기준 Performance(성능) 카테고리의 실제 가중치는 아래 표와 같다. 블로그 글이나 오래된 강의 자료에는 다른 숫자가 적혀 있을 수 있는데, 이 가중치는 종종 바뀌므로 진짜 진실은 항상 이 파일 하나라는 점이 중요하다.

④ 세 가지 실행 모드 — navigation · timespan · snapshot

core/gather/ 아래에는 navigation-runner.js·timespan-runner.js·snapshot-runner.js 세 개의 실행 진입점이 나란히 있다. 예전 Lighthouse는 "페이지를 새로 열어서 처음부터 로딩을 재는" 것만 할 수 있었지만, 지금은 사용자 흐름(User Flow) 전체를 다룰 수 있다.

이 세 모드를 이어붙여 하나의 시나리오로 만드는 게 core/user-flow.js의 UserFlow 클래스다. "홈페이지 로딩(navigation) → 검색어 입력(timespan) → 검색 결과 모달 확인(snapshot)"처럼, 실제 사용자가 겪는 다단계 흐름을 하나의 리포트로 묶어낼 수 있다. 이는 로그인 후 화면, SPA(단일 페이지 앱)의 페이지 전환처럼 "새로고침 없는" 상호작용을 재는 데 필수적이다.

⑤ Lantern 시뮬레이션 — "진짜 3G가 아니라 계산으로 만든 3G"

Lighthouse의 기본 설정(core/config/constants.js 실측)은 throttlingMethod: 'simulate'다. 이건 실제로 회선 속도를 느리게 만드는 게 아니라, 빠른 회선으로 페이지를 한 번 받아본 뒤 "만약 느린 회선이었다면 각 리소스가 언제 도착했을지"를 그래프 알고리즘으로 계산하는 방식이다. 이 계산 엔진의 이름이 Lantern이다.

기본 프로필은 코드에서 직접 확인한 값 기준으로 왕복 지연시간(RTT) 150ms · 다운로드 속도 1.6Mbps · CPU 4배 느리게(cpuSlowdownMultiplier: 4)다(모바일 기준 "Slow 4G" 프로필). 페이지의 리소스 요청 관계를 하나의 의존성 그래프(dependency graph)로 만든 뒤, 이 그래프 위에서 네트워크·CPU 시뮬레이션을 동시에 굴려 "몇 초에 무엇이 그려질지"를 예측한다.

⑥ CDP 사용 방식 — "이벤트 구독은 항상 enable보다 먼저"

Lighthouse는 puppeteer-core로 크롬에 연결한 뒤, core/gather/driver.js에서 page.target().createCDPSession()으로 저수준 CDP 세션을 직접 얻는다. 그 뒤 session.sendCommand('Page.enable')·session.sendCommand('Network.getResponseBody', ...)처럼 CDP 명령을 직접 호출한다. 즉 Puppeteer는 브라우저를 켜고 붙는 얇은 껍데기로만 쓰고, 실제 관찰은 CDP를 날것 그대로 다룬다.

docs/architecture.md가 공식적으로 남긴 함정 하나: CDP의 Domain.enable()은 먼저 호출한 뒤 이벤트를 구독하면 그 사이에 발생한 이벤트를 놓친다. 반드시 이벤트 리스너를 먼저 걸어두고 enable을 나중에 불러야 한다 — Node.js는 콜백을 동기적으로 등록하므로 이 순서가 실제로 안전하다.

// docs/architecture.md 에 실제로 적힌 경고 예시
// 이렇게 하면 안 됨 — enable 이후에 리스너를 걸면 그 틈의 이벤트를 놓친다
session.sendCommand('Security.enable').then(_ => {
  session.on('Security.securityStateChanged', state => { /* ... */ });
});

// 이렇게 해야 함 — 리스너를 먼저, enable을 나중에
session.on('Security.securityStateChanged', state => { /* ... */ });
session.sendCommand('Security.enable');

⑦ 랩(Lab) 데이터 vs 필드(Field) 데이터 — 이 저장소는 "랩" 전용이다

Lighthouse가 만드는 모든 점수는 랩 데이터(lab data)다 — 즉 "지금 이 순간, 이 한 대의 크롬으로, 한 번 시뮬레이션해서" 잰 값이다. 반면 실제 방문자 수백~수만 명의 진짜 로딩 경험을 모은 값은 필드 데이터(field data)라 부르고, 구글은 이를 CrUX(Chrome User Experience Report)라는 별도 데이터셋으로 따로 수집한다. report/renderer/report-utils.js에 실제로 "이 데이터는 여러 세션을 요약하는 필드 데이터와 달리, 단일 세션 하나에서 나온 것"이라는 안내 문구가 박혀 있을 만큼, Lighthouse 스스로도 이 차이를 리포트에 명시한다.

⑧ 신규 — Agentic Browsing 카테고리(2026년 추가)

core/config/default-config.js의 'agentic-browsing' 항목과 core/audits/webmcp-schema-validity.js·webmcp-registered-tools.js·webmcp-form-coverage.js(파일 저작권 표기 2026년) 감사들이 이 새 카테고리를 구성한다. 대응하는 수집기 core/gather/gatherers/agentic/llms-txt.js는 페이지의 /llms.txt 경로를 직접 요청해 이 사이트가 AI 크롤러/에이전트를 위한 안내 파일을 제공하는지 확인한다. 사람이 보는 SEO 다음으로 "AI 에이전트가 보는 접근성"을 재는 시대가 코드로 이미 시작됐다는 실물 증거다.

6기술 스택 · 의존성

Lighthouse는 순수 Node.js(≥ 22.19) 프로그램이다. 프론트엔드 프레임워크 없이 자바스크립트/TypeScript 타입 주석만으로 작성돼 있고, 실행 시점에 별도의 크롬 브라우저가 필요하다. package.json에서 직접 확인한 런타임 의존성(26개) 중 핵심만 추리면 다음과 같다.

개발 의존성(devDependencies)은 79개로, 빌드 도구(esbuild 계열)·타입 검사(TypeScript)·테스트(Mocha)·문서 생성 도구가 대부분을 차지한다. 라이선스는 Apache License 2.0이며, 저장소 전역에 이 라이선스 헤더가 파일마다 반복해서 박혀 있다.

7설치 · 요구사항

8실제 사용 흐름

npx lighthouse https://example.com --view

import lighthouse from 'lighthouse';
import * as chromeLauncher from 'chrome-launcher';

const chrome = await chromeLauncher.launch({chromeFlags: ['--headless=new']});
const result = await lighthouse('https://example.com', {port: chrome.port});
console.log(result.lhr.categories.performance.score * 100);  // 0~100점
await chrome.kill();

// 개념 설명용 의사코드 — 실제로는 puppeteer의 page와 함께 사용
flow.startNavigation()   // 1단계: 홈페이지 로딩(navigation 모드)
flow.startTimespan()     // 2단계: 검색창 타이핑 동안 반응성(timespan 모드)
flow.snapshot()          // 3단계: 검색 결과 모달의 접근성(snapshot 모드)
flow.generateReport()    // 세 단계를 하나의 리포트로 합쳐서 출력

9함정 · 오해 방지

10대안 비교

11정리 · 누가 쓰면 좋은가

Lighthouse는 한 문장으로 "웹페이지의 성능·접근성·모범 사례·SEO를 크롬으로 직접 실행해보고 자동 채점하는 오픈소스 엔진"이다. 그 채점은 Gatherer(수집) → Audit(판정) → Category/Scoring(점수화) → Report(보고)라는 4단 파이프라인으로 구현돼 있고, 네트워크·CPU를 진짜로 늦추는 대신 Lantern이라는 그래프 시뮬레이션으로 예측한다는 게 가장 독특한 설계 결정이다. 2026년 들어서는 성능·접근성·SEO를 넘어 "AI 에이전트가 이 페이지를 이해할 수 있는가"까지 검사하는 Agentic Browsing 카테고리로 영역을 넓히고 있다.

다만 앞서 다룬 함정들 — 점수의 실행마다의 변동성, 랩 데이터와 실제 사용자 경험의 차이, 모바일 기본값 — 을 모르고 쓰면 숫자 하나에 일희일비하기 쉽다. Lighthouse는 "정답을 알려주는 도구"가 아니라 "어디를 봐야 할지 알려주는 체크리스트"로 다루는 것이 가장 안전한 사용법이다.