要在 ci/cd 流水线中用 lighthouse ci 实现“性能不达标就阻断上线”，关键是将 performance 分数（≥85）、首屏加载（fcp ≤2000ms）、最大内容绘制（lcp ≤2500ms）、js 浪费字节数（≤100kb）和总资源体积（≤300kb）设为硬性断言，任一不满足即中断流水线。
要在 CI/CD 流水线中用 Lighthouse CI 实现“性能不达标就阻断上线”，关键不是单纯跑分，而是把评分和指标变成可执行的门禁规则——它得在构建后自动检查、比对阈值、不达标就让流水线失败。
明确要拦截哪些性能问题
不是所有 Lighthouse 指标都适合做阻断依据。优先选影响用户感知强、可量化、易回归的项：
- Performance 分数低于阈值（如
- 首次内容绘制（FCP）超时（如 > 2000ms）——首屏加载延迟
- 最大内容绘制（LCP）超时（如 > 2500ms）——主内容渲染完成时间
- JavaScript 总体积超标（如 > 300KB gzipped）——典型性能预算项
- 未使用代码比例过高（如 > 30%）——打包冗余预警
配置 lighthouserc.js 设置质量门禁
在项目根目录的 lighthouserc.js 中，通过 assert 字段定义硬性规则。CI 运行时只要任一断言失败，lhci autorun 就会退出非零状态，触发流水线中断：
module.exports = {
ci: {
collect: {
staticDistDir: './dist',
// 不写 url 字段，启用内置服务自动托管 dist
numberOfRuns: 3, // 多次运行降噪
waitFor: 'document.querySelector("#app")?.offsetHeight > 0', // 确保 Vue/React 渲染完成
throttling: 'provided', // 关闭网络限速，避免 CI 环境失真
chromeFlags: ['--no-sandbox', '--disable-setuid-sandbox', '--headless=new']
},
upload: { target: 'temporary-public-storage' },
assert: {
assertions: {
'categories:performance': ['error', { minScore: 0.85 }], // Performance ≥ 85 分
'metrics:first-contentful-paint': ['error', { maxNumericValue: 2000 }],
'metrics:largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
'resource-summary:script': ['error', { maxWastedBytes: 100000 }], // JS 浪费字节数 ≤ 100KB
'total-byte-weight': ['error', { maxNumericValue: 307200 }] // 总资源 ≤ 300KB
}
}
}
};
集成到 GitHub Actions（或其他 CI 平台）
确保构建产物已生成、服务已启动、Lighthouse CI 能稳定采集。以下为精简可靠的 .github/workflows/lighthouse.yml 示例：
name: Lighthouse CI Gate
on: [pull_request]
jobs:
lhci:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '18'
- run: npm ci
- run: npm run build
- run: npm install -g @lhci/cli@0.14.x
- run: lhci autorun
env:
LHCI_TOKEN: ${{ secrets.LHCI_TOKEN }} # 若需上传报告，否则可省略
注意：无需额外起服务——只要配置了 staticDistDir，Lighthouse CI 内置服务会自动监听并提供 http://localhost:PORT；若需测多页或 SPA 路由，才需手动起 serve -s dist 并改用 url 字段。
适配不同 CI 环境的关键细节
本地跑分高、CI 里掉分？大概率是环境差异导致采集失真：
-
关闭模拟限速：CI 默认启用 4G throttling，但构建产物没加缓存头、没压缩，容易超时 → 必设
throttling: "provided" -
等待真实渲染：React/Vue 应用务必用
waitFor等待根节点挂载完成，否则测的是空壳 HTML -
Chrome 启动参数必填：Docker 或无 GUI 环境下，
--no-sandbox --headless=new缺一不可 - 避免全量对比，聚焦增量变化：配合 LHCI Server 可追踪趋势，但门禁只应校验本次提交引入的变化，而非绝对分数
不复杂但容易忽略
