Lighthouse
运行 Google Lighthouse 来测量网页质量，并验证修复是否真正推动了指标。Lighthouse 对 URL 进行性能、无障碍、SEO 和最佳实践方面的审计，返回每个类别的 0–100 分以及一份包含具体建议的失败审核列表。
何时使用此技能
该技能负责测量。配套的质量技能负责修复。工作流是一个循环：
测量（此技能） → 修复（性能/无障碍/SEO/最佳实践） → 重新测量
当需要获取基准分数、找出具体失败的审核、设置性能预算、在 CI 中门控构建，或证明某次改动提高了（或降低了）指标时，请使用此技能。不要猜测改进——先测量，改动一处，再测量一次。
工作原理
- 选择一个目标 URL——可以是已部署的 URL，也可以是本地开发/预览服务器（如
http://localhost:3000）。 - 运行 Lighthouse——优先使用
scripts/run-lighthouse.sh <url>；它会运行多次，取中位值，并输出紧凑的 JSON（完整报告过于庞大且浪费上下文）。 - 从 JSON 中读取分类得分和失败审核。
- 将每个失败审核映射到相应的修复技能。
- 重新运行，并报告前后差值。
安装与运行（CLI）
Lighthouse 的 README 推荐全局安装（需要 Node 22 LTS+），并且它需要驱动本地已安装的 Chrome/Chromium：
npm install -g lighthouse
# 或：yarn global add lighthouse
lighthouse https://example.com --view # 基本运行；--view 打开 HTML 报告
Lighthouse 会自动检测已安装的 Chrome；也可以通过 CHROME_PATH 环境变量指定特定的二进制文件。
如果想快速一次性地运行，而不进行全局安装，也可以使用 npx lighthouse <url>——发布的 CLI 二进制文件支持此用法，尽管官方文档只介绍了全局安装方式。
面向 Agent 的机器可读运行（JSON 输出到文件，静音，无头模式）：
npx lighthouse https://example.com \
--quiet \
--chrome-flags="--headless=new" \
--only-categories=performance,accessibility,seo,best-practices \
--output=json --output-path=./lh.json
包装脚本（推荐）
scripts/run-lighthouse.sh 对 CLI 进行了封装，运行 N 次，选择中位运行（Lighthouse 推荐的做法以减少方差），并将紧凑的 JSON 打印到标准输出——仅包含分类得分和失败审核。人类可读的日志则输出到标准错误。
# 用法：run-lighthouse.sh <url> [运行次数] [类别]
skills/lighthouse/scripts/run-lighthouse.sh https://example.com 3
skills/lighthouse/scripts/run-lighthouse.sh http://localhost:3000 5 performance,accessibility
示例输出：
{
"success": true,
"url": "https://example.com",
"runs": 3,
"lighthouseVersion": "13.x",
"scores": { "performance": 78, "accessibility": 95, "seo": 92, "best-practices": 96 },
"failingAudits": [
{ "id": "largest-contentful-paint", "score": 0.4, "displayValue": "4.2 s" },
{ "id": "unused-javascript", "score": 0.3, "displayValue": "Potential savings of 180 KiB" }
]
}
关键标志
| 标志 | 用途 |
|---|---|
| `--output=json | html |
--output-path=<path> | 报告写入路径 |
--only-categories=… | 限制为 performance,accessibility,seo,best-practices |
--preset=desktop | 桌面端配置（默认是移动端：模拟中端手机 + 慢速 4G） |
--chrome-flags="--headless=new" | 无头模式运行（CI/服务器） |
--budget-path=budget.json | 强制执行性能预算（LightWallet） |
| `--throttling-method=simulate | devtools |
--quiet | 抑制进度日志 |
--view | 运行完成后打开 HTML 报告 |
读取 JSON
得分是以 0–1 的浮点数表示，位于 categories 下；审核详情位于 audits 下。
# 分类得分（0–1）→ 乘以 100 得到熟悉的百分制分数
jq '.categories | to_entries | map({(.key): (.value.score)}) | add' lh.json
# 核心网页指标（实验室值）
jq '.audits | {
LCP: .["largest-contentful-paint"].displayValue,
CLS: .["cumulative-layout-shift"].displayValue,
TBT: .["total-blocking-time"].displayValue
}' lh.json
# 值得关注的失败/优化审核
jq '[.audits[] | select(.score != null and .score < 0.9)
| {id, score, displayValue}]' lh.json
性能预算（LightWallet）
当资源或时间超过阈值时，判定运行失败。此技能附带了一个可直接编辑的 examples/budget.json 文件；其格式如下：
[
{
"path": "/*",
"timings": [
{ "metric": "largest-contentful-paint", "budget": 2500 },
{ "metric": "interactive", "budget": 3800 }
],
"resourceSizes": [
{ "resourceType": "script", "budget": 300 },
{ "resourceType": "stylesheet", "budget": 100 },
{ "resourceType": "image", "budget": 500 },
{ "resourceType": "total", "budget": 1500 }
],
"resourceCounts": [
{ "resourceType": "third-party", "budget": 10 }
]
}
]
lighthouse https://example.com --budget-path=budget.json --output=json --output-path=./lh.json
大小单位为 KB，时间单位为 ms。预算结果会出现在 JSON 中的 performance-budget 和 timing-budget 审核条目下。
实验室数据 vs. 现场数据——在使用数值前请阅读此内容
Lighthouse 是一个实验室工具：一次模拟加载，使用模拟硬件，配合模拟节流。它可重复性好，非常适合发现回归，但不等于真实用户体验。
- 方差真实存在。 单次运行可能波动 ±5–10 分。请至少运行 3 次并取中位值（包装脚本已实现此功能）。
- 如需真实用户数据，请使用现场来源：CrUX、PageSpeed Insights（同时显示实验室和现场数据）、Search Console 的核心网页指标报告，或
web-vitals库上报到您的分析系统。 - INP 无法在单次 Lighthouse 加载中测量——它需要真实的用户交互。Lighthouse 报告总阻塞时间（TBT）作为其实验室代理指标；请以现场 INP 数据为准。
Lighthouse v13 说明（Insight Audits）
自 v13（2025 年 10 月+）起，Lighthouse 将性能迁移到了 Insight Audits。多个原有的针对特定优化的审核 ID 被合并或移除（例如 CLS 相关审核 → cls-culprits-insight，图片审核 → image-delivery-insight）。建议内容未变，仅审核 ID 和报告分组发生了变化。在解析旧报告时，将其视为超集而非矛盾。在 CI 中固定 Lighthouse 版本，以确保您依赖的审核 ID 保持稳定。
性能得分是如何构成的
性能得分是多个实验室指标的加权组合（权重在不同版本间会有变化）。在最近版本中，主要指标大致如下：
| 指标 | 近似权重 |
|---|---|
| 总阻塞时间（TBT） | ~30% |
| 最大内容绘制时间（LCP） | ~25% |
| 累计布局偏移（CLS） | ~25% |
| 首次内容绘制时间（FCP） | ~10% |
| 速度指数 | ~10% |
由于 TBT/LCP/CLS 占主导地位，修复它们能最大程度地提高得分。使用 Lighthouse 得分计算器 可以精确了解某个指标变化如何映射到得分上。
CI 与编程 API
为了方便查阅，以下内容以引用形式给出：
- 持续集成——
@lhci/cli、lighthouserc.js断言以及 GitHub Actions 工作流：references/CI.md - 编程（Node）API——使用
chrome-launcher驱动 Lighthouse，支持自定义流程、用户流程和批量运行：references/PROGRAMMATIC-API.md
将审核映射到修复技能
| Lighthouse 分类 | 使用以下技能修复 |
|---|---|
| 性能 / 核心网页指标 | 性能或核心网页指标技能 |
| 无障碍 | 无障碍 / WCAG 技能 |
| SEO | SEO 技能 |
| 最佳实践 | 安全 / 最佳实践技能 |
此技能与 addyosmani/web-quality-skills 配合使用，构成循环的修复部分。