Back to Details

lighthouse-auditor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Lighthouse Auditor

Lighthouse 审计工具

Overview

概述

Use this skill to handle Lighthouse work end to end: verify the environment, fix browser-launch problems, run the right audit profile, and turn raw reports into prioritized recommendations.
使用此技能端到端处理Lighthouse相关工作：验证环境、修复浏览器启动问题、选择合适的审计配置文件，并将原始报告转换为优先级明确的优化建议。

Core Workflow

核心工作流程

  1. Identify the audit scope.
  2. Prepare the execution environment.
  3. Choose the right audit profile.
  4. Run the audit and save HTML plus JSON output.
  5. Summarize scores, metrics, opportunities, and next actions.
  1. 确定审计范围
  2. 准备执行环境
  3. 选择合适的审计配置文件
  4. 运行审计并保存HTML和JSON输出结果
  5. 总结评分、指标、优化机会及后续行动建议

1. Identify the Audit Scope

1. 确定审计范围

Collect the minimum missing context before touching the environment:
  • Target URL or URLs.
  • Localhost, staging, or production.
  • Mobile, desktop, or both.
  • One-off run, comparison, or batch audit.
  • Manual analysis or CI/CD integration.
If the user does not specify, default to one single-URL audit with one run for 
mobile
and one run for 
desktop
.
在操作环境前，先收集必要的上下文信息：
  • 目标URL或多个URL
  • 本地环境、预发布环境还是生产环境
  • 移动设备、桌面设备还是两者兼顾
  • 单次运行、对比分析还是批量审计
  • 手动分析还是CI/CD集成
如果用户未明确指定，默认采用单URL审计，分别针对
mobile
和
desktop
各运行一次。

2. Prepare the Execution Environment

2. 准备执行环境

Start with:
bash
bash scripts/ensure_lighthouse_env.sh --check
bash scripts/clean_lighthouse_temp.sh
If you need shell exports for a raw Lighthouse command, use:
bash
eval "$(bash scripts/ensure_lighthouse_env.sh --print-shell)"
Then act on the result:
  • If the global 
    lighthouse
    binary is missing and 
    npm
    is available, install it with 
    npm install -g lighthouse
    , or use 
    npx --yes lighthouse
    for a one-off run.
  • If Node.js or npm is missing, install Node.js 18+ LTS before continuing.
  • If the environment is WSL, prefer a Linux-native browser. Do not point Lighthouse to a Windows Chrome binary under 
    /mnt/c/...
    .
  • In WSL, prefer 
    /usr/bin/google-chrome-stable
    over Chromium. If Chrome Stable is missing, install it before trying to debug launcher failures.
  • In WSL, 
    CHROME_PATH
    alone is not always enough. 
    chrome-launcher
    may also require a valid Windows Local Temp path in 
    PATH
    . Use 
    ensure_lighthouse_env.sh --print-shell
    or the bundled wrapper so that fix is applied automatically.
  • If the user wants the agent to install missing dependencies directly, rerun 
    scripts/ensure_lighthouse_env.sh
    with 
    --install-lighthouse
    , 
    --install-browser
    , or 
    --install-all
    .
  • If browser launch fails with 
    Cannot find Chrome
    , 
    ECONNREFUSED 127.0.0.1
    , or similar launcher errors, read references/wsl-chrome-fix.md and apply it exactly.
  • Do not declare Lighthouse blocked in WSL until you have tried the explicit fallback sequence from 
    references/wsl-chrome-fix.md
    , including the exact raw Lighthouse command with 
    --chrome-flags="--headless --no-sandbox --disable-gpu"
    after exporting the environment fix.
