Lighthouse CI 默认不阻断构建，需显式配置断言和阈值；本地安装@lhci/cli并锁定版本、正确设置lighthouserc.js、处理Chrome沙盒、用wait-on等待服务就绪、合理配置puppeteerScript及上传目标，才能稳定集成。
Lighthouse CI 能直接嵌入 CI 流程，但默认不自动失败构建——必须显式配置断言（assertions）和阈值，否则即使性能暴跌也不会阻断发布。
安装与基础配置：避免全局安装导致的版本漂移
本地安装 @lhci/cli 比全局安装更可控，尤其在 CI 环境中：
- 用
npm install --save-dev @lhci/cli@0.14.x锁定小版本，防止 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，否则历史数据链就断了。
