lighthouse

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Lighthouse Audit

Lighthouse 审计

Google Lighthouse를 로컬에서 실행하여 웹 페이지의 성능, 접근성, SEO 등을 분석하고 개선점을 제안하는 스킬.
这是一个可在本地运行Google Lighthouse,分析网页性能、可访问性、SEO等指标并给出改进建议的技能。

동작 흐름

工作流程

1단계: 대상 URL 결정

第1步:确定目标URL

사용자가 URL을 명시한 경우 그대로 사용한다. URL이 여러 개이면 모두 수집하여 한 번에 분석한다. URL이 없으면 프로젝트 설정 파일을 확인하여 프레임워크를 감지하고 기본 로컬 URL을 추론한다.
감지 파일프레임워크기본 URL
vite.config.ts
/
vite.config.js
Vite (React, Vue 등)
http://localhost:5173
next.config.ts
/
next.config.js
/
next.config.mjs
Next.js
http://localhost:3000
nuxt.config.ts
/
nuxt.config.js
Nuxt
http://localhost:3000
svelte.config.js
/
svelte.config.ts
SvelteKit
http://localhost:5173
angular.json
Angular
http://localhost:4200
사용자가 특정 경로(예:
/about
,
/products/123
)를 지정하면 기본 URL에 경로를 붙여서 분석한다. 프레임워크를 감지할 수 없거나 설정 파일이 없으면 사용자에게 URL을 직접 입력받는다. 외부 URL(
https://...
)이 제공된 경우 프레임워크 감지 없이 바로 사용한다.
如果用户明确指定了URL,直接使用该URL。如果有多个URL,全部收集后一次性分析。 如果没有提供URL,则检查项目配置文件,识别所用框架并推断默认本地URL。
识别文件框架默认URL
vite.config.ts
/
vite.config.js
Vite (React, Vue等)
http://localhost:5173
next.config.ts
/
next.config.js
/
next.config.mjs
Next.js
http://localhost:3000
nuxt.config.ts
/
nuxt.config.js
Nuxt
http://localhost:3000
svelte.config.js
/
svelte.config.ts
SvelteKit
http://localhost:5173
angular.json
Angular
http://localhost:4200
如果用户指定了特定路径(例如:
/about
/products/123
),则将路径拼接到默认URL后进行分析。 如果无法识别框架或者不存在配置文件,则要求用户手动输入URL。 如果用户提供的是外部URL(
https://...
),则无需识别框架,直接使用该URL。

2단계: 분석 모드 선택

第2步:选择分析模式

외부 URL인 경우 이 단계를 건너뛴다.
로컬 프로젝트인 경우, 사용자에게 분석 모드를 확인한다:
  • 개발 서버 분석: 현재 실행 중인 개발 서버(
    dev
    )를 대상으로 분석한다
  • 프로덕션 빌드 분석: 프로젝트를 빌드한 후 프리뷰 서버를 실행하여 분석한다 (실제 배포 환경에 가까운 결과)
개발 서버 분석을 선택한 경우:
서버 접근 가능 여부를 확인한다:
bash
curl -s -o /dev/null -w "%{http_code}" {URL}
서버에 접근할 수 없으면 사용자에게 개발 서버 시작을 안내하고 대기한다.
프로덕션 빌드 분석을 선택한 경우:
프레임워크에 맞는 빌드 및 프리뷰 명령을 실행한다. 프리뷰 서버의 포트는
package.json
scripts
에서 프리뷰/스타트 명령의
--port
또는
-p
옵션을 파싱하거나, 프레임워크별 기본 포트를 사용한다.
프레임워크빌드 명령프리뷰 명령기본 포트
Vite (React, Vue 등)
npm run build
npm run preview
4173
Next.js
npm run build
npm run start
3000
Nuxt
npm run build
npm run preview
3000
SvelteKit
npm run build
npm run preview
4173
Angular
npm run build
npx serve dist/
3000
프리뷰 서버 포트 확인 순서:
  1. package.json
    의 해당 스크립트에서
    --port
    ,
    -p
    옵션 파싱
  2. 프레임워크 설정 파일에서 프리뷰 포트 설정 확인 (예:
    vite.config.ts
    preview.port
    )
  3. 위 테이블의 프레임워크별 기본 포트 사용