When installation needs network access, 
sudo
, or package-manager changes, ask for approval and state exactly what will be installed.
首先执行以下脚本：
bash
bash scripts/ensure_lighthouse_env.sh --check
bash scripts/clean_lighthouse_temp.sh
如果需要为原生Lighthouse命令配置Shell环境变量，执行：
bash
eval "$(bash scripts/ensure_lighthouse_env.sh --print-shell)"
然后根据结果进行相应处理：
  • 如果全局
    lighthouse
    二进制文件缺失且
    npm
    可用，通过
    npm install -g lighthouse
    安装，或使用
    npx --yes lighthouse
    进行单次运行。
  • 如果Node.js或npm缺失，先安装Node.js 18+ LTS版本。
  • 如果运行环境是WSL，优先使用Linux原生浏览器，不要将Lighthouse指向
    /mnt/c/...
    路径下的Windows Chrome二进制文件。
  • 在WSL环境中，优先使用
    /usr/bin/google-chrome-stable
    而非Chromium。如果Chrome Stable缺失，先安装再调试启动器故障。
  • 在WSL环境中，仅设置
    CHROME_PATH
    往往不够。
    chrome-launcher
    可能还需要在
    PATH
    中配置有效的Windows本地临时目录路径。使用
    ensure_lighthouse_env.sh --print-shell
    或捆绑的包装器脚本可自动应用此修复。
  • 如果用户希望工具直接安装缺失的依赖项，可添加
    --install-lighthouse
    、
    --install-browser
    或
    --install-all
    参数重新运行
    scripts/ensure_lighthouse_env.sh
    。
  • 如果浏览器启动失败并提示“Cannot find Chrome”、“ECONNREFUSED 127.0.0.1”或类似启动器错误，请阅读references/wsl-chrome-fix.md并严格按照步骤操作。
  • 在未尝试
    references/wsl-chrome-fix.md
    中明确的回退流程（包括导出环境修复后，使用带有
    --chrome-flags="--headless --no-sandbox --disable-gpu"
    参数的原生Lighthouse命令）前，不要判定WSL环境下Lighthouse无法运行。
当安装需要网络访问、
sudo
权限或修改包管理器配置时，需先征得用户同意，并明确说明将要安装的内容。

3. Choose the Right Audit Profile

3. 选择合适的审计配置文件

Use these defaults unless the user asks for something else:
  • Quick manual review: 
    1
    run.
  • Baseline or stakeholder report: 
    3
    runs and compare patterns instead of trusting one noisy result.
  • Default device scope: run both 
    mobile
    and 
    desktop
    .
  • Mobile audit: default Lighthouse behavior.
  • Desktop audit: 
    --preset=desktop
    .
  • Local development server: 
    --throttling-method=provided
    .
  • CI or headless Linux: 
    --chrome-flags="--headless --no-sandbox --disable-dev-shm-usage"
    .
  • WSL launcher-sensitive environment: 
    --chrome-flags="--headless --no-sandbox --disable-gpu"
    .
For advanced settings, budgets, and custom configs, read references/config-and-budgets.md.
除非用户有特殊要求，否则使用以下默认配置：
  • 快速手动审核：运行
    1
    次
  • 基准报告或面向利益相关者的报告：运行
    3
    次，通过对比结果模式而非单次可能存在误差的结果得出结论
  • 默认设备范围：同时运行
    mobile
    和
    desktop
    审计
  • 移动设备审计：使用Lighthouse默认行为
  • 桌面设备审计：添加
    --preset=desktop
    参数
  • 本地开发服务器：添加
    --throttling-method=provided
    参数
  • CI或无头Linux环境：添加
    --chrome-flags="--headless --no-sandbox --disable-dev-shm-usage"
    参数
  • 对WSL启动器敏感的环境：添加
    --chrome-flags="--headless --no-sandbox --disable-gpu"
    参数
如需高级设置、性能预算和自定义配置，请阅读references/config-and-budgets.md。

4. Run the Audit

4. 运行审计

Prefer the bundled wrapper for repeatable work:
bash
bash scripts/run_lighthouse_audit.sh https://example.com
By default, the wrapper creates 
./lighthouse-audit-results
in the current working directory, so reports stay inside the project where the audit was executed. By default, it generates separate report pairs for 
mobile
and 
desktop
. In WSL, it also cleans temporary Chrome/Lighthouse profile directories automatically so only the final reports remain in the project. The wrapper prefers the global 
lighthouse
binary, but if it is missing and 
npx
is available it can fall back to 
npx --yes lighthouse
. If a previous failed run already left stray folders in the project root, run 
bash scripts/clean_lighthouse_temp.sh
before or after the audit.
Common variations:
bash
undefined
对于可重复执行的任务，优先使用捆绑的包装器脚本：
bash
bash scripts/run_lighthouse_audit.sh https://example.com
默认情况下，包装器会在当前工作目录创建
./lighthouse-audit-results
文件夹，确保报告保存在审计执行的项目目录内。默认会分别为
mobile
和
desktop
生成独立的报告文件。在WSL环境中，它还会自动清理临时Chrome/Lighthouse配置文件目录，仅保留项目中的最终报告。包装器优先使用全局
lighthouse
二进制文件，如果缺失且
npx
可用，则会回退到
npx --yes lighthouse
。
如果之前的失败运行已在项目根目录留下零散文件夹，可在审计前后运行
bash scripts/clean_lighthouse_temp.sh
清理。
常见参数变体：
bash
undefined

