frontend-lighthouse

用途

frontend-lighthouse 是一个可移植技能，用于给 Web 应用添加 Lighthouse CI 性能门禁，使每个拉取请求在生产构建未达到明确的 Core Web Vitals 预算与分类分数下限时被阻止。它描述的是 CI 性能门禁（一份 Lighthouse CI 配置加一个工作流），不是组件库或视觉风格。该技能与 frontend-seo、frontend-architecture 技能配套：SEO 负责写入元数据，Lighthouse 负责证明其能快速交付。

主要能力

单一配置源：所有预算与断言集中在一份 lighthouserc.cjs 中，每个预算使用命名常量，避免断言对象中埋藏魔法数字。
门禁针对生产构建：Lighthouse 针对 build + start（真实、优化后的输出）运行，不使用开发服务器。
多次运行取中位数：运行 3 次以上并对中位数运行做断言，避免冷缓存、CI 噪声等单次抖动误报健康构建。
预算采用 Google "good" 阈值：LCP ≤ 2500 ms、INP ≤ 200 ms（实验室中以 TBT 代理门禁）、CLS ≤ 0.1。
CI 中阻断并以 artifact 可见：GitHub Action 在每个涉及应用的 PR 上运行门禁，并上传 HTML/JSON 报告，便于调试失败。

使用方式

技能会添加以下文件：

apps/web/                          (或你的应用根目录)
├── lighthouserc.cjs               ← 门禁：预算 + 断言 + 采集设置
├── package.json                   ← "lhci": "lhci autorun --config=./lighthouserc.cjs"
└── .github/workflows/lighthouse.yml  ← PR 阻断 CI 任务（build → start → lhci → upload）

并添加开发依赖：

pnpm add -D @lhci/cli        # 或 npm i -D / yarn add -D

配置使用 .cjs（CommonJS），以便无需 ESM/TS 转译即可加载。每个预算是带注释的命名常量，解释阈值含义。

npm 脚本：

// package.json
{
  "scripts": {
    "lhci": "lhci autorun --config=./lighthouserc.cjs"
  }
}

lhci autorun 依次执行 collect → assert → upload。推送前可在本地复现 CI 行为：

pnpm build && pnpm lhci
# 桌面形态：
LHCI_FORM_FACTOR=desktop pnpm build && LHCI_FORM_FACTOR=desktop pnpm lhci

GitHub Actions 工作流在涉及应用或工作流文件自身的 PR 上触发，构建生产输出、运行门禁，并始终上传报告（即使失败），使红色检查可调试。工作流中包含：检出代码、Setup pnpm、Setup Node、安装依赖、构建 Web 应用、运行 Lighthouse CI、上传 Lighthouse 报告（if: always()）。

安装此技能：遵循 Anthropic SKILL.md 格式，可跨代理移植。将其放在公开 GitHub 仓库的 skills/frontend-lighthouse/SKILL.md 下，保留 frontmatter 的 name 与高信号 description，安装命令为 npx skills add <org>/<repo> --skill "frontend-lighthouse"。非 SKILL.md 代理可通过 AGENTS.md / CLAUDE.md 指向此处；Kiro 可将其镜像为 steering 文件。

预算严重级别与阈值

审计 / 分类	严重级别	阈值	原因
largest-contentful-paint	error	≤ 2500 ms	Google "good" LCP
cumulative-layout-shift	error	≤ 0.1	Google "good" CLS
total-blocking-time	error	≤ 200 ms	INP 实验室代理
interaction-to-next-paint	warn	≤ 200 ms	并非所有构建都有此审计，不应因缺失审计而硬失败
categories:performance	error	≥ 0.9	顶级（绿色）区间
categories:seo	error	≥ 0.95	SEO 保持满分成本低
categories:accessibility	error	≥ 0.95	无障碍回归必须阻断
categories:best-practices	error	≥ 0.9	绿色区间

对必须成立的契约使用 error，对环境依赖或理想化的审计使用 warn。初始从严，仅在记录原因后放宽——不断调高以让 CI 通过的预算不再保护任何东西。

框架适配

除 startServerCommand 与 startServerReadyPattern 外，配置与框架无关：

框架	startServerCommand	startServerReadyPattern
Next.js	`pnpm start --port 3100`（在 next build 后）	"Ready in"
Remix	`pnpm start`（服务构建后的应用）	服务器监听日志行
Astro	`node ./dist/server/entry.mjs`（SSR）或 `npx serve dist`（静态）	适配器的就绪行 / serve 的 URL 行
SvelteKit	`node build`（node 适配器）	"Listening on"
Vite SPA	`npx vite preview --port 3100`	"Local:"

对于纯静态输出，可跳过服务器，将 collect.staticDistDir 指向构建目录而非 startServerCommand，由 Lighthouse 内部提供服务。

调试失败或不稳定的运行

不稳定的 LCP/TBT → 提高 numberOfRuns（5），确认使用 median-run，并确保运行器上没有其他任务争抢 CPU。
interaction-to-next-paint 报错 → 它应是 warn 而非 error；某些 Lighthouse 版本缺少该审计。
"server not ready" 超时 → 修正 startServerReadyPattern 以匹配框架实际的就绪日志，并提高 startServerReadyTimeout。
真实回归 → 打开上传的报告 artifact，阅读失败审计的 "Opportunities"/"Diagnostics"，修复原因（过大图片、阻塞渲染的 JS、未指定尺寸媒体导致的布局偏移），而不是直接调高预算。
桌面与移动端差异 → 运行两种形态；移动端是更严格的门禁，应作为默认。

适用场景

为 Web 应用添加 Lighthouse CI 性能门禁。
为 LCP、CLS、TBT（INP 的实验室代理）设置 Core Web Vitals 预算。
配置性能、SEO、无障碍、最佳实践的分类分数下限。
调试不稳定的 Lighthouse 运行，或使报告作为 CI artifacts 可见。

限制

Lighthouse CI 是实验室信号，不能替代真实用户指标（field monitoring）。
预算必须根据实际应用路由、托管平台与设备/网络假设进行调优。
通过 Lighthouse 门禁并不能证明业务关键流程、视觉正确性或后端可用性。