lighthouse-scanner

Lighthouse CI 无障碍集成

什么是 Lighthouse CI？

Lighthouse CI 是一套用于在 CI 流水线中运行 Google Lighthouse 审计的工具。最常见的 GitHub Actions 集成使用 treosh/lighthouse-ci-action。

Lighthouse 提供：

• 性能、无障碍、最佳实践和 SEO 评分（0-100）
• 单项审计结果，包括通过/失败状态和详细发现
• 评分预算和断言，可在出现回归时使构建失败
• HTML 和 JSON 报告制品
• 跨运行的评分比较，用于跟踪趋势

无障碍重点： Lighthouse 无障碍类别会运行 axe-core 规则的一个子集，并报告 0-100 的加权评分以及各项审计违规情况。

检测是否存在 Lighthouse CI

工作流文件检测

搜索引用 Lighthouse CI 的工作流文件：

# Search for the treosh Lighthouse CI action
grep -rl "treosh/lighthouse-ci-action" .github/workflows/

# Search for official Lighthouse CI CLI usage
grep -rl "lhci autorun\|lighthouse-ci" .github/workflows/

在 YAML 中匹配以下模式：

- uses: treosh/lighthouse-ci-action@v12

配置文件检测

Lighthouse CI 在仓库根目录使用配置文件：

# Check for Lighthouse CI config files
ls lighthouserc.js lighthouserc.json .lighthouserc.js .lighthouserc.json .lighthouserc.yml 2>/dev/null

配置文件	格式
lighthouserc.js	JavaScript 模块
lighthouserc.json	JSON
.lighthouserc.js	JavaScript 模块（点文件）
.lighthouserc.json	JSON（点文件）
.lighthouserc.yml	YAML（点文件）

配置结构

Lighthouse CI 配置中的关键字段：

{
  "ci": {
    "collect": {
      "url": ["https://example.com", "https://example.com/about"],
      "numberOfRuns": 3
    },
    "assert": {
      "assertions": {
        "categories:accessibility": ["error", {"minScore": 0.9}]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

部分	用途	Agent 使用方式
ci.collect.url	要审计的 URL	CI 扫描范围
ci.collect.numberOfRuns	每个 URL 的运行次数	可靠性指标
ci.assert.assertions	评分预算和阈值	回归检测
ci.upload.target	报告存储位置	报告获取

解析 Lighthouse 无障碍结果

无障碍评分

Lighthouse 根据各项审计结果计算 0-100 的加权无障碍评分。

评分范围	等级	说明
90-100	A	无障碍表现良好
70-89	B-C	有一些需要处理的问题
50-69	D	存在重大问题
0-49	F	存在严重的无障碍问题

单项审计结果

每项 Lighthouse 无障碍审计都对应一条 axe-core 规则：

审计 ID	axe-core 规则	WCAG 标准	权重
image-alt	image-alt	1.1.1	10
color-contrast	color-contrast	1.4.3	7
label	label	1.3.1	7
button-name	button-name	4.1.2	7
link-name	link-name	2.4.4	7
html-has-lang	html-has-lang	3.1.1	7
document-title	document-title	2.4.2	7
heading-order	heading-order	1.3.1	3
meta-viewport	meta-viewport	1.4.4	10
bypass	bypass	2.4.1	7
tabindex	tabindex	2.4.3	7
aria-allowed-attr	aria-allowed-attr	4.1.2	10
aria-hidden-body	aria-hidden-body	4.1.2	10
aria-required-attr	aria-required-attr	4.1.2	10
aria-roles	aria-roles	4.1.2	7
aria-valid-attr-value	aria-valid-attr-value	4.1.2	7
aria-valid-attr	aria-valid-attr	4.1.2	10

严重程度映射

Lighthouse 使用权重而非影响级别。根据权重和审计通过/失败状态映射到 Agent 严重程度模型：

Lighthouse 权重	审计状态	Agent 严重程度
10	失败	严重
7	失败	高
3	失败	中
1	失败	低
任意	通过	不适用（不报告）

与本地扫描的关联

Lighthouse 到 axe-core 的映射

由于 Lighthouse 在底层使用 axe-core，两者的关联很直接：

1. 按审计／规则 ID 匹配： Lighthouse 审计 ID 与 axe-core 规则 ID 直接对应
2. 按 URL 匹配： 将 Lighthouse 配置中的扫描 URL 与本地扫描目标进行比较
3. 提高置信度： Lighthouse CI 和本地 axe-core 扫描均确认的发现，置信度为 high

来源比较

场景	解释	操作
Lighthouse 和本地扫描均发现	高置信度	标记为高置信度，采用完整严重性权重
仅 Lighthouse 发现	特定于环境	标记为中置信度，并注明“仅 CI 中发现”
仅本地扫描发现	不在 Lighthouse 子集中	标记为中置信度，并注明“仅本地发现”
Lighthouse 分数下降	引入了新的无障碍问题	标记为回归，并在报告中优先处理

分数回归检测

跨运行追踪 Lighthouse 无障碍分数，以检测回归：

比较分数

{
  "url": "https://example.com",
  "previousScore": 95,
  "currentScore": 87,
  "delta": -8,
  "status": "regressed",
  "newFailures": ["color-contrast", "image-alt"],
  "newPasses": []
}

回归阈值

变化	严重程度	操作
分数下降 10 分或以上	严重	立即处理，可能引入了多个新违规项
分数下降 5–9 分	较严重	引入了新的违规项，合并前进行检查
分数下降 1–4 分	中等	轻微回归，跟进记录
分数不变或提高	不适用	未检测到回归

结构化输出格式

当 lighthouse-bridge 对 Lighthouse 数据进行标准化时，会按以下格式生成发现：

{
  "source": "lighthouse-ci",
  "ruleId": "color-contrast",
  "wcagCriterion": "1.4.3",
  "wcagLevel": "AA",
  "severity": "serious",
  "confidence": "high",
  "url": "https://example.com/login",
  "element": "button.submit-btn",
  "description": "Element has insufficient color contrast ratio",
  "lighthouseWeight": 7,
  "lighthouseScore": {
    "overall": 87,
    "previousOverall": 95,
    "delta": -8,
    "status": "regressed"
  }
}

GitHub Actions 集成

treosh/lighthouse-ci-action

最常用的 Lighthouse CI GitHub Action：

- name: Run Lighthouse CI
  uses: treosh/lighthouse-ci-action@v12
  with:
    urls: |
      https://example.com
      https://example.com/about
    uploadArtifacts: true
    configPath: ./lighthouserc.json

Action 输入

输入项	必需	描述
urls	是（或在配置中指定）	以换行符分隔的待审计 URL
configPath	否	Lighthouse CI 配置文件的路径
uploadArtifacts	否	将 HTML 报告上传为工作流构件
temporaryPublicStorage	否	上传到临时公共存储空间以便分享
runs	否	每个 URL 的运行次数（默认值：1）
budgetPath	否	Lighthouse 预算 JSON 文件的路径

从构件中提取结果

Lighthouse CI 会将结果作为工作流构件上传。要获取分数：

1. 从工作流运行中下载构件
2. 解析 JSON 报告文件
3. 提取 categories.accessibility.score 作为总分
4. 提取各项 audits.{audit-id} 结果以获取违规项