Back to Details

lighthouse-scanner

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Lighthouse CI Accessibility Integration

Lighthouse CI 无障碍集成

What Is Lighthouse CI?

什么是Lighthouse CI？

Lighthouse CI is a suite of tools for running Google Lighthouse audits in CI pipelines. The most common GitHub Actions integration uses 
treosh/lighthouse-ci-action
.
Lighthouse provides:
  • Performance, accessibility, best practices, and SEO scoring (0-100)
  • Individual audit results with pass/fail status and detailed findings
  • Score budgets and assertions to fail builds on regressions
  • HTML and JSON report artifacts
  • Score comparison across runs for trend tracking
Accessibility focus: The Lighthouse accessibility category runs a subset of axe-core rules and reports a weighted score from 0-100 along with individual audit violations.
Lighthouse CI 是一套用于在CI流水线中运行Google Lighthouse审计的工具套件，最常见的GitHub Actions集成方案使用
treosh/lighthouse-ci-action
。
Lighthouse提供以下能力：
  • 性能、无障碍、最佳实践和SEO评分（0-100分）
  • 单条审计的通过/失败状态与详细发现结果
  • 分数预算与断言规则，出现回归时可终止构建
  • HTML和JSON格式的报告产物
  • 跨运行的分数对比功能，用于跟踪变化趋势
无障碍专项说明： Lighthouse的无障碍分类会运行axe-core规则的子集，输出0-100的加权评分，同时列出所有单条审计违规项。

Detecting Lighthouse CI Presence

检测Lighthouse CI的配置存在

Workflow File Detection

工作流文件检测

Search for workflow files referencing Lighthouse CI:
bash
undefined
搜索引用Lighthouse CI的工作流文件：
bash
undefined

Search for the treosh Lighthouse CI action

搜索treosh出品的Lighthouse CI action

grep -rl "treosh/lighthouse-ci-action" .github/workflows/
grep -rl "treosh/lighthouse-ci-action" .github/workflows/

Search for official Lighthouse CI CLI usage

搜索官方Lighthouse CI CLI的使用记录

grep -rl "lhci autorun|lighthouse-ci" .github/workflows/

**Patterns to match in YAML:**
```yaml
- uses: treosh/lighthouse-ci-action@v12
grep -rl "lhci autorun|lighthouse-ci" .github/workflows/

**YAML中需要匹配的模式：**
```yaml
- uses: treosh/lighthouse-ci-action@v12

Configuration File Detection

配置文件检测

Lighthouse CI uses configuration files in the repository root:
bash
undefined
Lighthouse CI会使用仓库根目录下的配置文件：
bash
undefined

Check for Lighthouse CI config files

检查是否存在Lighthouse CI配置文件

ls lighthouserc.js lighthouserc.json .lighthouserc.js .lighthouserc.json .lighthouserc.yml 2>/dev/null

| Config File | Format |
|------------|--------|
| `lighthouserc.js` | JavaScript module |
| `lighthouserc.json` | JSON |
| `.lighthouserc.js` | JavaScript module (dotfile) |
| `.lighthouserc.json` | JSON (dotfile) |
| `.lighthouserc.yml` | YAML (dotfile) |
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（点文件） |

Configuration Structure

配置结构

