lighthouse
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseLighthouse Audit
Lighthouse 审计
Google Lighthouse를 로컬에서 실행하여 웹 페이지의 성능, 접근성, SEO 등을 분석하고 개선점을 제안하는 스킬.
这是一个可在本地运行Google Lighthouse,分析网页性能、可访问性、SEO等指标并给出改进建议的技能。
동작 흐름
工作流程
1단계: 대상 URL 결정
第1步:确定目标URL
사용자가 URL을 명시한 경우 그대로 사용한다. URL이 여러 개이면 모두 수집하여 한 번에 분석한다.
URL이 없으면 프로젝트 설정 파일을 확인하여 프레임워크를 감지하고 기본 로컬 URL을 추론한다.
| 감지 파일 | 프레임워크 | 기본 URL |
|---|---|---|
| Vite (React, Vue 등) | |
| Next.js | |
| Nuxt | |
| SvelteKit | |
| Angular | |
사용자가 특정 경로(예: , )를 지정하면 기본 URL에 경로를 붙여서 분석한다.
프레임워크를 감지할 수 없거나 설정 파일이 없으면 사용자에게 URL을 직접 입력받는다.
외부 URL()이 제공된 경우 프레임워크 감지 없이 바로 사용한다.
/about/products/123https://...如果用户明确指定了URL,直接使用该URL。如果有多个URL,全部收集后一次性分析。
如果没有提供URL,则检查项目配置文件,识别所用框架并推断默认本地URL。
| 识别文件 | 框架 | 默认URL |
|---|---|---|
| Vite (React, Vue等) | |
| Next.js | |
| Nuxt | |
| SvelteKit | |
| Angular | |
如果用户指定了特定路径(例如:、),则将路径拼接到默认URL后进行分析。
如果无法识别框架或者不存在配置文件,则要求用户手动输入URL。
如果用户提供的是外部URL(),则无需识别框架,直接使用该URL。
/about/products/123https://...2단계: 분석 모드 선택
第2步:选择分析模式
외부 URL인 경우 이 단계를 건너뛴다.
로컬 프로젝트인 경우, 사용자에게 분석 모드를 확인한다:
- 개발 서버 분석: 현재 실행 중인 개발 서버()를 대상으로 분석한다
dev - 프로덕션 빌드 분석: 프로젝트를 빌드한 후 프리뷰 서버를 실행하여 분석한다 (실제 배포 환경에 가까운 결과)
개발 서버 분석을 선택한 경우:
서버 접근 가능 여부를 확인한다:
bash
curl -s -o /dev/null -w "%{http_code}" {URL}서버에 접근할 수 없으면 사용자에게 개발 서버 시작을 안내하고 대기한다.
프로덕션 빌드 분석을 선택한 경우:
프레임워크에 맞는 빌드 및 프리뷰 명령을 실행한다. 프리뷰 서버의 포트는 의 에서 프리뷰/스타트 명령의 또는 옵션을 파싱하거나, 프레임워크별 기본 포트를 사용한다.
package.jsonscripts--port-p| 프레임워크 | 빌드 명령 | 프리뷰 명령 | 기본 포트 |
|---|---|---|---|
| Vite (React, Vue 등) | | | |
| Next.js | | | |
| Nuxt | | | |
| SvelteKit | | | |
| Angular | | | |
프리뷰 서버 포트 확인 순서:
- 의 해당 스크립트에서
package.json,--port옵션 파싱-p - 프레임워크 설정 파일에서 프리뷰 포트 설정 확인 (예: 의
vite.config.ts)preview.port - 위 테이블의 프레임워크별 기본 포트 사용
빌드 완료 후 프리뷰 서버를 백그라운드로 실행하고, 서버가 준비될 때까지 대기한 후 분석을 진행한다. 분석이 완료되면 프리뷰 서버 프로세스를 종료한다.
如果是外部URL,跳过该步骤。
如果是本地项目,向用户确认分析模式:
- 开发服务器分析: 针对当前正在运行的开发服务器()进行分析
dev - 生产构建分析: 构建项目后启动预览服务器进行分析(结果更接近实际部署环境)
如果选择开发服务器分析:
检查服务器是否可访问:
bash
curl -s -o /dev/null -w "%{http_code}" {URL}如果无法访问服务器,引导用户启动开发服务器并等待。
如果选择生产构建分析:
执行对应框架的构建和预览命令。预览服务器的端口优先从的中预览/启动命令的或选项解析,否则使用对应框架的默认端口。
package.jsonscripts--port-p| 框架 | 构建命令 | 预览命令 | 默认端口 |
|---|---|---|---|
| Vite (React, Vue等) | | | |
| Next.js | | | |
| Nuxt | | | |
| SvelteKit | | | |
| Angular | | | |
预览服务器端口确认顺序:
- 从对应脚本中解析
package.json、--port选项-p - 检查框架配置文件中的预览端口设置(例如:的
vite.config.ts)preview.port - 使用上表中对应框架的默认端口
构建完成后在后台启动预览服务器,等待服务器就绪后再进行分析。分析完成后终止预览服务器进程。
3단계: Lighthouse 실행 환경 확인
第3步:检查Lighthouse运行环境
프로젝트의 에 가 포함되어 있는지 확인한다. 없으면 에 를 추가하여 분석 결과가 실수로 커밋되지 않도록 한다.
.gitignore.lighthouseci.gitignore.lighthouseciLighthouse는 Chrome 또는 Chromium 브라우저가 필요하다. 설치 여부를 확인한다.
macOS:
bash
ls /Applications/Google\ Chrome.app 2>/dev/null || ls /Applications/Chromium.app 2>/dev/nullLinux:
bash
which google-chrome || which chromium-browserChrome이 설치되어 있지 않으면 사용자에게 설치를 안내하고 중단한다.
检查项目的中是否包含,如果没有则将添加到中,避免分析结果被误提交。
.gitignore.lighthouseci.lighthouseci.gitignoreLighthouse需要Chrome或Chromium浏览器,检查是否已安装:
macOS:
bash
ls /Applications/Google\ Chrome.app 2>/dev/null || ls /Applications/Chromium.app 2>/dev/nullLinux:
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플래그 없이도 LHCI가 자동으로 인식한다--config - 구성 파일에 이 이미 지정되어 있으면 1단계에서 결정한 URL 대신 구성 파일의 URL을 사용한다
ci.collect.url - 구성 파일에 없는 옵션만 CLI 플래그로 보충한다 (예: 구성 파일에 가 없으면 CLI에서
numberOfRuns을 추가)--numberOfRuns=1 - 사용자에게 감지된 구성 파일명과 주요 설정 내용을 안내한다
구성 파일이 없는 경우:
- 5단계의 기본 CLI 플래그로 실행한다
在项目根目录检查是否存在LHCI配置文件,按以下顺序查找:
.lighthouserc.js.lighthouserc.cjs.lighthouserc.json.lighthouserc.yml.lighthouserc.yaml
如果存在配置文件:
- 优先使用该文件的配置,执行时无需添加
lhci collect参数,LHCI会自动识别--config - 如果配置文件中已指定,则使用配置文件的URL,代替第1步确定的URL
ci.collect.url - 仅使用CLI参数补充配置文件中缺失的选项(例如:配置文件中没有时,在CLI中添加
numberOfRuns)--numberOfRuns=1 - 向用户告知检测到的配置文件名和核心配置内容
如果不存在配置文件:
- 使用第5步的默认CLI参数执行
5단계: Lighthouse 실행
第5步:运行Lighthouse
npx @lhci/clilhci collect.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구성 파일이 있는 경우, 구성 파일에 정의되지 않은 옵션만 CLI 플래그로 추가한다:
bash
npx @lhci/cli collect \
--chrome-flags="--headless --no-sandbox"- : 기본 1회 실행. 사용자가 더 정확한 결과를 원하면 3~5회로 늘려 중앙값을 사용한다
--numberOfRuns - 결과 파일은 디렉토리에
.lighthouseci/형식으로 저장된다lhr-{timestamp}.json
디바이스 설정:
- 기본값은 모바일(Lighthouse 기본 동작)
- 사용자가 데스크톱을 요청하면 플래그를 추가한다
--preset=desktop - 사용자가 모바일과 데스크톱 모두 요청하면 각각 실행하여 결과를 비교한다
通过运行Lighthouse,命令会执行Lighthouse检测,并将结果以JSON文件形式存储在目录下。
npx @lhci/clilhci collect.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"- : 默认执行1次,如果用户需要更准确的结果,可以增加到3~5次,取中位数结果
--numberOfRuns - 结果文件以格式存储在
lhr-{timestamp}.json目录下.lighthouseci/
设备设置:
- 默认使用移动端(Lighthouse默认行为)
- 如果用户要求桌面端,添加参数
--preset=desktop - 如果用户要求同时检测移动端和桌面端,分别执行后对比结果
6단계: 결과 파싱 및 요약
第6步:解析并汇总结果
.lighthouseci/lhr-*.json카테고리별 점수 요약 테이블을 출력한다:
| 카테고리 | 점수 | 등급 |
|---|---|---|
| Performance | 0-100 | Good (90-100) / Needs Improvement (50-89) / Poor (0-49) |
| Accessibility | 0-100 | 동일 기준 |
| Best Practices | 0-100 | 동일 기준 |
| SEO | 0-100 | 동일 기준 |
JSON 파싱 경로:
- 카테고리 점수: (0-1 범위, 100을 곱해서 표시)
categories.{category}.score - 감사 항목 참조: 에서
categories.{category}.auditRefs인 항목weight > 0 - 감사 상세: 에서
audits.{auditId},title,description,score추출displayValue
각 카테고리에서 점수가 1 미만인 감사 항목을 순으로 정렬하여 상위 항목부터 보고한다.
Performance 카테고리의 경우 또는 값이 있으면 예상 절감 효과도 함께 표시한다.
weightmetricSavingsoverallSavingsMs读取目录下最新的文件,提取各分类得分和改进项。如果执行了多次检测,使用中位数结果文件。
.lighthouseci/lhr-*.json输出各分类得分汇总表:
| 分类 | 得分 | 等级 |
|---|---|---|
| Performance | 0-100 | 优秀 (90-100) / 待改进 (50-89) / 较差 (0-49) |
| Accessibility | 0-100 | 同上标准 |
| Best Practices | 0-100 | 同上标准 |
| SEO | 0-100 | 同上标准 |
JSON解析路径:
- 分类得分:(范围0-1,乘以100后展示)
categories.{category}.score - 检测项引用:取中
categories.{category}.auditRefs的项weight > 0 - 检测详情:从中提取
audits.{auditId}、title、description、scoredisplayValue
将各分类中得分低于1的检测项按排序,优先展示权重高的项。Performance分类如果存在或值,同时展示预期优化收益。
weightmetricSavingsoverallSavingsMs7단계: 개선점 제안
第7步:提出改进建议
카테고리별로 구분하여 구체적인 개선 방법을 제안한다. 프로젝트에서 사용 중인 프레임워크에 맞는 해결 방법을 우선 제안한다.
각 개선 항목은 다음 3단계 우선순위로 분류하여 제시한다:
| 우선순위 | 의미 | 기준 |
|---|---|---|
| 필수 | 반드시 수정해야 하는 항목 | 사용자 경험에 직접적 영향이 크고, 코드 수정으로 명확히 해결 가능한 항목 |
| 권장 | 수정하면 좋지만 상황에 따라 판단할 항목 | 개선 효과가 있으나 수정 난이도가 높거나, 프로젝트 구조 변경이 필요한 항목 |
| 참고 | 인지만 하면 되는 항목 | 외부 환경(서버, CDN 등)에 의존하거나, 수정 대비 효과가 미미하거나, 현실적으로 수정이 어려운 항목 |
우선순위 분류 기준:
- 감사 항목의 와
weight: weight가 높고 score가 낮을수록 필수에 가까움score - 수정 가능 여부: 프로젝트 코드에서 직접 수정 가능하면 필수/권장, 서버 설정이나 인프라 변경이 필요하면 참고
- 효과 대비 난이도: 가 크고 수정이 단순하면 필수, 대규모 리팩토링이 필요하면 권장 또는 참고
metricSavings - 실용성: 로컬 개발 환경에서만 발생하는 문제(예: HTTP, 캐시 헤더)는 참고로 분류
Performance 주요 항목:
| Lighthouse Audit | 일반적 우선순위 | 개선 제안 |
|---|---|---|
| 필수 | 이미지에 |
| 필수 | LCP 요소 최적화 (preload, |
| 필수 | CLS 개선 (이미지 크기 지정, |
| 권장 | CSS/JS 로딩 최적화 ( |
| 권장 | 미사용 코드 제거, 코드 스플리팅 |
| 권장 | 이미지 포맷 변환 (WebP/AVIF), Next.js |
| 권장 | TBT 개선 (코드 스플리팅, Web Worker, 무거운 작업 분리) |
| 참고 | gzip/brotli 압축 (서버/호스팅 설정 필요) |
| 참고 | 캐시 헤더 설정 (서버/CDN 설정 필요) |
| 참고 | TTFB 개선 (서버/인프라 영역) |
Accessibility 주요 항목:
| Lighthouse Audit | 일반적 우선순위 | 개선 제안 |
|---|---|---|
| 필수 | 이미지에 |
| 필수 | |
| 필수 | 버튼/링크에 접근 가능한 이름 추가 ( |
| 권장 | 제목 태그( |
| 권장 | 뷰포트 메타 태그 설정 확인 |
| 참고 | 색상 대비 비율 조정 (디자인 시스템 변경이 필요할 수 있음) |
SEO 주요 항목:
| Lighthouse Audit | 일반적 우선순위 | 개선 제안 |
|---|---|---|
| 필수 | 페이지 제목 설정 |
| 필수 | 메타 설명 추가 |
| 권장 | canonical URL 설정 |
| 권장 | robots.txt 확인 및 생성 |
| 참고 | 다국어 대응 hreflang 추가 (다국어 사이트가 아니면 불필요) |
Best Practices 주요 항목:
| Lighthouse Audit | 일반적 우선순위 | 개선 제안 |
|---|---|---|
| 필수 | 콘솔 에러 해결 |
| 권장 | 취약한 라이브러리 업데이트 |
| 권장 | 사용 중단 예정 API 교체 |
| 참고 | HTTPS 적용 확인 (로컬 개발 환경에서는 해당 없음) |
위 테이블의 우선순위는 일반적인 기준이다. 실제 분류 시에는 해당 프로젝트의 맥락(프레임워크, 배포 환경, 페이지 특성 등)을 고려하여 항목별 우선순위를 조정한다.
按分类区分,给出具体的改进方法,优先提供适配项目所用框架的解决方案。
每个改进项按以下3个优先级分类展示:
| 优先级 | 含义 | 判定标准 |
|---|---|---|
| 必填 | 必须修复的项 | 对用户体验有直接影响,可通过代码修改明确解决的项 |
| 推荐 | 建议修复,可根据实际情况判断的项 | 有优化效果,但修复难度较高,或需要调整项目结构的项 |
| 参考 | 仅需知晓即可的项 | 依赖外部环境(服务器、CDN等),或修复投入产出比低,或实际修复难度大的项 |
优先级分类规则:
- 检测项的和
weight: weight越高、score越低,越接近必填级别score - 可修复性: 可直接在项目代码中修改的为必填/推荐,需要修改服务器配置或基础设施的为参考
- 投入产出比: 高且修改简单的为必填,需要大规模重构的为推荐或参考
metricSavings - 实用性: 仅在本地开发环境出现的问题(例如:HTTP、缓存头)归类为参考
Performance核心项:
| Lighthouse检测项 | 通用优先级 | 改进建议 |
|---|---|---|
| 必填 | 为图片添加 |
| 必填 | 优化LCP元素(preload、 |
| 必填 | 优化CLS(指定图片尺寸、 |
| 推荐 | 优化CSS/JS加载( |
| 推荐 | 移除未使用代码、代码分割 |
| 推荐 | 转换图片格式(WebP/AVIF)、使用Next.js |
| 推荐 | 优化TBT(代码分割、Web Worker、拆分重任务) |
| 参考 | 开启gzip/brotli压缩(需要修改服务器/托管配置) |
| 参考 | 设置缓存头(需要修改服务器/CDN配置) |
| 参考 | 优化TTFB(属于服务器/基础设施范畴) |
Accessibility核心项:
| Lighthouse检测项 | 通用优先级 | 改进建议 |
|---|---|---|
| 必填 | 为图片添加 |
| 必填 | 添加 |
| 必填 | 为按钮/链接添加可访问名称( |
| 推荐 | 修正标题标签( |
| 推荐 | 检查视口meta标签设置 |
| 参考 | 调整颜色对比度(可能需要修改设计系统) |
SEO核心项:
| Lighthouse检测项 | 通用优先级 | 改进建议 |
|---|---|---|
| 必填 | 设置页面标题 |
| 必填 | 添加meta描述 |
| 推荐 | 设置canonical URL |
| 推荐 | 检查并生成robots.txt |
| 参考 | 多语言站点添加hreflang(非多语言站点无需设置) |
Best Practices核心项:
| Lighthouse检测项 | 通用优先级 | 改进建议 |
|---|---|---|
| 必填 | 修复控制台报错 |
| 推荐 | 更新存在漏洞的依赖库 |
| 推荐 | 替换即将废弃的API |
| 参考 | 确认HTTPS配置(本地开发环境无需考虑) |
上表中的优先级为通用标准,实际分类时需要结合项目实际场景(框架、部署环境、页面特性等)调整各项目的优先级。
8단계: 코드 수정 (선택적)
第8步:代码修复(可选)
개선 항목을 우선순위별로 그룹화하여 사용자에게 제시한 후, 수정 여부를 확인한다.
- 필수 항목을 먼저 보여주고, 이어서 권장, 참고 순으로 제시한다
- 각 항목에 우선순위 라벨, 개선 내용, 예상 효과를 함께 표시한다
- 참고 항목은 수정 방법 대신 해당 항목이 참고인 이유(예: 서버 설정 필요, 디자인 변경 수반 등)를 설명한다
- 사용자가 수정을 원하는 항목을 선택하면 해당 코드를 수정한다
- 수정 완료 후 재측정을 원하는지 확인한다
코드 수정 가능 범위:
- HTML 메타 태그 추가/수정 (SEO, Accessibility)
- 이미지 태그에 ,
alt,width속성 추가height - Next.js 컴포넌트로 교체 제안
<Image> - CSS/JS 로딩 방식 변경 (,
async, dynamic import)defer - 추가
font-display: swap - 속성 추가/수정
<html lang> - 색상 대비 수정 (구체적 색상값 제시)
将改进项按优先级分组展示给用户后,确认是否需要修复。
- 优先展示必填项,之后依次展示推荐、参考项
- 每个项同时展示优先级标签、改进内容、预期收益
- 参考项不提供修复方法,而是说明该项为参考级别的原因(例如:需要修改服务器配置、需要配合设计修改等)
- 用户选择需要修复的项后,修改对应代码
- 修复完成后确认是否需要重新检测
可自动修复的范围:
- 添加/修改HTML meta标签(SEO、Accessibility)
- 为图片标签添加、
alt、width属性height - 建议替换为Next.js 组件
<Image> - 修改CSS/JS加载方式(、
async、dynamic import)defer - 添加
font-display: swap - 添加/修改属性
<html lang> - 调整颜色对比度(提供具体色值)
9단계: 정리
第9步:清理
분석 완료 후 정리 작업을 수행한다.
- 프로덕션 빌드 분석 모드였다면 백그라운드 프리뷰 서버 프로세스를 종료한다
- 생성된 리포트 디렉토리를 삭제하여 프로젝트 디렉토리를 깨끗하게 유지한다
bash
rm -rf ./.lighthouseci分析完成后执行清理操作:
- 如果使用生产构建分析模式,终止后台运行的预览服务器进程
- 删除生成的报告目录,保持项目目录整洁
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时,向用户告知结果可能受网络状态影响