Pa11y

Pa11y 是一款开源自动化无障碍测试工具。最初由 Nature Publishing Group 开发，现由独立社区维护，过去十年来一直是”在 CI 中运行无障碍测试”的首选方案。

Pa11y 的工作原理

在命令行中，Pa11y 接受一个 URL，对已渲染页面执行无障碍检测，并输出违规列表：

$ pa11y https://example.com
Welcome to Pa11y

> Running Pa11y on 1 URLs:
...

Error: This element does not have an attribute "alt".
   • Element: <img src="..." />
   • Code: HTML_CS.Principle1.Guideline1_1.1_1_1.H37
   • Selector: body > section:nth-child(2) > img

Pa11y 在无头浏览器（底层使用 Puppeteer 或 Playwright）中运行，因此检测的是渲染后的 DOM，而非原始 HTML 源码——对 JavaScript 渲染的内容与真实用户体验一致。

支持的规则引擎

Pa11y 历史上支持两种规则引擎：

• HTML_CodeSniffer（默认引擎；Pa11y 最初的核心）。
• axe-core（通过 pa11y --runner axe 启用）。

两者可同时运行并合并结果，实现”自动可检测问题全覆盖”模式。当前大多数 Pa11y 部署已改为只使用 axe-core 引擎，因为 axe-core 的规则迭代最为活跃。

pa11y-ci——多 URL 批量流程

Pa11y 最重要的使用场景是 pa11y-ci。该包装工具可一次性对多个 URL 运行检测，并以适合 CI 的状态码退出：

$ pa11y-ci --sitemap https://example.com/sitemap.xml

这正是大多数无障碍项目采用的夜间回归流程：将站点 Sitemap 传入 pa11y-ci，通过定时任务调度，一旦出现新违规即中断构建，违规数量上升时发出告警。

配置文件位于 .pa11yci（或 JSON 文件），支持按 URL 排除项、严重程度阈值、视口尺寸、自定义操作（登录、点击流程）等自动化设置。

Pa11y、axe-core 与 Lighthouse 的对比

合理的认知模型如下：

• axe-core 是规则引擎——底层检测库，需通过封装工具使用。
• Lighthouse 是其中一种封装，针对站点整体质量审计优化（性能 + 无障碍 + 最佳实践 + SEO）。
• Pa11y 是另一种封装，针对大规模多 URL 无障碍 CI 门控优化。
• axe-core CLI 是第三种——不含 Pa11y 封装的纯 axe，同样适合 CI。

单页面深度分析用 Lighthouse 更佳；多 URL 全站回归测试以 Pa11y 为实践首选；单 URL 构建阻断 PR 检查，则 axe-core CLI 或 Lighthouse-CI 均可胜任。

局限性

Pa11y 继承了所有自动化工具的固有局限：

• 约 30%–40% 的 WCAG 问题可被自动检测；其余需要人工判断。
• 无法测试键盘导航、焦点顺序或屏幕阅读器行为。
• 在无头浏览器中运行，因此无法捕捉仅在真实用户交互过程中出现的问题（如愤怒点击、表单中途放弃、意外的模态对话框叠加）。

但在自动检测能力的上限内，Pa11y 是主流工具中操作最灵活的——尤其当审计范围是”整个站点、每晚全量扫描”，而非”特定 PR”时。