Key fields in Lighthouse CI config:
json
{
  "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"
    }
  }
}
SectionPurposeAgent Use
ci.collect.url
URLs to auditScope of CI scanning
ci.collect.numberOfRuns
How many times to run each URLReliability indicator
ci.assert.assertions
Score budgets and thresholdsRegression detection
ci.upload.target
Where to store reportsReport retrieval
Lighthouse CI配置的核心字段：
json
{
  "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
报告存储位置报告拉取

Parsing Lighthouse Accessibility Results

解析Lighthouse无障碍审计结果

Accessibility Score

无障碍评分

Lighthouse computes a weighted accessibility score from 0-100 based on individual audit results.
Score RangeGradeInterpretation
90-100AGood accessibility
70-89B-CSome issues to address
50-69DSignificant issues
0-49FCritical accessibility failures
Lighthouse基于单条审计结果计算0-100的加权无障碍评分：
分数范围等级含义
90-100A无障碍表现良好
70-89B-C存在部分待修复问题
50-69D存在明显问题
0-49F存在严重无障碍故障

Individual Audit Results

单条审计结果

Each Lighthouse accessibility audit corresponds to an axe-core rule:
Audit IDaxe-core RuleWCAG CriterionWeight
image-alt
image-alt
1.1.110
color-contrast
color-contrast
1.4.37
label
label
1.3.17
button-name
button-name
4.1.27
link-name
link-name
2.4.47
html-has-lang
html-has-lang
3.1.17
document-title
document-title
2.4.27
heading-order
heading-order
1.3.13
meta-viewport
meta-viewport
1.4.410
bypass
bypass
2.4.17
tabindex
tabindex
2.4.37
aria-allowed-attr
aria-allowed-attr
4.1.210
aria-hidden-body
aria-hidden-body
4.1.210
aria-required-attr
aria-required-attr
4.1.210
aria-roles
aria-roles
4.1.27
aria-valid-attr-value
aria-valid-attr-value
4.1.27
aria-valid-attr
aria-valid-attr
4.1.210
每条Lighthouse无障碍审计都对应一条axe-core规则：
审计IDaxe-core规则WCAG标准项权重
image-alt
image-alt
1.1.110
color-contrast
color-contrast
1.4.37
label
label
1.3.17
button-name
button-name
4.1.27
link-name
link-name
2.4.47
html-has-lang
html-has-lang
3.1.17
document-title
document-title
2.4.27
heading-order
heading-order
1.3.13
meta-viewport
meta-viewport
1.4.410
bypass
bypass
2.4.17
tabindex
tabindex
2.4.37
aria-allowed-attr
aria-allowed-attr
4.1.210
aria-hidden-body
aria-hidden-body
4.1.210
aria-required-attr
aria-required-attr
4.1.210
aria-roles
aria-roles
4.1.27
aria-valid-attr-value
aria-valid-attr-value
4.1.27
aria-valid-attr
aria-valid-attr
4.1.210

Severity Mapping

严重性映射

Lighthouse uses weights rather than impact levels. Map to the agent severity model based on weight and audit pass/fail:
Lighthouse WeightAudit StatusAgent Severity
10FailCritical
7FailSerious
3FailModerate
1FailMinor
AnyPassN/A (not reported)
Lighthouse使用权重而非影响等级，可根据权重和审计通过/失败状态映射到Agent严重性模型：
Lighthouse权重审计状态Agent严重性
10未通过严重
7未通过较高
3未通过中等
1未通过轻微
任意通过无需上报

Correlation with Local Scans

与本地扫描结果关联

Lighthouse-to-axe-core Mapping

Lighthouse与axe-core的映射关系

Since Lighthouse uses axe-core under the hood, correlation is straightforward:
  1. Match by audit/rule ID: Lighthouse audit IDs correspond directly to axe-core rule IDs
  2. Match by URL: Compare scanned URLs from Lighthouse config with local scan targets
  3. Boost confidence: Findings confirmed by both Lighthouse CI and local axe-core scan receive 
    high
    confidence
由于Lighthouse底层基于axe-core实现，二者的结果关联非常简单：
  1. 按审计/规则ID匹配： Lighthouse审计ID与axe-core规则ID直接对应
  2. 按URL匹配： 将Lighthouse配置中的扫描URL与本地扫描目标做对比
  3. 提升置信度： 同时被Lighthouse CI和本地axe-core扫描确认的问题可标记为
    高
    置信度

Source Comparison

来源对比规则

ScenarioInterpretationAction
Found by Lighthouse AND local scanHigh confidenceReport as high confidence, full severity weight
Found by Lighthouse onlyEnvironment-specificReport as medium confidence, note "CI-only finding"
Found by local scan onlyNot covered by Lighthouse subsetReport as medium confidence, note "local-only finding"
Lighthouse score regressedNew accessibility issues introducedFlag as regression, prioritize in report
场景含义处理方式
同时被Lighthouse和本地扫描发现高置信度问题按高置信度上报，使用完整严重性权重
仅被Lighthouse发现环境专属问题按中置信度上报，标记为「仅CI环境发现」
仅被本地扫描发现不在Lighthouse规则子集覆盖范围按中置信度上报，标记为「仅本地扫描发现」
Lighthouse分数出现回归新引入无障碍问题标记为回归问题，在报告中优先展示

Score Regression Detection

分数回归检测

Track Lighthouse accessibility scores across runs to detect regressions:
跟踪多轮运行的Lighthouse无障碍分数以检测回归：

Comparing Scores

分数对比结构

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

Regression Thresholds

回归阈值

DeltaSeverityAction
Score drops 10+ pointsCriticalImmediate attention, likely multiple new violations
Score drops 5-9 pointsSeriousNew violations introduced, review before merge
Score drops 1-4 pointsModerateMinor regression, track for follow-up
Score unchanged or improvedN/ANo regression detected
分数变化严重性处理方式
分数下降10分及以上严重需要立即处理，大概率存在多个新增违规
分数下降5-9分较高存在新增违规，合并前需要评审
分数下降1-4分中等轻微回归，后续跟进修复
分数无变化或提升无未检测到回归

Structured Output Format

结构化输出格式

When 
lighthouse-bridge
normalizes Lighthouse data, it produces findings in this format:
json
{
  "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"
  }
}
当
lighthouse-bridge
标准化Lighthouse数据时，会输出如下格式的结果：
json
{
  "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 Integration

GitHub Actions集成

treosh/lighthouse-ci-action

treosh/lighthouse-ci-action

The most common Lighthouse CI GitHub Action:
yaml
- name: Run Lighthouse CI
  uses: treosh/lighthouse-ci-action@v12
  with:
    urls: |
      https://example.com
      https://example.com/about
    uploadArtifacts: true
    configPath: ./lighthouserc.json
最常用的Lighthouse CI GitHub Action：
yaml
- 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 Inputs

Action入参

InputRequiredDescription
urls
Yes (or in config)Newline-separated URLs to audit
configPath
NoPath to Lighthouse CI config file
uploadArtifacts
NoUpload HTML reports as workflow artifacts
temporaryPublicStorage
NoUpload to temporary public storage for sharing
runs
NoNumber of runs per URL (default: 1)
budgetPath
NoPath to a Lighthouse budget JSON file
入参是否必填说明
urls
是（或在配置文件中定义）换行分隔的待审计URL列表
configPath
否Lighthouse CI配置文件路径
uploadArtifacts
否将HTML报告作为工作流产物上传
temporaryPublicStorage
否上传到临时公共存储用于分享
runs
否每个URL的运行次数（默认：1）
budgetPath
否Lighthouse预算JSON文件路径

Extracting Results from Artifacts

从产物中提取结果

Lighthouse CI uploads results as workflow artifacts. To retrieve scores:
  1. Download the artifact from the workflow run
  2. Parse the JSON report files
  3. Extract 
    categories.accessibility.score
    for the overall score
  4. Extract individual 
    audits.{audit-id}
    results for violations
Lighthouse CI会将结果作为工作流产物上传，提取分数的步骤如下：
  1. 从工作流运行记录中下载产物
  2. 解析JSON报告文件
  3. 提取
    categories.accessibility.score
    作为整体评分
  4. 提取
    audits.{audit-id}
    下的单条违规结果