novalon-website/docs/lighthouse-ci-guide.md

Lighthouse CI使用指南

概述

Lighthouse CI是一个用于自动化性能测试的工具，它可以在CI/CD流程中运行Lighthouse审计，跟踪性能指标变化，并设置性能预算。

安装

npm install --save-dev @lhci/cli

配置

配置文件

项目根目录下的lighthouserc.json文件包含所有配置：

{
  "ci": {
    "collect": {
      "numberOfRuns": 3,
      "startServerCommand": "npm run start",
      "startServerReadyPattern": "Local:",
      "url": [
        "http://localhost:3000/",
        "http://localhost:3000/about",
        "http://localhost:3000/services"
      ],
      "settings": {
        "preset": "desktop",
        "onlyCategories": [
          "performance",
          "accessibility",
          "best-practices",
          "seo"
        ]
      }
    },
    "assert": {
      "assertions": {
        "categories:performance": ["error", {"minScore": 0.9}],
        "categories:accessibility": ["error", {"minScore": 0.9}],
        "categories:best-practices": ["error", {"minScore": 0.9}],
        "categories:seo": ["error", {"minScore": 0.9}]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

配置说明

collect配置

• numberOfRuns: 每个URL运行的次数（默认3次）
• startServerCommand: 启动服务器的命令
• startServerReadyPattern: 服务器就绪的匹配模式
• url: 要测试的URL列表
• settings: Lighthouse设置
  • preset: 测试预设（desktop/mobile）
  • onlyCategories: 只测试指定类别

assert配置

• assertions: 性能断言
  • categories:performance: 性能分数最低0.9
  • categories:accessibility: 可访问性分数最低0.9
  • categories:best-practices: 最佳实践分数最低0.9
  • categories:seo: SEO分数最低0.9

upload配置

• target: 上传目标
  • temporary-public-storage: 临时公共存储
  • lhci: Lighthouse CI服务器
  • filesystem: 本地文件系统

使用方法

本地运行

运行完整测试

npm run lighthouse

这将执行以下步骤：

1. 启动开发服务器
2. 收集性能数据
3. 运行断言检查
4. 上传结果

分步运行

# 1. 收集性能数据
npm run lighthouse:collect

# 2. 运行断言检查
npm run lighthouse:assert

# 3. 上传结果
npm run lighthouse:upload

指定设备类型

# 桌面端测试
npm run lighthouse:desktop

# 移动端测试
npm run lighthouse:mobile

CI/CD集成

GitHub Actions

创建.github/workflows/lighthouse.yml：

name: Lighthouse CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build application
        run: npm run build
      
      - name: Run Lighthouse CI
        run: npm run lighthouse
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
      
      - name: Upload Lighthouse results
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: lighthouse-results
          path: lighthouse-reports

GitLab CI

创建.gitlab-ci.yml：

lighthouse:
  stage: test
  image: node:18
  script:
    - npm ci
    - npm run build
    - npm run lighthouse
  artifacts:
    paths:
      - lighthouse-reports/
    expire_in: 1 week
  only:
    - main
    - merge_requests

性能指标

Core Web Vitals

Lighthouse CI重点监控以下Core Web Vitals指标：

指标	名称	目标值	说明
LCP	Largest Contentful Paint	< 2.5s	最大内容绘制时间
FID	First Input Delay	< 100ms	首次输入延迟
CLS	Cumulative Layout Shift	< 0.1	累积布局偏移

其他重要指标

指标	名称	目标值	说明
FCP	First Contentful Paint	< 1.8s	首次内容绘制时间
SI	Speed Index	< 3.4s	速度指数
TBT	Total Blocking Time	< 200ms	总阻塞时间

性能预算

在lighthouserc.json中设置性能预算：

{
  "ci": {
    "assert": {
      "assertions": {
        "first-contentful-paint": ["error", {"maxNumericValue": 2000}],
        "largest-contentful-paint": ["error", {"maxNumericValue": 3000}],
        "cumulative-layout-shift": ["error", {"maxNumericValue": 0.1}],
        "total-blocking-time": ["error", {"maxNumericValue": 300}],
        "speed-index": ["error", {"maxNumericValue": 3000}]
      }
    }
  }
}

性能优化建议

1. 减少LCP时间

问题：LCP > 2.5s

解决方案：

// 优化图片加载
<img 
  src="/hero.jpg" 
  alt="Hero image"
  loading="eager"
  fetchpriority="high"
/>

// 使用Next.js Image组件
<Image
  src="/hero.jpg"
  alt="Hero image"
  priority
  width={1920}
  height={1080}
/>

2. 减少CLS

问题：CLS > 0.1

解决方案：

// 为图片预留空间
<img 
  src="/image.jpg" 
  alt="Description"
  width={800}
  height={600}
  style={{ aspectRatio: '800/600' }}
/>

// 避免内容跳动
<div style={{ minHeight: '200px' }}>
  {loading ? <Skeleton /> : <Content />}
</div>

3. 减少TBT

问题：TBT > 200ms

解决方案：

// 代码分割
const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <Loading />,
});

// 延迟加载非关键脚本
useEffect(() => {
  import('heavy-library').then(module => {
    // 使用库
  });
}, []);

4. 优化FCP

问题：FCP > 1.8s

解决方案：

// 内联关键CSS
<style dangerouslySetInnerHTML={{__html: criticalCSS}} />

// 预加载关键资源
<link rel="preload" href="/font.woff2" as="font" type="font/woff2" crossOrigin="anonymous" />

// 减少阻塞资源
<script src="/script.js" defer></script>

查看报告

本地报告

运行测试后，报告保存在lighthouse-reports/目录：

# 打开最新报告
open lighthouse-reports/lhci-*.html

在线报告

如果使用临时公共存储，测试后会输出报告URL：

✅  Report: https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/xxxxx.html

Lighthouse CI服务器

配置Lighthouse CI服务器后，可以查看历史趋势：

{
  "ci": {
    "upload": {
      "target": "lhci",
      "serverBaseUrl": "https://your-lhci-server.com",
      "token": "your-upload-token"
    }
  }
}

性能监控仪表板

创建自定义仪表板

// scripts/performance-dashboard.ts

import fs from 'fs';
import path from 'path';

interface LighthouseResult {
  url: string;
  performance: number;
  accessibility: number;
  'best-practices': number;
  seo: number;
  lcp: number;
  fcp: number;
  cls: number;
  tbt: number;
}

function generateDashboard(results: LighthouseResult[]) {
  const avgPerformance = results.reduce((sum, r) => sum + r.performance, 0) / results.length;
  const avgAccessibility = results.reduce((sum, r) => sum + r.accessibility, 0) / results.length;
  
  console.log(`
## 性能监控仪表板

### 平均分数
- 性能: ${(avgPerformance * 100).toFixed(0)}/100
- 可访问性: ${(avgAccessibility * 100).toFixed(0)}/100

### 各页面性能
${results.map(r => `
#### ${r.url}
- 性能: ${(r.performance * 100).toFixed(0)}
- LCP: ${r.lcp}ms
- FCP: ${r.fcp}ms
- CLS: ${r.cls}
`).join('\n')}
  `);
}

// 读取结果并生成仪表板
const resultsPath = path.join(process.cwd(), 'lighthouse-reports', 'manifest.json');
const results = JSON.parse(fs.readFileSync(resultsPath, 'utf-8'));
generateDashboard(results);

故障排查

问题1：服务器启动失败

症状：Error: Server did not start in time

解决方案：

{
  "ci": {
    "collect": {
      "startServerReadyPattern": "Local:",
      "startServerReadyTimeout": 60000
    }
  }
}

问题2：性能分数不达标

症状：Assertion failed: categories:performance

解决方案：

1. 查看详细报告找出问题
2. 根据优化建议进行改进
3. 调整性能预算（临时）

{
  "assertions": {
    "categories:performance": ["warn", {"minScore": 0.8}]
  }
}

问题3：测试超时

症状：Navigation timeout of 30000 ms exceeded

解决方案：

{
  "ci": {
    "collect": {
      "settings": {
        "maxWaitForLoad": 45000
      }
    }
  }
}

最佳实践

✅ 推荐做法

1. 设置合理的性能预算

   • 基于当前性能设置目标
   • 逐步提高标准

2. 定期运行测试

   • 在CI/CD中自动运行
   • 每次部署前检查

3. 监控性能趋势

   • 使用Lighthouse CI服务器
   • 跟踪性能变化

4. 优化关键页面

   • 首页
   • 高流量页面
   • 转化页面

❌ 避免的做法

1. 不要设置过高的目标

   // ❌ 不现实
   "categories:performance": ["error", {"minScore": 1.0}]
   
   // ✅ 合理
   "categories:performance": ["error", {"minScore": 0.9}]
   

2. 不要忽略移动端性能

   # 同时测试桌面和移动端
   npm run lighthouse:desktop
   npm run lighthouse:mobile
   

3. 不要跳过性能测试

   • 性能问题会影响用户体验
   • 早期发现问题更容易修复

参考资源

• Lighthouse CI官方文档
• Web Vitals
• 性能优化指南
• Lighthouse评分指南

总结

Lighthouse CI已完全集成到项目中，提供了：

✅ 自动化性能测试 ✅ 性能预算监控 ✅ CI/CD集成 ✅ 详细的性能报告 ✅ 历史趋势跟踪

通过合理使用Lighthouse CI，可以：

• 保持良好的性能水平
• 及时发现性能退化
• 持续优化用户体验
• 建立性能文化