CLI 选项

输出选项

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

# 输出格式（可使用多个）
--output html          # HTML 报告（默认）
--output json          # JSON 输出
--output csv           # CSV 输出

# 示例
lighthouse https://example.com --output json                    # JSON 输出到标准输出
lighthouse https://example.com --output html --output-path ./audit.html
lighthouse https://example.com --output json --output html      # 两种格式都输出

审计类别

# 仅运行特定类别
lighthouse https://example.com --only-categories=performance,accessibility

# 可用类别：
# - performance
# - accessibility
# - best-practices
# - seo
# - pwa (渐进式 Web 应用)

# 跳过特定审计
lighthouse https://example.com --skip-audits=unused-javascript,offscreen-images

# 列出所有可用审计
lighthouse --list-all-audits

预设和设备模拟

# 使用内置预设
lighthouse https://example.com --preset=desktop    # 桌面预设
lighthouse https://example.com --preset=perf       # 仅性能
lighthouse https://example.com --preset=experimental  # 实验性审计

# 设备形态
lighthouse https://example.com --form-factor=mobile   # 移动设备（默认）
lighthouse https://example.com --form-factor=desktop  # 桌面设备

# 屏幕模拟
lighthouse https://example.com --screenEmulation.mobile
lighthouse https://example.com --screenEmulation.width=1280 --screenEmulation.height=720
lighthouse https://example.com --screenEmulation.disabled  # 禁用模拟

网络和 CPU 节流

# 节流方法
--throttling-method=simulate    # 模拟节流（默认，最快）
--throttling-method=devtools    # 使用 DevTools 节流
--throttling-method=provided    # 无节流

# 自定义节流设置
--throttling.rttMs=150                    # 网络往返时间
--throttling.throughputKbps=1600          # 下载速度
--throttling.cpuSlowdownMultiplier=4      # CPU 降速倍数

Chrome 配置

# 自定义 Chrome 路径（通过环境变量）
CHROME_PATH=/path/to/chrome lighthouse https://example.com

# Chrome 标志
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"

# 调试协议设置
--port=9222                    # 使用特定调试端口
--hostname=localhost           # 自定义主机名

高级选项

# 页面加载最大等待时间（毫秒）
--max-wait-for-load=60000

# 保存资源（跟踪和 devtools 日志）
--save-assets

# 禁用全页面截图（减小报告大小）
--disable-full-page-screenshot

# 禁用存储重置（保留缓存/cookies）
--disable-storage-reset

# 阻止 URL 模式
--blocked-url-patterns="*.png" --blocked-url-patterns="*.jpg"

# 额外的 HTTP 头部
--extra-headers="{\"Cookie\":\"monster=blue\", \"Authorization\":\"Bearer token\"}"

# 报告的语言环境/语言
--locale=en

# 插件
--plugins=lighthouse-plugin-field-performance

生命周期模式

收集模式（收集工件）

# 收集工件并保存到磁盘
lighthouse https://example.com --gather-mode

# 保存到自定义文件夹
lighthouse https://example.com -G=./artifacts/

# 收集内容：跟踪、devtools 日志、页面工件

审计模式（处理已保存的工件）

# 处理先前保存的工件
lighthouse --audit-mode

# 从自定义文件夹加载
lighthouse -A=./artifacts/

# 跳过浏览器交互，对保存的数据运行审计

组合模式

# 正常运行 + 保存工件供以后使用
lighthouse https://example.com -GA

# 使用自定义文件夹
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 报告

# 在浏览器中自动打开
lighthouse https://example.com --view

# 手动打开报告
open ./example.com_2024-01-01.report.html

JSON 报告

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

# 在 Lighthouse Viewer 在线查看
cat ./report.json | xclip -selection clipboard
# 然后访问：https://googlechrome.github.io/lighthouse/viewer/

在线查看器

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

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

常见用例

移动设备性能审计

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

桌面设备全面审计

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

CI/CD 集成

# CI 的安静模式
lighthouse https://example.com --quiet --chrome-flags="--headless --no-sandbox"

# 用于程序化处理的 JSON 输出
lighthouse https://example.com --output=json --quiet > report.json

批量审计

# 审计多个 URL
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

需要身份验证的页面

# 传递身份验证 cookies
lighthouse https://example.com/dashboard \
  --extra-headers="{\"Cookie\":\"sessionid=abc123; auth_token=xyz\"}"

# 或使用配置文件处理复杂身份验证

性能预算

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

# 安装 lighthouse-ci
npm install -g @lhci/cli

# 使用断言运行
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 无法启动

# 尝试无头模式
lighthouse https://example.com --chrome-flags="--headless --no-sandbox --disable-gpu"

# 检查 Chrome 版本
chrome --version  # 应为 66+

# 指定 Chrome 路径
CHROME_PATH=/usr/bin/google-chrome-stable lighthouse https://example.com

连接问题

# 使用特定端口
lighthouse https://example.com --port=9222

# 允许更长的页面加载时间
lighthouse https://example.com --max-wait-for-load=90000

跟踪文件过大

# 禁用全页面截图
lighthouse https://example.com --disable-full-page-screenshot

# 不保存资源
# （不要使用 --save-assets）

关键指标参考

相关工具

• 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

每周安装量

103

代码仓库

onnokh/lighthouse

首次出现

2026年2月2日

安全审计

Gen Agent Trust HubWarnSocketPassSnykFail

安装于

codex98

opencode97

gemini-cli96

github-copilot89

kimi-cli79

amp78

Quick Start

# 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 Options

Output Options

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

Audit Categories

# 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

Presets & Device Emulation

# 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

Network & CPU Throttling

# 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 Configuration

# 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

Advanced Options

# 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

Lifecycle Modes

Gather Mode (Collect Artifacts)

# 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 Mode (Process Saved Artifacts)

# Process previously saved artifacts
lighthouse --audit-mode

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

# Skips browser interaction, runs audits on saved data

Combined Mode

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

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

Configuration File

Create 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'],
  },
};

Use it:

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

Viewing Reports

HTML Reports

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

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

JSON Reports

# 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/

Online Viewer

Upload JSON reports to: https://googlechrome.github.io/lighthouse/viewer/

• Drag and drop JSON files
• Share reports as secret GitHub gists
• Compare historical reports

Common Use Cases

Mobile Performance Audit

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

Desktop Full Audit

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

CI/CD Integration

# 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

Batch Auditing

# 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

Authenticated Pages

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

# Or use config file for complex auth

Performance Budgets

Lighthouse doesn't enforce budgets natively, but you can combine with lighthouse-ci:

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

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

Example lighthouserc.js:

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

Troubleshooting

Chrome Won't Start

# 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

Connection Issues

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

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

Large Trace Files

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

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

Key Metrics Reference

Related Tools

• Lighthouse CI : Continuous integration for Lighthouse
• Lighthouse Viewer : Online report viewer
• Lighthouse CLI : This tool (Node module also available)
• Chrome DevTools : Built-in Lighthouse panel

Resources

• GitHub : https://github.com/GoogleChrome/lighthouse
• Documentation : https://developer.chrome.com/docs/lighthouse/
• Scoring Guide : https://developer.chrome.com/docs/lighthouse/performance/performance-scoring/
• Stack Overflow : https://stackoverflow.com/questions/tagged/lighthouse

Weekly Installs

103

Repository

onnokh/lighthouse

First Seen

Feb 2, 2026

Security Audits

Gen Agent Trust HubWarnSocketPassSnykFail

Installed on

codex98

opencode97

gemini-cli96

github-copilot89

kimi-cli79

amp78