前端A11y自动化检测(axe-core)

可视化演示

展示axe-core无障碍检测规则、DOM树遍历、违规严重度分级及CI流水线集成机制，含粒子场背景和发光动画。

A11y检测基础

大厦的坡道不只是给轮椅用的——推婴儿车的妈妈、拖着行李箱的旅客、送货的搬运师傅，全都受益于此。网页也一样。无障碍（A11y）这个词，英文是 Accessibility，取首字母 A、末字母 y、中间 11 个字母，所以缩写成 A11y。它的核心思想是：不论视力、听力、行动力、认知能力如何，所有人都能平等地获取信息和完成任务。

网页世界的“建筑规范”叫做 WCAG——Web 内容无障碍指南，由 W3C 发布。它像一册厚厚的消防条例，规定了文本对比度、键盘可达性、表单可辨识性等标准。问题是，人工对照这册条例逐页检查，就像物业经理拿着 200 页手册亲自爬遍整栋楼的每一层，费时费力还容易遗漏。

axe-core 就是来解决这个痛点的。它是 Deque Systems 开源的自动化无障碍检测引擎，能在毫秒级扫描完一个页面，输出标准化的 JSON 报告。它被公认为业界事实标准，因为规则覆盖面广、误报率低，还深度支持 CI 集成。自动化检测的价值在于“持续且一致”——人会有情绪波动、会有看漏，机器人却永远按同一把尺子量每一页。

一座楼如果坡道、盲道、标识全部合规，每一位访客都会感受到这份用心。同样地，当你的页面通过 axe-core 全量扫描，其实是在向每一位用户传递一个信号：这个产品，欢迎所有人。

axe-core原理

小斧是怎么工作的？它不是魔法，而是一个结构清晰的三段式巡检流程：睁眼——看到全楼所有角落；对照——把看到的东西和检查清单比对；贴条——给不合格的地方登记造册。

对应到技术上，axe-core 的执行入口是 axe.run()。它接受三个参数：上下文（你要查哪一栋楼）、选项（要跑哪些规则的配置）、回调函数。调用时，axe-core 会把一个 JavaScript 运行脚本注入到页面里，在浏览器环境中遍历 DOM 树，把所有元素作为候选对象交给规则引擎。

规则引擎是它的“大脑”。每一条规则都由两部分组成：一个 CSS 选择器匹配器（决定这个规则关心哪些元素，比如 img 标签）和一个 JavaScript 检查函数（对匹配到的元素做布尔判定）。当一个元素同时满足“被规则关心”且“检查不通过”时，它就被记录为一个 violations 成员。整个扫描是异步的，返回一个 Promise，结果中包含违规、通过、无法自动判断三类信息。

小斧最让物业团队省心的一点，是它连“房间里的密室”也能进——现代前端组件常把样式封装在影子 DOM 里，就像大厦楼内的隐形隔间。axe-core 对此有专门支持，让阴影中的违规也无所遁形。

规则体系解析

小斧手里的检查清单不是随手写的，而是有官方依据的“标准手册”。axe-core 内置 90 多条规则，每一条都标注了对应的 WCAG 等级标签：wcag2a、wcag2aa、wcag2aaa，分别对应 A 级、AA 级、AAA 级；还有一类不计入 WCAG 但很实用的规则，叫 best-practice，比如“页面应包含 landmark 区域”。

用 runOnly 可以筛选规则集——比如只跑 wcag2a 和 wcag2aa，满足大多数公司合规验收的要求。每条规则还有自己的 impact 字段，相当于小斧给问题贴的标签颜色：critical（红色，完全不可用）、serious（橙色，严重影响操作）、moderate（黄色，造成困扰）、minor（蓝色，轻微瑕疵）。

这套“颜色标签”体系让团队沟通变得简单：产品经理不需要读懂代码，只需要知道“这周必须把红色和橙色清完”。

常见检测项

巡检半年后，小斧带回了一份高频问题排行。排在榜首的是三类：颜色对比度不足、图片缺替代文本、按钮没有名字。它们占了全部违规的六成以上，而且修复成本极低。

颜色对比度检测是最有意思的一条。它不只是比较“哪个颜色亮一点”，而是计算两种颜色在真实屏幕上的感知亮度差。WCAG AA 要求普通文本的对比度至少达到 4.5:1，大号文本可以放宽到 3:1。很多设计师选了一个浅灰配白底，肉眼勉强能看，但视力不佳的用户就彻底看不清了。

图片替代文本和按钮名称则是“可访问名称”问题。屏幕阅读器用户看不到图片，全靠 alt 文本描述图片内容；一个只有图标没有文字的按钮，对读屏用户来说就是“无法理解的空白按钮”。axe-core 的 image-alt 和 button-name 规则专门抓这两类问题。

小斧把这三大类问题抓出来之后，真正动手修其实很快：给图片补一句 alt、给按钮加 aria-label、调整调色板里的两三个色值——大厦的“小毛病”大多就是这样十来分钟能解决的事。

集成工作流

小斧再能干，如果只是每个月手工抱着它爬一次楼，那就少了一半价值。聪明的物业团队会把它的巡检排进每天的晨间例行程序。前端领域也完全一样：把 axe-core 嵌进开发链路，让它在代码提交、集成测试、CI 构建的每个关键节点都自动跑一遍。

