lighthouse

Google Lighthouse

Google Lighthouse 综合参考——这是一款用于提升网页质量的开源自动化工具，包含性能、无障碍、渐进式 Web 应用、SEO 等方面的审计。

来源： https://github.com/GoogleChrome/lighthouse
NPM 包： https://www.npmjs.com/package/lighthouse
文档： https://developer.chrome.com/docs/lighthouse/overview/

前置条件

要求

• Node.js： 版本 22（LTS）或更高版本
• Chrome/Chromium： 版本 66.0 或更高版本

安装

# Global installation (recommended)
npm install -g lighthouse

# Or use yarn
yarn global add lighthouse

# Verify installation
lighthouse --version

Chrome 设置

Lighthouse 使用 Chrome/Chromium。你可以：

• 使用现有的 Chrome/Chrome Canary 安装
• 通过 CHROME_PATH 环境变量指定自定义 Chrome 二进制文件
• 通过 --chrome-flags 传递自定义标志

快速开始

# Basic audit - generates HTML report
lighthouse https://example.com

# View report immediately in browser
lighthouse https://example.com --view

# JSON output to stdout
lighthouse https://example.com --output json

# Save to specific path
lighthouse https://example.com --output-path ./report.html

CLI 选项

输出选项

lighthouse <url> --output <format> --output-path <path>

# Output formats (can use multiple)
--output html          # HTML report (default)
--output json          # JSON output
--output csv           # CSV output

# Examples
lighthouse https://example.com --output json                    # JSON to stdout
lighthouse https://example.com --output html --output-path ./audit.html
lighthouse https://example.com --output json --output html      # Both formats

审计类别

# Run specific categories only
lighthouse https://example.com --only-categories=performance,accessibility

# Available categories:
# - performance
# - accessibility
# - best-practices
# - seo
# - pwa (Progressive Web App)

# Skip specific audits
lighthouse https://example.com --skip-audits=unused-javascript,offscreen-images

# List all available audits
lighthouse --list-all-audits

预设与设备模拟

# Use built-in presets
lighthouse https://example.com --preset=desktop    # Desktop preset
lighthouse https://example.com --preset=perf       # Performance only
lighthouse https://example.com --preset=experimental  # Experimental audits

# Form factor
lighthouse https://example.com --form-factor=mobile   # Mobile (default)
lighthouse https://example.com --form-factor=desktop  # Desktop

# Screen emulation
lighthouse https://example.com --screenEmulation.mobile
lighthouse https://example.com --screenEmulation.width=1280 --screenEmulation.height=720
lighthouse https://example.com --screenEmulation.disabled  # Disable emulation

网络与 CPU 限流

# Throttling methods
--throttling-method=simulate    # Simulate throttling (default, fastest)
--throttling-method=devtools    # Use DevTools throttling
--throttling-method=provided    # No throttling

# Custom throttling settings
--throttling.rttMs=150                    # Network RTT
--throttling.throughputKbps=1600          # Download speed
--throttling.cpuSlowdownMultiplier=4      # CPU slowdown

Chrome 配置

# Custom Chrome path (via environment variable)
CHROME_PATH=/path/to/chrome lighthouse https://example.com

# Chrome flags
lighthouse https://example.com --chrome-flags="--headless --no-sandbox"
lighthouse https://example.com --chrome-flags="--window-size=412,660"
lighthouse https://example.com --chrome-flags="--disable-gpu --disable-dev-shm-usage"

# Debug protocol settings
--port=9222                    # Use specific debugging port
--hostname=localhost           # Custom hostname

高级选项

# Max wait time for page load (milliseconds)
--max-wait-for-load=60000

# Save assets (trace and devtools log)
--save-assets

# Disable full page screenshot (reduces report size)
--disable-full-page-screenshot

# Disable storage reset (keep cache/cookies)
--disable-storage-reset

# Block URL patterns
--blocked-url-patterns="*.png" --blocked-url-patterns="*.jpg"

# Extra HTTP headers
--extra-headers="{\"Cookie\":\"monster=blue\", \"Authorization\":\"Bearer token\"}"

# Locale/language for report
--locale=en

# Plugins
--plugins=lighthouse-plugin-field-performance

生命周期模式

收集模式（收集产物）

# Collect artifacts and save to disk
lighthouse https://example.com --gather-mode

# Save to custom folder
lighthouse https://example.com -G=./artifacts/

# Collects: trace, devtools log, page artifacts

审计模式（处理已保存的产物）

# Process previously saved artifacts
lighthouse --audit-mode

# Load from custom folder
lighthouse -A=./artifacts/

