一个按钮引发的血案如何用axe-core把网页无障碍测试从加班噩梦变成5分钟日常【免费下载链接】axe-coreAccessibility engine for automated Web UI testing项目地址: https://gitcode.com/gh_mirrors/ax/axe-core周五下午四点距离上线还有三天。产品经理丢过来一张截图某无障碍审计报告满屏红色Violations涉及十几个页面。你打开浏览器扩展一个个点开看发现按钮没有可访问名称图片缺少alt颜色对比度不足……一个下午过去连一半都没看完。如果你也经历过这种无障碍测试 手动挨个页面排查 周末加班的死循环那么这篇 axe-core无障碍测试实战指南就是为你写的。axe-coreAccessibility engine for automated Web UI testing是目前开源界最流行的网页无障碍自动化检测引擎平均能自动发现约57%的WCAG问题关键是——它能直接嵌进你现有的测试体系把事后补课变成日常巡检。初次尝试装上了跑起来了然后看不懂了先别急着写代码。我第一次接触 axe-core 时也以为这是装个库跑一下那么简单。npm install axe-core --save-dev在页面里引入node_modules/axe-core/axe.min.js然后在需要检测的时机调用axe.run().then(results { if (results.violations.length) { throw new Error(Accessibility issues found); } });跑通了。结果对象里也确实有violations、incomplete、passes、inapplicable四类数据。但问题来了我第一次看到incomplete数组里躺着几十条记录时以为全是 bug。其实不是。那是 axe-core 最值得尊重的设计之一它宁可告诉你我拿不准也不硬给你一个结论。拆解底层原理一条规则其实是几个小法官在投票很多人的误区是把 axe-core 当成一个魔法黑盒——一调用就吐一堆结论。真正理解它你只需要理解三层结构。规则Rule负责找谁测每个规则是一个 JSON 文件躺在lib/rules/目录下。它做的事有两件选出要测的元素指定用哪些检查来测。以最经典的button-name规则按钮必须有可读文本为例{ id: button-name, impact: critical, selector: button, matches: no-explicit-name-required-matches, any: [ button-has-visible-text, aria-label, aria-labelledby, non-empty-title, implicit-label, explicit-label, presentational-role ], all: [], none: [] }selector告诉引擎去把所有button揪出来matches是一个过滤函数用来排除一些特殊情况比如某些元素明确不需要名称然后就是关键的any、all、none三个数组。检查Check负责投一票每个检查是一个evaluate函数返回 true/false/undefined配上消息模板和可配置项。规则里那个any数组的意思是7个检查里至少1个通过按钮就合格。any至少一个返回 true → 通过有一个算一个all全部返回 true → 通过缺一个都不行none全部返回 false → 通过碰一个就挂这一套多个小法官投票的机制是 axe-core 能把误报压到接近零的核心。为什么因为现代前端里一个可访问名称的来源实在太多了aria-label、aria-labelledby、label、title、可见文本、甚至 SVG 里的title……任何单一检查都容易误判但让它们互相兜底结论就可靠得多。结果分类比对/错多两档你看到的四类结果其实对应引擎内部四个状态见lib/core/constants.js结果内部状态含义inapplicableNA页面上根本没这类元素跳过passesPASS确定通过incompleteCANTTELL拿不准需要人工复核也叫 needs reviewviolationsFAIL确定违规incomplete是你必须学会看见的一档。以color-contrast为例如果文字背景是渐变色、背景图、或者元素被其他元素遮挡引擎根本无法算出精确的对比度——它不会硬报一个 3.9 就完事而是把元素扔进incomplete附上原因bgImage、bgGradient、bgOverlap……等你人工确认。这份诚实比那些张口就报的工具有价值得多。上手实战用一条自定义规则解决你们独有的坑理解了规则 检查的机制你就拥有了定制能力。团队里常见的场景是你们的组件库有个祖传的样式每个图标按钮都漏了可访问名称偏偏默认规则扫不出来。Axe-core 的目录结构为这种需求留好了位置规则定义在lib/rules/检查逻辑在lib/checks/可复用工具函数在lib/commons/执行引擎在lib/core/。写一条规则其实就三步写检查器在lib/checks/下新增一个xxx-evaluate.js导出一个接收node、virtualNode、options的函数注册检查配套写一个 JSON声明evaluate和messagespass/fail/incomplete 三条消息模板定义规则在lib/rules/下写规则 JSON把selector、matches、any/all/none串起来。项目里还提供了脚手架命令pnpm run rule-gen会帮你生成一套规则骨架文件省去手工拼 JSON 的麻烦。构建时跑pnpm run build开发时用pnpm run develop监听文件变化自动重构建。一个容易忽略的细节如果你的规则涉及 DOM 层级判断查父级、查子级请用virtualNode而不是node。因为在 Shadow DOM 里扁平化树上的父子关系才是真实的。用错 API规则在普通 DOM 上跑得好好的一进 Shadow DOM 就翻车。把规则和检查文件翻译成你们团队的语言Axe-core 支持多语言。locales/目录下已经躺着一堆da.json、ja.json、zh_CN.json……构建时用pnpm run build -- --langzh_CN就能生成中文版构建产物。不过更常见的做法是运行时配置axe.configure({ locale: { rules: { button-name: { help: 按钮必须包含可辨识的文本 } } } });这样你团队里的开发同学看到的中文提示就不再是机器翻译腔了。生产环境实战要点让无障碍测试真正跑进CI接入 CI 才是最值钱的环节。我的经验是三个别别只测首页。无障碍问题集中在表单页、弹窗、深链页面。把 axe-core 挂到每条 PR 的 E2E 流程里新增页面全量扫描。别在 JSDOM 里测对比度。axe-core 对 JSDOM 是有限支持——文档里明确写了color-contrast规则在 JSDOM 下不工作。node 环境测试记得关掉这条规则否则你会收获一批莫名其妙的失败。别忘 iframe。axe-core 能深入任意层级的 iframe 做检测这是它的招牌能力之一但前提是每个 iframe 里都要引入axe.min.js。只在外层页面引入iframe 里的内容就是盲区。还有一个性能窍门如果页面很大、结果很多可以给axe.run传resultTypes比如只保留violations和incomplete的完整节点信息能明显缩短扫描时间。新手最常踩的配置坑避坑清单把incomplete当失败上报。那是待人工复核不是违规。误报会把同事对自动化测试的信任一次性耗尽。扫隐藏内容。默认规则不会测隐藏区域未激活的菜单、关闭的弹窗。要测它们得先把内容激活/渲染可见再跑一次。忽略matches函数。没有它规则会误伤大量本不该测的元素比如presentational-role明确豁免的情况。直接改构建产物。应该改lib/下的源码再pnpm run build而不是手改axe.min.js。跨 iframe 的规则不写after。需要统计全页数量的规则比如 landmark 是否唯一光在单个 frame 里 evaluate 是算不出来的必须用after汇总各 frame 的数据。想深入源码从这些路径开始规则定义lib/rules/如lib/rules/button-name.json检查器逻辑lib/checks/如lib/checks/color/color-contrast.json公共工具函数lib/commons/执行引擎与结果管理lib/core/lib/core/constants.js里定义四类结果规则开发指南doc/rule-development.mdAPI 文档doc/API.md规则清单doc/rule-descriptions.md多语言目录locales/测试test/rule-matches/、test/checks/、test/integration/full/常见问题FAQQ1axe-core 和无障碍浏览器扩展有什么区别浏览器扩展是事后人工点查的工具适合抽查axe-core 是引擎能嵌进单元测试、E2E、CI实现每次构建自动扫。两者是互补关系CI 跑 axe-core 抓确定性问题扩展留给人工做最终确认。Q2npm 安装和从源码构建该怎么选只是接入项目用npm install axe-core --save-dev即可想开发自定义规则、改源码或贡献新规则才需要 clone 仓库地址https://gitcode.com/gh_mirrors/ax/axe-core然后pnpm install、pnpm run build。Q3为什么我的 color-contrast 总是返回 incomplete大概率是背景图、渐变、透明度或元素遮挡导致引擎算不出精确对比度。这是设计行为——axe-core 的原则是不确定就不下结论。可以配合人工复核或用无背景图的测试 fixture 覆盖该规则。Q4axe-core 能测出100%的无障碍问题吗不能。它平均只能自动发现约57%的WCAG问题其余要么需要人工判断要么需要真实用户测试。正确心态是让自动化兜住确定性的那一大半把专家精力留给真正需要判断力的部分。Q5旧浏览器支持到什么程度Chrome 42、Firefox 38、Edge 40、Safari 7 都在支持范围内IE11 已标记废弃。但要注意它只支持原生实现或正确 polyfill 的环境v0 版旧 Shadow DOM 不受支持。回头看那把无障碍测试当成临上线前的折磨本质是把一件应该持续发生的事压缩成了一夜之间的事。axe-core 真正改变的不是多了一个检测工具而是它让无障碍检测从懂无障碍的人才敢碰的专家活变成了每个前端都能在日常构建里顺手做完的普通测试。自动化引擎负责兜住那57%的确定性问题把稀缺的人工判断留给真正需要它的时候——这大概就是为所有人创造平等访问机会最务实的一种落地方式。现在就从你项目里那个一直没人管的按钮开始吧。【免费下载链接】axe-coreAccessibility engine for automated Web UI testing项目地址: https://gitcode.com/gh_mirrors/ax/axe-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考