如何借助 Lighthouse CI 把性能审计接入持续集成流程

Lighthouse CI 默认不阻断构建，需显式配置断言和阈值；本地安装@lhci/cli并锁定版本、正确设置lighthouserc.js、处理Chrome沙盒、用wait-on等待服务就绪、合理配置puppeteerScript及上传目标，才能稳定集成。

Lighthouse CI 能直接嵌入 CI 流程，但默认不自动失败构建——必须显式配置断言（assertions）和阈值，否则即使性能暴跌也不会阻断发布。

安装与基础配置：避免全局安装导致的版本漂移

本地安装 @lhci/cli 比全局安装更可控，尤其在 CI 环境中：

• 用 npm install --save-dev @lhci/[email protected] 锁定小版本，防止 CI 中因新版本 breaking change 导致 lhci autorun 报错
• lighthouserc.js 必须导出对象，且 ci.collect.url 不能是空数组；若测试本地服务，需确保 npm run build 后 staticDistDir 路径存在且可被 http-server 或类似工具访问
• CI 中 Chrome 可能缺失沙盒支持，需在 puppeteerLaunchOptions 中加 --no-sandbox，否则报 Failed to launch chrome

断言（assertions）配置：不设 minScore 就等于没监控

默认配置下 lhci autorun 只收集、上传、输出报告，完全不校验分数。要让 CI 失败，必须在 assert.assertions 中明确声明：

• 写法必须是 'categories:performance': ['error', {minScore: 0.85}]，漏掉 error 或写成 warn 都不会中断构建
• 指标名区分大小写且带冒号，比如 metrics:first-contentful-paint 是合法键，但 firstContentfulPaint 或 fcp 会静默忽略
• 若同时监控多个指标，每个都要单独配断言：'metrics:lcp'、'metrics:cls'，不能合并

CI 中启动本地服务的坑：端口冲突与就绪等待

很多团队用 http-server -p 3000 ./dist 启服务，但在 GitHub Actions Ubuntu runner 上容易失败：

• 端口 3000 常被其他 job 占用，建议用随机端口 + PORT=0（如 http-server -p 0 ./dist），再用脚本读取实际端口并注入到 lighthouserc.js 或环境变量
• Lighthouse 启动时服务可能还没 ready，直接访问会报 ERR_CONNECTION_REFUSED；不要依赖固定 sleep，改用 wait-on http://localhost:3000（需提前 npm install wait-on --save-dev）
• lhci collect 的 numberOfRuns 设为 3 时，每次运行都重建浏览器实例，若服务不稳定，某次失败会导致整轮采集中断——建议先用 numberOfRuns: 1 调通流程

Puppeteer 脚本介入时机：认证页和 SPA 的关键控制点

当审计页面需要登录或依赖 JS 渲染时，puppeteerScript 不是“辅助工具”，而是必需环节：

• 脚本必须 export default async (browser, context) => { ... }，返回 Promise，且最后不能调用 page.close() ——Lighthouse 需要复用该 page 实例
• 若页面跳转后 URL 改变（如登录重定向），Lighthouse 默认仍测原始 URL；需在脚本末尾加 await page.goto('https://app.example.com/dashboard')，并确保该 URL 在 ci.collect.url 列表中
• SPA 路由切换后内容未加载完就触发审计，会导致 LCP/CLS 失真；务必用 await page.waitForSelector('.main-content') 或 await page.waitForFunction(() => window._lighthouseReady === true) 显式等待

最常被忽略的一点：Lighthouse CI 的 upload.target 设为 temporary-public-storage 时，报告链接 7 天后失效，无法做跨周趋势比对；长期监控必须对接自建服务器或 LHCI Server，否则历史数据链就断了。