Desktop

桌面设备审计

bash scripts/run_lighthouse_audit.sh https://example.com --preset desktop
bash scripts/run_lighthouse_audit.sh https://example.com --preset desktop

Mobile only

仅移动设备审计

bash scripts/run_lighthouse_audit.sh https://example.com --preset mobile
bash scripts/run_lighthouse_audit.sh https://example.com --preset mobile

Local dev server

本地开发服务器审计

bash scripts/run_lighthouse_audit.sh http://localhost:3000 --throttling-method provided
bash scripts/run_lighthouse_audit.sh http://localhost:3000 --throttling-method provided

Three-run comparison

三次运行对比分析

bash scripts/run_lighthouse_audit.sh https://example.com --runs 3
bash scripts/run_lighthouse_audit.sh https://example.com --runs 3

Only performance

仅审计性能指标

bash scripts/run_lighthouse_audit.sh https://example.com --only-categories performance

Use raw `lighthouse` commands only when a wrapper script would get in the way of a very custom case.
In WSL, prefer the wrapper even more strongly because it injects the launcher-specific environment fix automatically.

If you need to prove whether raw Lighthouse works in WSL, use this exact sequence before concluding the environment is blocked:

```bash
eval "$(bash scripts/ensure_lighthouse_env.sh --print-shell)"
lighthouse https://example.com --chrome-flags="--headless --no-sandbox --disable-gpu"
If the global binary is not installed but 
npx
is available, run the same fallback with:
bash
eval "$(bash scripts/ensure_lighthouse_env.sh --print-shell)"
npx --yes lighthouse https://example.com --chrome-flags="--headless --no-sandbox --disable-gpu"
After any raw fallback attempt in WSL, run:
bash
bash scripts/clean_lighthouse_temp.sh
If those exact sequences still fail, report the exact stderr and classify it as an environment/runtime issue.
Always save both HTML and JSON output so the report can be opened visually and analyzed programmatically. When running both device profiles, keep the output sets separate and compare them explicitly.
bash scripts/run_lighthouse_audit.sh https://example.com --only-categories performance

仅在包装器脚本会阻碍自定义需求的极端情况下，才使用原生`lighthouse`命令。在WSL环境中，更推荐使用包装器脚本，因为它会自动注入启动器相关的环境修复。

如果需要验证WSL环境中原生Lighthouse是否可运行，请先执行以下完整步骤再判定环境是否受阻：

```bash
eval "$(bash scripts/ensure_lighthouse_env.sh --print-shell)"
lighthouse https://example.com --chrome-flags="--headless --no-sandbox --disable-gpu"
如果全局二进制文件未安装但
npx
可用，可使用以下回退命令：
bash
eval "$(bash scripts/ensure_lighthouse_env.sh --print-shell)"
npx --yes lighthouse https://example.com --chrome-flags="--headless --no-sandbox --disable-gpu"
在WSL环境中执行任何原生回退尝试后，都要运行：
bash
bash scripts/clean_lighthouse_temp.sh
如果上述步骤仍失败，请提供完整的标准错误输出，并将其归类为环境/运行时问题。
请始终同时保存HTML和JSON格式的输出结果，以便可视化查看报告并进行程序化分析。当同时审计两种设备配置时，请将输出文件分开保存并进行明确对比。

5. Summarize and Explain Results

5. 总结与解读结果

