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

ライフサイクルモード

Gather モード（アーティファクトを収集）

# 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

Audit モード（保存済みのアーティファクトを処理）

# 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）
First Contentful Paint（FCP）	< 1.8s	テキストまたは画像が最初に描画されるまでの時間
Largest Contentful Paint（LCP）	< 2.5s	最大の要素が描画されるまでの時間
Total Blocking Time（TBT）	< 200ms	メインスレッドがブロックされている時間
Cumulative Layout Shift（CLS）	< 0.1	視覚的な安定性のスコア
Speed Index	< 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