最轻量的方式是用官方命令行工具。在项目里安装 @axe-core/cli 后，一条命令就能扫描指定 URL 或 HTML 文件：

--exit 表示发现违规就以非零退出码结束进程，这正是 CI 门禁的基础。更推荐的做法是把它集成到测试框架里：Jest 生态常用 jest-axe，配合 expect(page).toHaveNoViolations() 一条断言；Playwright 和 Cypress 也都有对应的 axe 插件，可以在页面跳转、用户交互之后实时扫描动态内容。

流水线的设计遵循“关键路径优先”原则——不是每张子页面都要全量跑，而是把登录、支付、内容阅读等用户旅程的核心路由列为必检项。CI 阶段一旦发现 critical 或 serious 级违规，直接让构建失败，挡住合并请求。

当小斧的巡检被编进每日晨巡，物业团队再也不用担心“上周漏检的盲道这周有没有人修好”——因为每天早上它都会坚定地重新报告一遍。

npx @axe-core/cli http://localhost:3000 --exit

报告与修复

小斧交回的巡检报告，是一份结构严谨的 JSON 文档。读懂它，是修复工作的第一步。报告的顶级字段有三个：violations（违规项）、passes（通过项）、incomplete（无法自动判断项）。很多人只看 violations，但 incomplete 同样重要——它相当于是小斧在报告里写的“这块我判断不了，请人工来确认一下”。

每个 violation 对象里包含若干个 nodes，每个 node 指明了具体的 DOM 目标、影响描述和修复建议。有了这些坐标，开发人员不需要费劲猜测“到底哪张图缺 alt 文本”，直接定位即可。

修复顺序不应该平均用力。推荐的做法是给每个违规计算一个优先级：严重级别越高的权重越大，影响的节点数越多越优先。先把红色和橙色清零，再处理黄色，最后有精力时优化蓝色。修复完成一轮后，把小斧重新拉出来跑一遍，确认问题不再复发——这就是“复检闭环”。

小斧把一栋楼的问题整理成了可执行的工单队列。物业团队只要照着优先级列表逐项销号，复检后把报告贴进团队文档，整个项目的无障碍水位就能稳步上升。

AI 应用场景

Python 演示

# -*- coding: utf-8 -*-"""axe-core 违规报告解读器：提取并按优先级排序无障碍问题。"""import jsonimport sys SEVERITY_WEIGHT = {    "critical": 4,    "serious": 3,    "moderate": 2,    "minor": 1,} DEMO_REPORT = {    "violations": [        {            "id": "color-contrast",            "impact": "serious",            "help": "确保文本与背景对比度至少 4.5:1",            "nodes": [{"target": ".btn-primary"}, {"target": ".nav-link"}],        },        {            "id": "image-alt",            "impact": "critical",            "help": "为信息型图片提供 alt 替代文本",            "nodes": [{"target": "img.hero"}],        },        {            "id": "button-name",            "impact": "serious",            "help": "按钮元素需要可访问名称",            "nodes": [{"target": "button.icon-close"}],        },        {            "id": "region",            "impact": "moderate",            "help": "页面需要 landmark 区域便于读屏导航",            "nodes": [{"target": "html"}],        },    ]}  def load_report(path):    """读取 axe-core 输出的 JSON 报告；未传路径时使用演示数据。"""    if path is None:        return DEMO_REPORT    with open(path, "r", encoding="utf-8") as f:        return json.load(f)  def summarize(report):    """按 impact 权重降序汇总 violations。"""    items = []    for violation in report.get("violations", []):        items.append({            "rule": violation["id"],            "impact": violation.get("impact", "minor"),            "count": len(violation.get("nodes", [])),            "help": violation.get("help", ""),        })    items.sort(key=lambda x: SEVERITY_WEIGHT.get(x["impact"], 0), reverse=True)    return items  def render(items, top_n=5):    """打印修复优先级清单。"""    print("===== axe-core 修复优先级清单 =====")    for idx, item in enumerate(items[:top_n], 1):        print("{0}. [{1}] 影响 {2} 个节点: {3}".format(            idx, item["impact"], item["count"], item["rule"]))        print("   建议: " + item["help"])  def main():    path = sys.argv[1] if len(sys.argv) > 1 else None    report = load_report(path)    items = summarize(report)    render(items)  if __name__ == "__main__":    main()

1. SEVERITY_WEIGHT = {...}为四个 impact 档位分配权重分，critical 最高 4 分，这是排序的依据。
2. def load_report(path):兼容两种数据源：传入文件路径读真实报告，否则使用内置演示报告。
3. report.get("violations", [])安全取值：报告里没有这个键时返回空列表，避免 KeyError。
4. len(violation.get("nodes", []))统计每条规则影响了多少个节点，用于衡量影响范围。
5. items.sort(key=lambda x: SEVERITY_WEIGHT.get(...))按权重降序排列，权重最高的红色问题排最前面。
6. if __name__ == "__main__":保证脚本既能作为模块被导入，也能被命令行直接执行。

常见误区

面试题