前端无障碍的持续集成方案：从代码提交到生产环境的完整检查链

一、引子：无障碍检查不应该是上线前的手动抽查

大多数团队的无障碍实践是这样的：QA 在上线前一天手动跑一遍键盘操作和屏幕阅读器测试，发现问题后紧急修几个，剩下的记录为"已知问题"然后带着歉意上线。这种模式的问题是：下个 Sprint 没人会回头看"已知问题"列表。

无障碍需要和单元测试、类型检查一样，成为 CI 流水线的一部分——每次提交自动检查，不通过则阻断合并。

美院有一门课叫"通用设计"，核心思想是：为残障人群做的设计，会惠及所有人。坡道最初是为轮椅设计的，但推婴儿车的人也受益；字幕最初是为听障人士设计的，但在静音环境下看视频的人也依赖它。前端无障碍同理——aria-label不仅帮助屏幕阅读器用户，也帮助 SEO 爬虫理解按钮用途；键盘导航不仅帮助运动障碍用户，也帮助喜欢用 Tab 键高效操作的开发者。把无障碍检查放进 CI，不是在做"额外的好事"，而是在做"基础的正确"。

二、四层检查金字塔

三、CI 集成方案

/** * 无障碍 CI 检查流水线配置 */ // .github/workflows/a11y-check.yml const a11yPipeline = { name: '无障碍检查', on: ['pull_request'], jobs: { // 第一层：Lint lint: { steps: [ 'npm run lint:jsx-a11y', // eslint-plugin-jsx-a11y ], }, // 第二层：组件级自动扫描 'component-scan': { steps: [ // 使用 jest-axe 在组件测试中集成 'npm test -- --testPathPattern=a11y', ], }, // 第三层：页面级 E2E 扫描 'e2e-scan': { steps: [ 'npx playwright test a11y.spec.ts', ], }, // 结果汇总 'report': { needs: ['lint', 'component-scan', 'e2e-scan'], steps: [ // 汇总所有检查结果，任一严重违规则 CI 失败 'node scripts/a11y-report.js', ], }, }, }; // 组件级测试示例（jest-axe） import { render } from '@testing-library/react'; import { axe, toHaveNoViolations } from 'jest-axe'; expect.extend(toHaveNoViolations); it('Button 组件无障碍检查', async () => { const { container } = render(<Button>提交</Button>); const results = await axe(container); expect(results).toHaveNoViolations(); }); // E2E 扫描示例（Playwright + axe） import { test, expect } from '@playwright/test'; import AxeBuilder from '@axe-core/playwright'; test('首页无障碍检查', async ({ page }) => { await page.goto('/'); const results = await new AxeBuilder({ page }) .withTags(['wcag2a', 'wcag2aa']) .analyze(); expect(results.violations).toEqual([]); });

jest-axe的toHaveNoViolations()断言会在 axe-core 发现任何 WCAG 违规时让测试失败。withTags(['wcag2a', 'wcag2aa'])限定扫描范围为 WCAG 2.0 的 A 和 AA 级别——这是法律合规的最低要求（美国 ADA、欧盟 EN 301 549）。建议在 CI 中将严重违规（critical/serious）设为阻断条件，中等违规（moderate）设为警告但不阻断——这样团队可以逐步还债，而不是被一夜之间的几百个违规淹没。

四、边界分析

自动化扫描的覆盖率上限：axe-core 只能检测约 30% 的 WCAG 标准。焦点管理质量、屏幕阅读器朗读准确度、键盘操作的流畅性无法自动化。第四层 E2E 测试虽然成本最高，但覆盖了最多的场景。

假阳性的处理：CI 中的无障碍检查会产生假阳性——实际可访问但被标记为违规。需要建立豁免机制（通过注释标记已审查的假阳性），避免"狼来了"效应导致团队忽略所有无障碍报警。

增量检查 vs 全量检查：大型项目中全量无障碍扫描可能耗时 10 分钟+。建议在 PR 中只扫描变更文件（增量），main 分支合并后再做全量扫描。

设计阶段的无障碍。无障碍问题最好的修复时机是设计阶段，而非代码阶段。设计师在选择#CCCCCC的浅灰文字配白色背景时，对比度只有 1.6:1——远低于 WCAG AA 标准的 4.5:1。如果在 Figma 插件层就做对比度检查，开发者拿到的设计稿已经是合规的。推荐使用 Stark 或 Polypane 的对比度检查插件，在设计评审阶段就拦截 60% 以上的无障碍问题。色彩对比度的快速参考：正常文字需要 4.5:1 以上，大文字（18px+ 或 14px+加粗）需要 3:1 以上，非文字元素（图标、边框）需要 3:1 以上。

结论

1. 无障碍检查四层金字塔：Lint → 组件扫描 → 页面扫描 → E2E 测试
2. eslint-plugin-jsx-a11y 拦截 15% 问题，成本最低应该最先集成
3. jest-axe 在组件测试中集成，覆盖率 30%
4. Playwright + axe-core E2E 扫描覆盖 70%，但执行成本最高
5. CI 中任一层的严重违规必须阻断合并
6. 假阳性需要豁免机制，避免团队疲劳
7. 增量扫描解决大项目的性能问题，全量扫描保留在 main 分支

无障碍 CI 的终极目标不是"拦截所有违规"，而是"让无障碍成为开发习惯"。当 lint 规则在提交时就提示"<img>缺少alt属性"，开发者下次写<img>时会自然地加上alt——这就是习惯的养成。美院教设计时有条规矩：交作业前先过一遍检查清单（字体、间距、对齐、色彩），久而久之就不需要检查清单了。CI 中的无障碍检查就是前端的"检查清单"——它在那里不是为了永远抓 Bug，而是为了让 Bug 不再产生。当一个团队的无障碍 CI 连续 30 天零违规时，就可以考虑将 lint 规则从"警告"升级为"错误"——这意味着团队的无障碍意识已经内化到了编码习惯中。