ci-integration

用途

该技能提供将自动化无障碍扫描集成到 CI/CD 流水线中的模式、模板与参考数据，覆盖 axe-core CLI、Lighthouse CI、SARIF 输出、基线管理以及多平台配置。使用该技能的智能体包括 ci-accessibility、web-accessibility-wizard、accessibility-lead。

主要能力

axe-core CLI 参考

安装命令：

npm install --save-dev @axe-core/cli

WCAG 2.2 AA 标签集：

npx axe <url> --tags wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa

输出格式：

参数	输出
--reporter json	JSON 结果输出到 stdout
--reporter sarif	用于代码扫描的 SARIF 格式
--reporter html	人类可读的 HTML 报告
--save <file>	将结果保存到文件

退出码：

代码	含义
0	未发现违规
1	发现违规
2	运行扫描出错

基线模式

目的：没有基线时，每一个遗留违规都会导致 CI 失败，使棕地（brownfield）应用无法采用。有了基线，CI 门禁只阻止回归。

基线文件结构（axe-baseline.json）：

{
  "version": "1.0",
  "timestamp": "2026-03-22T00:00:00Z",
  "tool": "@axe-core/cli",
  "tags": "wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa",
  "violations": {
    "color-contrast": { "count": 12, "pages": ["index.html", "about.html"] },
    "image-alt": { "count": 3, "pages": ["gallery.html"] },
    "label": { "count": 5, "pages": ["contact.html", "signup.html"] }
  },
  "total": 20
}

比较逻辑：

current_violations = run_axe_scan()
baseline = load("axe-baseline.json")

new_violations = current_violations - baseline
if new_violations.count > 0:
    FAIL PR — "N new accessibility violations introduced"
else:
    PASS — "No new violations (M existing in baseline)"

GitHub Actions 模板

name: Accessibility Check
on:
  pull_request:
    paths: ['**/*.html', '**/*.jsx', '**/*.tsx', '**/*.vue', '**/*.svelte']

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx axe $(git diff --name-only HEAD~1 --diff-filter=ACMR -- '*.html' | tr '\n' ' ') --tags wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa --reporter json --save results.json
      - name: Check results
        run: |
          violations=$(jq '[.[].violations[]] | length' results.json)
          echo "Found $violations violations"
          if [ "$violations" -gt 0 ]; then exit 1; fi

SARIF 集成

SARIF（Static Analysis Results Interchange Format）可在 GitHub PR diff 中实现内联注释。

上传步骤：

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
    category: accessibility

优势：

违规以 PR diff 中确切行的内联注释形式出现
结果在 Security → Code Scanning 标签页可见
随时间跟踪违规趋势
支持对误报的驳回工作流

门禁策略

策略	阻止条件	最适合
Strict	任何违规（所有严重级别）	新的绿地项目
Standard	仅 Critical + Serious	具有良好无障碍基线的活跃项目
Baseline	仅新增违规（回归）	棕地采用、遗留代码库
Warning	从不阻止，仅评论	意识阶段、渐进式采用

多平台模板

Azure DevOps：

trigger:
  paths:
    include: ['**/*.html', '**/*.jsx', '**/*.tsx']

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: NodeTool@0
    inputs: { versionSpec: '22.x' }
  - script: npm ci && npx axe $(Build.SourcesDirectory)/index.html --tags wcag2a,wcag2aa
    displayName: 'Accessibility Scan'

GitLab CI：

accessibility:
  image: node:22
  script:
    - npm ci
    - npx axe $CI_PROJECT_DIR/index.html --tags wcag2a,wcag2aa
  only:
    changes: ['**/*.html', '**/*.jsx', '**/*.tsx']

严重级别映射

axe-core Impact	CI 优先级	动作
critical	p1-blocker	必须阻止合并
serious	p2-high	应阻止合并
moderate	p3-medium	在 PR 评论中警告
minor	p4-low	仅信息

使用方式

该技能以参考文档形式提供，包含安装命令、CLI 参数、基线文件结构、比较逻辑伪代码以及 GitHub Actions、Azure DevOps、GitLab CI 的配置模板。使用时按需引用对应模板与参数，将无障碍扫描步骤加入现有 CI 流水线，并依据项目阶段选择门禁策略。

适用场景

新绿地项目：采用 Strict 策略，阻止任何违规合并。
具有良好无障碍基线的活跃项目：采用 Standard 策略，仅阻止 Critical 与 Serious 级别违规。
棕地采用与遗留代码库：采用 Baseline 策略，仅阻止新增回归。
意识阶段与渐进式采用：采用 Warning 策略，仅评论不阻止。

限制

资料未提供该技能的具体运行环境要求、依赖版本兼容性范围、性能开销数据、对动态渲染页面的支持程度，以及除 axe-core CLI 与 Lighthouse CI 之外其他工具的集成细节。Lighthouse CI 在资料中仅被提及，未提供具体配置模板或参数说明。