After a run completes, summarize the JSON report with:
bash
python3 scripts/summarize_lighthouse_report.py path/to/report.report.json
Present the results in this order:
  1. Audit scope and command profile used.
  2. Category scores.
  3. Core Web Vitals and related timing metrics.
  4. Top three opportunities by estimated savings.
  5. Critical diagnostics or failing audits.
  6. Prioritized next actions.
Use references/interpreting-results.md when you need symptom-to-root-cause guidance or more detailed remediation ideas.
审计完成后，可通过以下脚本总结JSON报告：
bash
python3 scripts/summarize_lighthouse_report.py path/to/report.report.json
请按照以下顺序呈现结果：
  1. 审计范围及使用的命令配置
  2. 各维度评分
  3. Core Web Vitals及相关计时指标
  4. 预估优化收益最高的三个机会点
  5. 关键诊断信息或未通过的审计项
  6. 优先级明确的后续行动建议
如需从症状定位根因或获取更详细的修复方案，请参考references/interpreting-results.md。

Batch and CI/CD Work

批量审计与CI/CD集成

For multiple URLs, read references/batch-analysis.md.
For GitHub Actions, GitLab CI, or Lighthouse CI, read references/ci-cd.md.
When running many URLs:
  • Keep concurrency modest to avoid distorting scores.
  • Reuse the same Chrome flags across the whole batch.
  • Compare medians or repeated patterns, not a single best run.
如需审计多个URL，请阅读references/batch-analysis.md。
如需集成GitHub Actions、GitLab CI或Lighthouse CI，请阅读references/ci-cd.md。
当审计大量URL时：
  • 控制并发数，避免影响评分准确性
  • 所有批量任务使用相同的Chrome参数
  • 对比中位数或重复出现的模式，而非单次最佳结果

Reporting Standard

报告标准

A complete answer should normally include:
  • What was audited and under which profile.
  • The generated report locations.
  • Category scores with a short interpretation.
  • Core Web Vitals with threshold context.
  • The biggest performance opportunities.
  • The most likely root causes.
  • A short, prioritized action plan.
完整的回复应包含以下内容：
  • 审计对象及使用的配置文件
  • 生成报告的存储位置
  • 各维度评分及简要解读
  • Core Web Vitals及阈值上下文说明
  • 影响最大的性能优化机会
  • 最可能的根因分析
  • 简短、优先级明确的行动方案

Resources

资源列表

  • scripts/ensure_lighthouse_env.sh
    : Check and optionally install Lighthouse plus a usable browser, with WSL-specific Chrome handling.
  • scripts/clean_lighthouse_temp.sh
    : Remove stray Chrome/Lighthouse temp directories that may be materialized in the project root by WSL launcher failures.
  • scripts/run_lighthouse_audit.sh
    : Run a single or repeated audit with sensible defaults and stable output naming.
  • scripts/summarize_lighthouse_report.py
    : Extract scores, metrics, opportunities, and failing audits from a Lighthouse JSON report.
  • references/wsl-chrome-fix.md: Exact recovery steps for WSL Chrome launcher failures.
  • references/interpreting-results.md: Read and explain Lighthouse output.
  • references/config-and-budgets.md: Advanced config files and performance budgets.
  • references/batch-analysis.md: Batch auditing patterns and comparisons.
  • references/ci-cd.md: GitHub Actions, GitLab CI, and Lighthouse CI templates.
  • scripts/ensure_lighthouse_env.sh
    ：检查并可选安装Lighthouse及可用浏览器，包含WSL环境下Chrome的特殊处理逻辑
  • scripts/clean_lighthouse_temp.sh
    ：清理因WSL启动器故障可能遗留在项目根目录的Chrome/Lighthouse临时目录
  • scripts/run_lighthouse_audit.sh
    ：使用合理的默认配置运行单次或多次审计，并生成命名规范的输出文件
  • scripts/summarize_lighthouse_report.py
    ：从Lighthouse JSON报告中提取评分、指标、优化机会及未通过的审计项
  • references/wsl-chrome-fix.md：WSL环境下Chrome启动器故障的精确修复步骤
  • references/interpreting-results.md：Lighthouse报告解读指南
  • references/config-and-budgets.md：高级配置文件与性能预算说明
  • references/batch-analysis.md：批量审计模式与对比分析方法
  • references/ci-cd.md：GitHub Actions、GitLab CI及Lighthouse CI配置模板