빌드 완료 후 프리뷰 서버를 백그라운드로 실행하고, 서버가 준비될 때까지 대기한 후 분석을 진행한다. 분석이 완료되면 프리뷰 서버 프로세스를 종료한다.
如果是外部URL,跳过该步骤。
如果是本地项目,向用户确认分析模式:
  • 开发服务器分析: 针对当前正在运行的开发服务器(
    dev
    )进行分析
  • 生产构建分析: 构建项目后启动预览服务器进行分析(结果更接近实际部署环境)
如果选择开发服务器分析:
检查服务器是否可访问:
bash
curl -s -o /dev/null -w "%{http_code}" {URL}
如果无法访问服务器,引导用户启动开发服务器并等待。
如果选择生产构建分析:
执行对应框架的构建和预览命令。预览服务器的端口优先从
package.json
scripts
中预览/启动命令的
--port
-p
选项解析,否则使用对应框架的默认端口。
框架构建命令预览命令默认端口
Vite (React, Vue等)
npm run build
npm run preview
4173
Next.js
npm run build
npm run start
3000
Nuxt
npm run build
npm run preview
3000
SvelteKit
npm run build
npm run preview
4173
Angular
npm run build
npx serve dist/
3000
预览服务器端口确认顺序:
  1. package.json
    对应脚本中解析
    --port
    -p
    选项
  2. 检查框架配置文件中的预览端口设置(例如:
    vite.config.ts
    preview.port
  3. 使用上表中对应框架的默认端口
构建完成后在后台启动预览服务器,等待服务器就绪后再进行分析。分析完成后终止预览服务器进程。

3단계: Lighthouse 실행 환경 확인

第3步:检查Lighthouse运行环境

프로젝트의
.gitignore
.lighthouseci
가 포함되어 있는지 확인한다. 없으면
.gitignore
.lighthouseci
를 추가하여 분석 결과가 실수로 커밋되지 않도록 한다.
Lighthouse는 Chrome 또는 Chromium 브라우저가 필요하다. 설치 여부를 확인한다.
macOS:
bash
ls /Applications/Google\ Chrome.app 2>/dev/null || ls /Applications/Chromium.app 2>/dev/null
Linux:
bash
which google-chrome || which chromium-browser
Chrome이 설치되어 있지 않으면 사용자에게 설치를 안내하고 중단한다.
检查项目的
.gitignore
中是否包含
.lighthouseci
,如果没有则将
.lighthouseci
添加到
.gitignore
中,避免分析结果被误提交。
Lighthouse需要Chrome或Chromium浏览器,检查是否已安装:
macOS:
bash
ls /Applications/Google\ Chrome.app 2>/dev/null || ls /Applications/Chromium.app 2>/dev/null
Linux:
bash
which google-chrome || which chromium-browser
如果未安装Chrome,引导用户安装后终止流程。

4단계: LHCI 구성 파일 감지

第4步:检测LHCI配置文件

프로젝트 루트에서 LHCI 구성 파일이 있는지 확인한다. 다음 파일명을 순서대로 탐색한다:
  • .lighthouserc.js
  • .lighthouserc.cjs
  • .lighthouserc.json
  • .lighthouserc.yml
  • .lighthouserc.yaml
구성 파일이 존재하는 경우:
  • 해당 파일의 설정을 우선 적용한다.
    lhci collect
    실행 시
    --config
    플래그 없이도 LHCI가 자동으로 인식한다
  • 구성 파일에
    ci.collect.url
    이 이미 지정되어 있으면 1단계에서 결정한 URL 대신 구성 파일의 URL을 사용한다
  • 구성 파일에 없는 옵션만 CLI 플래그로 보충한다 (예: 구성 파일에
    numberOfRuns
    가 없으면 CLI에서
    --numberOfRuns=1
    을 추가)
  • 사용자에게 감지된 구성 파일명과 주요 설정 내용을 안내한다
구성 파일이 없는 경우:
  • 5단계의 기본 CLI 플래그로 실행한다
在项目根目录检查是否存在LHCI配置文件,按以下顺序查找:
  • .lighthouserc.js
  • .lighthouserc.cjs
  • .lighthouserc.json
  • .lighthouserc.yml
  • .lighthouserc.yaml
如果存在配置文件:
  • 优先使用该文件的配置,执行
    lhci collect
    时无需添加
    --config
    参数,LHCI会自动识别
  • 如果配置文件中已指定
    ci.collect.url
    ,则使用配置文件的URL,代替第1步确定的URL
  • 仅使用CLI参数补充配置文件中缺失的选项(例如:配置文件中没有
    numberOfRuns
    时,在CLI中添加
    --numberOfRuns=1
  • 向用户告知检测到的配置文件名和核心配置内容
如果不存在配置文件:
  • 使用第5步的默认CLI参数执行

5단계: Lighthouse 실행

第5步:运行Lighthouse

npx @lhci/cli
로 Lighthouse를 실행한다.
lhci collect
명령은 Lighthouse를 실행하고 결과를
.lighthouseci/
디렉토리에 JSON 파일로 저장한다.
구성 파일이 없는 경우의 기본 실행 명령:
bash
npx @lhci/cli collect \
  --url={URL1} \
  --url={URL2} \
  --numberOfRuns=1 \
  --chrome-flags="--headless --no-sandbox" \
  --only-categories=performance,accessibility,best-practices,seo
--url
플래그를 여러 번 지정하여 복수의 URL을 한 번에 분석할 수 있다.
구성 파일이 있는 경우, 구성 파일에 정의되지 않은 옵션만 CLI 플래그로 추가한다:
bash
npx @lhci/cli collect \
  --chrome-flags="--headless --no-sandbox"
  • --numberOfRuns
    : 기본 1회 실행. 사용자가 더 정확한 결과를 원하면 3~5회로 늘려 중앙값을 사용한다
  • 결과 파일은
    .lighthouseci/
    디렉토리에
    lhr-{timestamp}.json
    형식으로 저장된다
디바이스 설정:
  • 기본값은 모바일(Lighthouse 기본 동작)
  • 사용자가 데스크톱을 요청하면
    --preset=desktop
    플래그를 추가한다
  • 사용자가 모바일과 데스크톱 모두 요청하면 각각 실행하여 결과를 비교한다
通过
npx @lhci/cli
运行Lighthouse,
lhci collect
命令会执行Lighthouse检测,并将结果以JSON文件形式存储在
.lighthouseci/
目录下。
无配置文件时的默认执行命令:
bash
npx @lhci/cli collect \
  --url={URL1} \
  --url={URL2} \
  --numberOfRuns=1 \
  --chrome-flags="--headless --no-sandbox" \
  --only-categories=performance,accessibility,best-practices,seo
可以多次指定
--url
参数,一次性分析多个URL。
如果存在配置文件,仅使用CLI参数补充配置文件中未定义的选项:
bash
npx @lhci/cli collect \
  --chrome-flags="--headless --no-sandbox"
  • --numberOfRuns
    : 默认执行1次,如果用户需要更准确的结果,可以增加到3~5次,取中位数结果
  • 结果文件以
    lhr-{timestamp}.json
    格式存储在
    .lighthouseci/
    目录下
设备设置:
  • 默认使用移动端(Lighthouse默认行为)
  • 如果用户要求桌面端,添加
    --preset=desktop
    参数
  • 如果用户要求同时检测移动端和桌面端,分别执行后对比结果

6단계: 결과 파싱 및 요약

第6步:解析并汇总结果

.lighthouseci/
디렉토리에서 가장 최근
lhr-*.json
파일을 읽어서 카테고리별 점수와 개선 항목을 추출한다. 여러 번 실행한 경우 중앙값(median) 결과 파일을 사용한다.
카테고리별 점수 요약 테이블을 출력한다:
카테고리점수등급
Performance0-100Good (90-100) / Needs Improvement (50-89) / Poor (0-49)
Accessibility0-100동일 기준
Best Practices0-100동일 기준
SEO0-100동일 기준
JSON 파싱 경로:
  • 카테고리 점수:
    categories.{category}.score
    (0-1 범위, 100을 곱해서 표시)
  • 감사 항목 참조:
    categories.{category}.auditRefs
    에서
    weight > 0
    인 항목
  • 감사 상세:
    audits.{auditId}
    에서
    title
    ,
    description
    ,
    score
    ,
    displayValue
    추출
각 카테고리에서 점수가 1 미만인 감사 항목을
weight
순으로 정렬하여 상위 항목부터 보고한다. Performance 카테고리의 경우
metricSavings
또는
overallSavingsMs
값이 있으면 예상 절감 효과도 함께 표시한다.
读取
.lighthouseci/
目录下最新的
lhr-*.json
文件,提取各分类得分和改进项。如果执行了多次检测,使用中位数结果文件。
输出各分类得分汇总表:
分类得分等级
Performance0-100优秀 (90-100) / 待改进 (50-89) / 较差 (0-49)
Accessibility0-100同上标准
Best Practices0-100同上标准
SEO0-100同上标准
JSON解析路径:
  • 分类得分:
    categories.{category}.score
    (范围0-1,乘以100后展示)
  • 检测项引用:取
    categories.{category}.auditRefs
    weight > 0
    的项
  • 检测详情:从
    audits.{auditId}
    中提取
    title
    description
    score
    displayValue
将各分类中得分低于1的检测项按
weight
排序,优先展示权重高的项。Performance分类如果存在
metricSavings
overallSavingsMs
值,同时展示预期优化收益。

7단계: 개선점 제안

第7步:提出改进建议

카테고리별로 구분하여 구체적인 개선 방법을 제안한다. 프로젝트에서 사용 중인 프레임워크에 맞는 해결 방법을 우선 제안한다.
각 개선 항목은 다음 3단계 우선순위로 분류하여 제시한다:
우선순위의미기준
필수반드시 수정해야 하는 항목사용자 경험에 직접적 영향이 크고, 코드 수정으로 명확히 해결 가능한 항목
권장수정하면 좋지만 상황에 따라 판단할 항목개선 효과가 있으나 수정 난이도가 높거나, 프로젝트 구조 변경이 필요한 항목
참고인지만 하면 되는 항목외부 환경(서버, CDN 등)에 의존하거나, 수정 대비 효과가 미미하거나, 현실적으로 수정이 어려운 항목
우선순위 분류 기준:
  1. 감사 항목의
    weight
    score
    : weight가 높고 score가 낮을수록 필수에 가까움
  2. 수정 가능 여부: 프로젝트 코드에서 직접 수정 가능하면 필수/권장, 서버 설정이나 인프라 변경이 필요하면 참고
  3. 효과 대비 난이도:
    metricSavings
    가 크고 수정이 단순하면 필수, 대규모 리팩토링이 필요하면 권장 또는 참고
  4. 실용성: 로컬 개발 환경에서만 발생하는 문제(예: HTTP, 캐시 헤더)는 참고로 분류
Performance 주요 항목:
Lighthouse Audit일반적 우선순위개선 제안
unsized-images
필수이미지에
width
/
height
속성 추가
largest-contentful-paint
필수LCP 요소 최적화 (preload,
fetchpriority="high"
)
cumulative-layout-shift
필수CLS 개선 (이미지 크기 지정,
font-display: swap
)
render-blocking-resources
권장CSS/JS 로딩 최적화 (
async
,
defer
, 동적 import)
unused-css-rules
/
unused-javascript
권장미사용 코드 제거, 코드 스플리팅
uses-optimized-images
/
uses-webp-images
권장이미지 포맷 변환 (WebP/AVIF), Next.js
<Image>
활용
total-blocking-time
권장TBT 개선 (코드 스플리팅, Web Worker, 무거운 작업 분리)
uses-text-compression
참고gzip/brotli 압축 (서버/호스팅 설정 필요)
uses-long-cache-ttl
참고캐시 헤더 설정 (서버/CDN 설정 필요)
server-response-time
참고TTFB 개선 (서버/인프라 영역)
Accessibility 주요 항목:
Lighthouse Audit일반적 우선순위개선 제안
image-alt
필수이미지에
alt
속성 추가
html-has-lang
필수
<html lang="ko">
속성 추가
button-name
/
link-name
필수버튼/링크에 접근 가능한 이름 추가 (
aria-label
등)
heading-order
권장제목 태그(
h1
~
h6
) 순서 수정
meta-viewport
권장뷰포트 메타 태그 설정 확인
color-contrast
참고색상 대비 비율 조정 (디자인 시스템 변경이 필요할 수 있음)
SEO 주요 항목:
Lighthouse Audit일반적 우선순위개선 제안
document-title
필수페이지 제목 설정
meta-description
필수메타 설명 추가
canonical
권장canonical URL 설정
robots-txt
권장robots.txt 확인 및 생성
hreflang
참고다국어 대응 hreflang 추가 (다국어 사이트가 아니면 불필요)
Best Practices 주요 항목:
Lighthouse Audit일반적 우선순위개선 제안
errors-in-console
필수콘솔 에러 해결
no-vulnerable-libraries
권장취약한 라이브러리 업데이트
deprecations
권장사용 중단 예정 API 교체
is-on-https
참고HTTPS 적용 확인 (로컬 개발 환경에서는 해당 없음)
위 테이블의 우선순위는 일반적인 기준이다. 실제 분류 시에는 해당 프로젝트의 맥락(프레임워크, 배포 환경, 페이지 특성 등)을 고려하여 항목별 우선순위를 조정한다.
按分类区分,给出具体的改进方法,优先提供适配项目所用框架的解决方案。
每个改进项按以下3个优先级分类展示:
优先级含义判定标准
必填必须修复的项对用户体验有直接影响,可通过代码修改明确解决的项
推荐建议修复,可根据实际情况判断的项有优化效果,但修复难度较高,或需要调整项目结构的项
参考仅需知晓即可的项依赖外部环境(服务器、CDN等),或修复投入产出比低,或实际修复难度大的项
优先级分类规则:
  1. 检测项的
    weight
    score
    : weight越高、score越低,越接近必填级别
  2. 可修复性: 可直接在项目代码中修改的为必填/推荐,需要修改服务器配置或基础设施的为参考
  3. 投入产出比:
    metricSavings
    高且修改简单的为必填,需要大规模重构的为推荐或参考
  4. 实用性: 仅在本地开发环境出现的问题(例如:HTTP、缓存头)归类为参考
Performance核心项:
Lighthouse检测项通用优先级改进建议
unsized-images
必填为图片添加
width
/
height
属性
largest-contentful-paint
必填优化LCP元素(preload、
fetchpriority="high"
cumulative-layout-shift
必填优化CLS(指定图片尺寸、
font-display: swap
render-blocking-resources
推荐优化CSS/JS加载(
async
defer
、动态import)
unused-css-rules
/
unused-javascript
推荐移除未使用代码、代码分割
uses-optimized-images
/
uses-webp-images
推荐转换图片格式(WebP/AVIF)、使用Next.js
<Image>
组件
total-blocking-time
推荐优化TBT(代码分割、Web Worker、拆分重任务)
uses-text-compression
参考开启gzip/brotli压缩(需要修改服务器/托管配置)
uses-long-cache-ttl
参考设置缓存头(需要修改服务器/CDN配置)
server-response-time
参考优化TTFB(属于服务器/基础设施范畴)
Accessibility核心项:
Lighthouse检测项通用优先级改进建议
image-alt
必填为图片添加
alt
属性
html-has-lang
必填添加
<html lang="zh">
属性
button-name
/
link-name
必填为按钮/链接添加可访问名称(
aria-label
等)
heading-order
推荐修正标题标签(
h1
~
h6
)层级顺序
meta-viewport
推荐检查视口meta标签设置
color-contrast
参考调整颜色对比度(可能需要修改设计系统)
SEO核心项:
Lighthouse检测项通用优先级改进建议
document-title
必填设置页面标题
meta-description
必填添加meta描述
canonical
推荐设置canonical URL
robots-txt
推荐检查并生成robots.txt
hreflang
参考多语言站点添加hreflang(非多语言站点无需设置)
Best Practices核心项:
Lighthouse检测项通用优先级改进建议
errors-in-console
必填修复控制台报错
no-vulnerable-libraries
推荐更新存在漏洞的依赖库
deprecations
推荐替换即将废弃的API
is-on-https
参考确认HTTPS配置(本地开发环境无需考虑)
上表中的优先级为通用标准,实际分类时需要结合项目实际场景(框架、部署环境、页面特性等)调整各项目的优先级。

8단계: 코드 수정 (선택적)

第8步:代码修复(可选)

개선 항목을 우선순위별로 그룹화하여 사용자에게 제시한 후, 수정 여부를 확인한다.
  1. 필수 항목을 먼저 보여주고, 이어서 권장, 참고 순으로 제시한다
  2. 각 항목에 우선순위 라벨, 개선 내용, 예상 효과를 함께 표시한다
  3. 참고 항목은 수정 방법 대신 해당 항목이 참고인 이유(예: 서버 설정 필요, 디자인 변경 수반 등)를 설명한다
  4. 사용자가 수정을 원하는 항목을 선택하면 해당 코드를 수정한다
  5. 수정 완료 후 재측정을 원하는지 확인한다
코드 수정 가능 범위:
  • HTML 메타 태그 추가/수정 (SEO, Accessibility)
  • 이미지 태그에
    alt
    ,
    width
    ,
    height
    속성 추가
  • Next.js
    <Image>
    컴포넌트로 교체 제안
  • CSS/JS 로딩 방식 변경 (
    async
    ,
    defer
    , dynamic import)
  • font-display: swap
    추가
  • <html lang>
    속성 추가/수정
  • 색상 대비 수정 (구체적 색상값 제시)
将改进项按优先级分组展示给用户后,确认是否需要修复。
  1. 优先展示必填项,之后依次展示推荐参考
  2. 每个项同时展示优先级标签、改进内容、预期收益
  3. 参考项不提供修复方法,而是说明该项为参考级别的原因(例如:需要修改服务器配置、需要配合设计修改等)
  4. 用户选择需要修复的项后,修改对应代码
  5. 修复完成后确认是否需要重新检测
可自动修复的范围:
  • 添加/修改HTML meta标签(SEO、Accessibility)
  • 为图片标签添加
    alt
    width
    height
    属性
  • 建议替换为Next.js
    <Image>
    组件
  • 修改CSS/JS加载方式(
    async
    defer
    、dynamic import)
  • 添加
    font-display: swap
  • 添加/修改
    <html lang>
    属性
  • 调整颜色对比度(提供具体色值)

9단계: 정리

第9步:清理

분석 완료 후 정리 작업을 수행한다.
  1. 프로덕션 빌드 분석 모드였다면 백그라운드 프리뷰 서버 프로세스를 종료한다
  2. 생성된 리포트 디렉토리를 삭제하여 프로젝트 디렉토리를 깨끗하게 유지한다
bash
rm -rf ./.lighthouseci
分析完成后执行清理操作:
  1. 如果使用生产构建分析模式,终止后台运行的预览服务器进程
  2. 删除生成的报告目录,保持项目目录整洁
bash
rm -rf ./.lighthouseci

주의사항

注意事项

  • Lighthouse 실행에는 Chrome 또는 Chromium 브라우저가 반드시 필요하다. 설치되어 있지 않으면 안내 후 중단한다
  • 로컬 URL 분석 시 개발 서버가 실행 중이어야 한다. 서버가 꺼져 있으면 시작을 안내하고 대기한다
  • Lighthouse 점수는 실행 환경(네트워크, CPU 등)에 따라 매번 달라질 수 있다. 정확도가 필요하면
    --numberOfRuns
    를 늘려 중앙값을 사용한다
  • npx @lhci/cli
    를 사용하여 실행한다
  • 코드 수정은 반드시 사용자 확인 후 진행한다. 자동으로 수정하지 않는다
  • .lighthouseci/
    디렉토리는 분석 완료 후 삭제하여 프로젝트를 오염시키지 않는다
  • 외부 URL 분석 시 네트워크 상태에 따라 결과가 달라질 수 있음을 사용자에게 안내한다
  • 运行Lighthouse必须安装Chrome或Chromium浏览器,未安装时引导用户后终止流程
  • 分析本地URL时需要提前启动开发服务器,服务器未启动时引导用户启动并等待
  • Lighthouse得分会受运行环境(网络、CPU等)影响每次结果可能存在差异,需要高准确率时可增加
    --numberOfRuns
    取中位数结果
  • 使用
    npx @lhci/cli
    执行命令
  • 代码修复必须经过用户确认后再执行,不得自动修改
  • 分析完成后删除
    .lighthouseci/
    目录,避免污染项目
  • 分析外部URL时,向用户告知结果可能受网络状态影响