본문으로 건너뛰기

Web Perf · EP 04

Lighthouse CI로 성능 예산 지키기

성능 예산을 코드에 강제하는 방법을 정리했습니다. Lighthouse CI 설정부터 PR을 막는 게이트까지 실무에서 쓰는 구성을 소개합니다.

· 3분 읽기

Lighthouse CI로 성능 예산 지키기

개요

성능 최적화는 한번 해서 끝나는 작업이 아니었습니다. QA를 통과했던 페이지도 몇 주 만에 이미지 몇 장과 배너 스크립트 하나로 다시 느려졌고, “왜 이렇게 느려요?”라는 말을 들을 때면 원인을 다시 찾아야 했습니다. 이 글에서는 성능 예산(performance budget)을 문서가 아니라 CI 설정으로 강제해서, 성능이 나빠지는 변경이 메인 브랜치에 들어오지 못하게 만드는 방법을 정리합니다.

성능 예산이란

성능 예산은 페이지가 지켜야 할 정량 지표의 상한선입니다. 예를 들어 이런 식으로 정합니다.

  • LCP 2.5초 이하
  • JS 번들(초기 로드) 200KB(gzip) 이하
  • 이미지 총 1MB 이하

핵심은 “빠르게 만들자”라는 막연한 목표가 아니라, 숫자로 합의된 선을 넘으면 병합을 못하게 만드는 것입니다. 예산은 Lighthouse가 측정하는 카테고리 점수(LCP, TBT, CLS 등)와 리소스 크기 두 가지 축으로 세우는 게 관리하기 쉽했습니다.

Lighthouse CI 설정

Lighthouse CI는 Lighthouse 검사를 자동으로 돌려주는 도구입니다. 설정 파일 하나면 시작할 수 있습니다.

// lighthouserc.json
{
  "ci": {
    "collect": {
      "staticDistDir": "./dist",
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "categories:performance": ["error", { "minScore": 0.9 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
        "total-byte-weight": ["warn", { "maxNumericValue": 1500000 }],
        "unused-javascript": "warn"
      }
    }
  }
}

포인트를 짚으면 이렇습니다.

  • numberOfRuns: 3 — 측정값의 변동이 커서 여러 번 돌린 중간값을 쓰는 편이 안정적이었습니다.
  • error 레벨은 실패, warn은 경고만 남깁니다. 처음부터 전부 error로 걸면 초반에 CI가 계속 빨간색이라 동료들 설득이 어려웠습니다.
  • 점수(0.9) 대신 지표 값(LCP 2500ms)으로 걸면 Lighthouse 버전이 바뀌어도 의미가 덜 흔들립니다.

로컬에서는 @lhci/cli를 실행해 같은 설정으로 미리 확인할 수 있습니다.

npx @lhci/cli autorun

PR을 막는 게이트 만들기

설정만으로는 부족하고, 실제로 CI 파이프라인에 끼워 넣어야 예산이 됩니다. GitHub Actions에서는 공식 액션으로 간단히 연결됩니다.

# .github/workflows/lighthouse.yml
name: Lighthouse CI
on:
  pull_request:
jobs:
  lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: treosh/lighthouse-ci-action@v12
        with:
          configPath: ./lighthouserc.json
          uploadArtifacts: true

이 워크플로우가 실패하면(성능 카테고리가 0.9 미만이거나 LCP가 2.5초를 넘으면) PR은 병합 보호 규칙에 걸려 막힙니다. 브랜치 보호 설정에서 이 워크플로우를 required check로 지정하는 것까지가 세트였습니다. 여기까지 해야 “예산”이 아니라 “권고”에 그치지 않습니다.

한 가지 팁은 임시 저장(temporary public storage) 대신 자체 서버나 LHCI 서버로 리포트를 올리면 과거 추이도 볼 수 있다는 점입니다. 추이가 쌓이면 “원래 이 페이지는 1.8초였는데 이번 PR에서 3.2초가 됐다”처럼 리뷰 때 근거를 들 수 있어 설득이 훨씬 쉬워졌습니다.

실패를 다루는 태도

게이트를 만들고 나면 반드시 이 상황이 옵니다. 급한 기능 PR이 성능 예산에 걸리는 경우입니다. 처음엔 예산을 통과할 때까지 막는 게 원칙이라고 생각했지만, 실무에서는 몇 가지 예외 장치가 필요했습니다.

  • 라벨(예: skip-performance-gate)로 워크플로우를 건너뛰되, PR 설명에 성능 영향을 남기게 합니다.
  • 단계적 상향: 현재 LCP가 4초인 레거시 페이지에 2.5초 예산을 바로 걸면 아무것도 못 합니다. 3.8초에서 시작해 점점 내리는 방식이 현실적이었습니다.
  • 예산 위반은 자동으로 코멘트로 남겨서, 리뷰어가 수치를 열어보지 않아도 원인 라인(예: unused-javascript)을 볼 수 있게 합니다.

마무리

성능 예산의 핵심은 도구가 아니라 “숫자로 합의된 선을 CI가 지키게 한다”는 구조였습니다. Lighthouse CI 설정 파일 하나, GitHub Actions 워크플로우 하나, 브랜치 보호 규칙 하나. 이 세 가지로 저희 팀은 성능 논쟁을 “느린 것 같은데?”에서 “LCP가 800ms 나빠졌네, 이미지 사이즈부터 볼까?”로 바꿀 수 있었습니다. 처음 도입할 때는 기준을 너무 빡빡하게 잡지 않는 것, 그리고 실패했을 때 대화가 이어질 장치를 함께 만드는 것이 중요했습니다.

더 알아보기

  • Lighthouse CI 공식 문서의 assertions 설정 — 커스텀 예산의 전체 옵션을 확인할 수 있습니다.
  • web.dev의 성능 예산 가이드 — 예산 수치를 정할 때 참고할 만한 기준들을 소개합니다.

Related

· 15 min read Build Logs

AI 과제 지도(assignment-map) 구축기 — 수집기 흰 화면 복구부터 18종 레퍼런스 기반 UI 개편까지

채용 과제·해커톤의 AI 정책과 마감을 매일 수집하는 과제 지도를 6일 동안 PR 16건으로 고도화했습니다. evidence 문자열 하나가 배포 화면을 통째로 죽인 장애와 그 뿌리 수정, 18종 레퍼런스 실측에서 나온 PR A~E, npm ci 앞에서 돌던 테스트가 배포를 막은 CI 함정까지 실제 수치로 정리합니다.

프론트엔드AI
→
· 3 min read

피처 플래그로 안전하게 배포하기

피처 플래그는 배포와 릴리스를 분리해 주지만, 방치하면 가장 비싼 기술부채가 됩니다. 수명주기와 정리 리듬을 정리합니다.

CI/CD프론트엔드
→
· 3 min read Web Perf

프론트엔드 성능 예산을 릴리즈 게이트로 운영하는 법

Next.js 프로젝트에서 성능 예산을 숫자 장식이 아니라 배포 판단 기준으로 운영하는 방법을 정리했습니다. LCP, INP, CLS, 번들 크기, 이미지 정책을 PR 체크와 연결하는 실무형 가이드입니다.

프론트엔드성능
→