如何利用 Lighthouse CI 实现提交准入阶段的性能预警与阈值拦截-js教程-PHP中文网

Lighthouse CI 的 collect 阶段卡住或报错 ERR_CONNECTION_REFUSED，主因是 CI 中未启动待测服务；Lighthouse 不启动服务器，仅访问 http://localhost:8080，需手动启动服务、加 wait-on 等待、配置端口权限及沙箱参数。

如何利用 lighthouse ci 实现提交准入阶段的性能预警与阈值拦截

为什么 `lighthouse-ci` 的 `collect` 阶段常卡住或报错 `ERR_CONNECTION_REFUSED`

本地跑通但 CI 中失败，大概率是没启动待测服务。Lighthouse 本身不启动服务器，只访问已有地址——它默认尝试连 http://localhost:8080，而多数 CI 环境里这个端口根本没服务在监听。

实操建议：

必须在 collect 前显式启动服务，比如用 npx http-server ./dist -p 8080 或 npm run serve -- --port=8080，并加 & 后台运行（注意不同 shell 对后台任务的处理差异）
加等待逻辑，避免服务未就绪就发起检测：用 npx wait-on http://localhost:8080（需提前 npm install -D wait-on）
确认 CI 环境允许端口绑定（如 GitHub Actions 默认允许，GitLab CI 可能需设 services: 或用 Docker）
若用 chromium 无头模式失败，可临时加 --chromeFlags="--no-sandbox --disable-setuid-sandbox"，但生产配置应优先修复权限而非绕过沙箱

如何配置 `lhci collect` 的阈值并在超限时让 CI 失败

阈值拦截不是靠 Lighthouse 报告生成后人工比对，而是由 lhci autorun 或手动调用 lhci upload + assert 实现。关键在 assert 阶段的规则定义。

实操建议：

在 .lighthouserc.json 中写死断言规则，例如：

{
  "ci": {
    "collect": { "url": ["http://localhost:8080"] },
    "assert": {
      "assertions": {
        "categories:performance": ["error", {"minScore": 0.8}],
        "metrics:first-contentful-paint": ["warn", {"maxNumericValue": 2000}],
        "accessibility": ["off"]
      }
    }
  }
}

lhci autorun 会自动执行 collect → upload → assert 流程；若拆开执行，需确保 upload 成功后再跑 lhci assert，否则找不到历史基线
注意 minScore 是小数（0.8 表示 80 分），maxNumericValue 单位是毫秒，且仅对具体指标（如 first-contentful-paint）有效，不能对整个 category 用 numeric 断言
CI 中建议加 --collect.numberOfRuns=1 加速，但正式准入建议保留默认 3 次取中位数，避免单次抖动误判

如何让 `lhci` 在 PR 提交时只测变更页面，而不是全站扫描

Lighthouse CI 默认对配置里的 url 数组全量执行，不感知 Git 差异。所谓“只测变更页面”，需要外部逻辑提取改动文件、映射到路由，再动态构造 URL 列表。

实操建议：

用 git diff 找出被修改的源码路径，再通过约定（如 src/pages/foo.vue → /foo）映射为 URL，拼成数组传给 lhci collect --url

简单脚本示例（Bash）：

URLS=(); for f in $(git diff --name-only origin/main...HEAD | grep -E '\.(vue|tsx?|jsx?)$'); do
  path=$(echo $f | sed -E 's|src/pages/(.*)\.(vue|tsx?)$|/\1|; s|/index$||');
  URLS+=("http://localhost:8080$path");
done;
npx lhci collect --url="${URLS[@]}"

若项目路由非文件直出（如动态路由、SSR），需维护一份「变更文件→影响路由」的映射表，或退回到保守策略：只测核心路径（首页、关键转化页）+ 全量回归开关（如 nightly job）
注意：Lighthouse 不支持单页面内多个 url 共享同一份报告，每个 URL 都是独立审计，所以 URL 数量直接影响 CI 耗时

上传报告后如何快速定位性能退化点，而不是只看红绿灯

lhci upload 会把报告推到 lhci server 或 lhci github-app，但默认只展示汇总分。退化往往藏在具体指标波动里，比如 total-blocking-time 上涨 300ms，但 performance category 分只跌了 2%。

实操建议：

启用 lhci server 并配置 collect.target="public"，这样每次上传都会生成可比对的 HTML 报告链接，附带详细指标 delta 图表
在 CI 日志里直接打印关键指标变化：用 lhci upload --outputDir=./lh-report 生成 JSON，再用 jq 提取对比字段，例如：
```
jq '.runs[0].lhr.categories.performance.score, .runs[0].lhr.audits["total-blocking-time"].numericValue' ./lh-report/latest.json
```
若用 GitHub App，PR 评论里默认只显示 summary，需在 .lighthouserc.json 中开启 "githubAppToken" 并设置 "collect.uploadArtifacts": true，才能让详情链接出现在评论底部
警惕「伪稳定」：某些指标（如 speed-index）在低网速下波动极大，建议在 CI 中固定网络条件（--throttling.cpuSlowdownMultiplier=4）并禁用预加载（--chromeFlags="--disable-features=Translate"）以提升可比性