# Skips browser interaction, runs audits on saved data

组合模式

# Normal run + save artifacts for later
lighthouse https://example.com -GA

# With custom folder
lighthouse https://example.com -GA=./my-run/

配置文件

创建 lighthouse-config.js：

module.exports = {
  extends: 'lighthouse:default',
  settings: {
    formFactor: 'desktop',
    throttling: {
      rttMs: 40,
      throughputKbps: 10240,
      cpuSlowdownMultiplier: 1,
    },
    screenEmulation: {
      mobile: false,
      width: 1350,
      height: 940,
      deviceScaleFactor: 1,
      disabled: false,
    },
    emulatedUserAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)',
    onlyCategories: ['performance', 'accessibility', 'best-practices', 'seo'],
  },
};

使用方法：

lighthouse https://example.com --config-path=./lighthouse-config.js

查看报告

HTML 报告

# Auto-open in browser
lighthouse https://example.com --view

# Open report manually
open ./example.com_2024-01-01.report.html

JSON 报告

# Generate JSON
lighthouse https://example.com --output=json --output-path=./report.json

# View online at Lighthouse Viewer
cat ./report.json | xclip -selection clipboard
# Then visit: https://googlechrome.github.io/lighthouse/viewer/

在线查看器

将 JSON 报告上传到：https://googlechrome.github.io/lighthouse/viewer/

• 拖放 JSON 文件
• 将报告分享到私密 GitHub gist
• 比较历史报告

常见用例

移动设备性能审计

lighthouse https://example.com \
  --form-factor=mobile \
  --only-categories=performance \
  --preset=perf \
  --view

桌面端完整审计

lighthouse https://example.com \
  --preset=desktop \
  --view

CI/CD 集成

# Quiet mode for CI
lighthouse https://example.com --quiet --chrome-flags="--headless --no-sandbox"

# JSON output for programmatic processing
lighthouse https://example.com --output=json --quiet > report.json

批量审计

# Audit multiple URLs
for url in https://example.com https://example.com/about; do
  lighthouse "$url" --output=json --output-path="./reports/$(echo $url | sed 's/[^a-zA-Z0-9]/_/g').json"
done

需要身份验证的页面

# Pass authentication cookies
lighthouse https://example.com/dashboard \
  --extra-headers="{\"Cookie\":\"sessionid=abc123; auth_token=xyz\"}"

# Or use config file for complex auth

性能预算

Lighthouse 本身不会强制执行预算，但你可以结合 lighthouse-ci 使用：

# Install lighthouse-ci
npm install -g @lhci/cli

# Run with assertions
lhci autorun --config=lighthouserc.js

lighthouserc.js 示例：

module.exports = {
  ci: {
    assert: {
      assertions: {
        'categories:performance': ['warn', {minScore: 0.9}],
        'categories:accessibility': ['error', {minScore: 1}],
        'first-contentful-paint': ['warn', {maxNumericValue: 2000}],
      },
    },
  },
};

故障排除

Chrome 无法启动

# Try headless mode
lighthouse https://example.com --chrome-flags="--headless --no-sandbox --disable-gpu"

# Check Chrome version
chrome --version  # Should be 66+

# Specify Chrome path
CHROME_PATH=/usr/bin/google-chrome-stable lighthouse https://example.com

连接问题

# Use specific port
lighthouse https://example.com --port=9222

# Allow more time for page load
lighthouse https://example.com --max-wait-for-load=90000

过大的跟踪文件

# Disable full page screenshot
lighthouse https://example.com --disable-full-page-screenshot

# Don't save assets
# (don't use --save-assets)

关键指标参考

指标	目标	描述
性能得分	90+	总体性能得分（0-100）
首次内容绘制（FCP）	< 1.8s	首次绘制文本/图像
最大内容绘制（LCP）	< 2.5s	最大元素绘制时间
总阻塞时间（TBT）	< 200ms	主线程阻塞时间
累积布局偏移（CLS）	< 0.1	视觉稳定性得分
速度指数	< 3.4s	视觉完整性速度

相关工具

• Lighthouse CI：用于 Lighthouse 的持续集成
• Lighthouse Viewer：在线报告查看器
• Lighthouse CLI：此工具（也提供 Node 模块）
• Chrome DevTools：内置的 Lighthouse 面板

资源

• GitHub：https://github.com/GoogleChrome/lighthouse
• 文档：https://developer.chrome.com/docs/lighthouse/
• 评分指南：https://developer.chrome.com/docs/lighthouse/performance/performance-scoring/
• Stack Overflow：https://stackoverflow.com/questions/tagged/lighthouse