docs: 整理文档结构并创建索引（任务 2.3/20）
This commit is contained in:
张翔
@@ -0,0 +1,513 @@
|
||||
# Lighthouse CI使用指南
|
||||
|
||||
## 概述
|
||||
|
||||
Lighthouse CI是一个用于自动化性能测试的工具，它可以在CI/CD流程中运行Lighthouse审计，跟踪性能指标变化，并设置性能预算。
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
npm install --save-dev @lhci/cli
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
### 配置文件
|
||||
|
||||
项目根目录下的`lighthouserc.json`文件包含所有配置：
|
||||
|
||||
```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**: 本地文件系统
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 本地运行
|
||||
|
||||
#### 运行完整测试
|
||||
|
||||
```bash
|
||||
npm run lighthouse
|
||||
```
|
||||
|
||||
这将执行以下步骤：
|
||||
1. 启动开发服务器
|
||||
2. 收集性能数据
|
||||
3. 运行断言检查
|
||||
4. 上传结果
|
||||
|
||||
#### 分步运行
|
||||
|
||||
```bash
|
||||
# 1. 收集性能数据
|
||||
npm run lighthouse:collect
|
||||
|
||||
# 2. 运行断言检查
|
||||
npm run lighthouse:assert
|
||||
|
||||
# 3. 上传结果
|
||||
npm run lighthouse:upload
|
||||
```
|
||||
|
||||
#### 指定设备类型
|
||||
|
||||
```bash
|
||||
# 桌面端测试
|
||||
npm run lighthouse:desktop
|
||||
|
||||
# 移动端测试
|
||||
npm run lighthouse:mobile
|
||||
```
|
||||
|
||||
### CI/CD集成
|
||||
|
||||
#### GitHub Actions
|
||||
|
||||
创建`.github/workflows/lighthouse.yml`：
|
||||
|
||||
```yaml
|
||||
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`：
|
||||
|
||||
```yaml
|
||||
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`中设置性能预算：
|
||||
|
||||
```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
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// 优化图片加载
|
||||
<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
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// 为图片预留空间
|
||||
<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
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// 代码分割
|
||||
const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
|
||||
loading: () => <Loading />,
|
||||
});
|
||||
|
||||
// 延迟加载非关键脚本
|
||||
useEffect(() => {
|
||||
import('heavy-library').then(module => {
|
||||
// 使用库
|
||||
});
|
||||
}, []);
|
||||
```
|
||||
|
||||
### 4. 优化FCP
|
||||
|
||||
**问题**：FCP > 1.8s
|
||||
|
||||
**解决方案**：
|
||||
```typescript
|
||||
// 内联关键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/`目录：
|
||||
|
||||
```bash
|
||||
# 打开最新报告
|
||||
open lighthouse-reports/lhci-*.html
|
||||
```
|
||||
|
||||
### 在线报告
|
||||
|
||||
如果使用临时公共存储，测试后会输出报告URL：
|
||||
|
||||
```
|
||||
✅ Report: https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/xxxxx.html
|
||||
```
|
||||
|
||||
### Lighthouse CI服务器
|
||||
|
||||
配置Lighthouse CI服务器后，可以查看历史趋势：
|
||||
|
||||
```json
|
||||
{
|
||||
"ci": {
|
||||
"upload": {
|
||||
"target": "lhci",
|
||||
"serverBaseUrl": "https://your-lhci-server.com",
|
||||
"token": "your-upload-token"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 性能监控仪表板
|
||||
|
||||
### 创建自定义仪表板
|
||||
|
||||
```typescript
|
||||
// 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`
|
||||
|
||||
**解决方案**：
|
||||
```json
|
||||
{
|
||||
"ci": {
|
||||
"collect": {
|
||||
"startServerReadyPattern": "Local:",
|
||||
"startServerReadyTimeout": 60000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 问题2：性能分数不达标
|
||||
|
||||
**症状**：`Assertion failed: categories:performance`
|
||||
|
||||
**解决方案**：
|
||||
1. 查看详细报告找出问题
|
||||
2. 根据优化建议进行改进
|
||||
3. 调整性能预算（临时）
|
||||
|
||||
```json
|
||||
{
|
||||
"assertions": {
|
||||
"categories:performance": ["warn", {"minScore": 0.8}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 问题3：测试超时
|
||||
|
||||
**症状**：`Navigation timeout of 30000 ms exceeded`
|
||||
|
||||
**解决方案**：
|
||||
```json
|
||||
{
|
||||
"ci": {
|
||||
"collect": {
|
||||
"settings": {
|
||||
"maxWaitForLoad": 45000
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### ✅ 推荐做法
|
||||
|
||||
1. **设置合理的性能预算**
|
||||
- 基于当前性能设置目标
|
||||
- 逐步提高标准
|
||||
|
||||
2. **定期运行测试**
|
||||
- 在CI/CD中自动运行
|
||||
- 每次部署前检查
|
||||
|
||||
3. **监控性能趋势**
|
||||
- 使用Lighthouse CI服务器
|
||||
- 跟踪性能变化
|
||||
|
||||
4. **优化关键页面**
|
||||
- 首页
|
||||
- 高流量页面
|
||||
- 转化页面
|
||||
|
||||
### ❌ 避免的做法
|
||||
|
||||
1. **不要设置过高的目标**
|
||||
```json
|
||||
// ❌ 不现实
|
||||
"categories:performance": ["error", {"minScore": 1.0}]
|
||||
|
||||
// ✅ 合理
|
||||
"categories:performance": ["error", {"minScore": 0.9}]
|
||||
```
|
||||
|
||||
2. **不要忽略移动端性能**
|
||||
```bash
|
||||
# 同时测试桌面和移动端
|
||||
npm run lighthouse:desktop
|
||||
npm run lighthouse:mobile
|
||||
```
|
||||
|
||||
3. **不要跳过性能测试**
|
||||
- 性能问题会影响用户体验
|
||||
- 早期发现问题更容易修复
|
||||
|
||||
## 参考资源
|
||||
|
||||
- [Lighthouse CI官方文档](https://github.com/GoogleChrome/lighthouse-ci)
|
||||
- [Web Vitals](https://web.dev/vitals/)
|
||||
- [性能优化指南](https://web.dev/performance/)
|
||||
- [Lighthouse评分指南](https://web.dev/performance-scoring/)
|
||||
|
||||
## 总结
|
||||
|
||||
Lighthouse CI已完全集成到项目中，提供了：
|
||||
|
||||
✅ **自动化性能测试**
|
||||
✅ **性能预算监控**
|
||||
✅ **CI/CD集成**
|
||||
✅ **详细的性能报告**
|
||||
✅ **历史趋势跟踪**
|
||||
|
||||
通过合理使用Lighthouse CI，可以：
|
||||
- 保持良好的性能水平
|
||||
- 及时发现性能退化
|
||||
- 持续优化用户体验
|
||||
- 建立性能文化
|
||||
Reference in New Issue
Block a user