Pa11y 9要求Node.js 20/22/24，旧版如Node 18会报ERR_UNSUPPORTED_ESM_URL_SCHEME；需node -v ≥20，否则须升级Node或降级Pa11y至v8；pa11y-ci支持批量扫描，推荐配axe引擎与WCAG2AA标准，并输出CSV/JSON用于自动化分析。
pa11y 命令行批量扫描必须先装对版本
Pa11y 9 要求 Node.js 20/22/24，旧版 Node（比如 18 或更早）会直接报 ERR_UNSUPPORTED_ESM_URL_SCHEME 或 Cannot find module 'node:fs'。这不是配置问题，是运行时环境不兼容。
确认方式很简单：node -v 输出必须 ≥20；如果不符合，要么升级 Node，要么降级 Pa11y：npm install -g pa11y@8（注意：Pa11y 8 默认只支持 WCAG 2.0，不带 2.1 规则）。
安装后验证是否可用：pa11y --version。输出应为 9.x.x 或 8.x.x，而非报错或空响应。
用 pa11y-ci 批量跑多个 URL 最省事
pa11y-ci 是 Pa11y 官方提供的批量扫描命令行工具，专为 CI 和多页检测设计，比手写 for 循环或脚本更稳定——它内置重试、超时控制、并发限制和统一报告格式。
立即学习“前端免费学习笔记（深入）”；
基本用法：
pa11y-ci --config pa11y-config.json --sitemap https://example.com/sitemap.xml
或者直接传 URL 列表文件：
pa11y-ci --config pa11y-config.json --urls urls.txt
urls.txt 每行一个 URL，例如：
https://example.com/ https://example.com/about https://example.com/contact
关键配置项（pa11y-config.json）要明确指定：
-
"standard": "WCAG2AA"—— 推荐起始标准，比 A 更实用，比 AAA 更可行 -
"timeout": 30000—— 页面加载超时设为 30 秒，防卡死 -
"wait": 2000—— 等待 JS 渲染完成再检测，尤其对 React/Vue 页面必要 -
"ignore": ["color-contrast"]—— 可临时忽略争议项（但别长期忽略）
用 --runner axe 而不是默认 HTML_CodeSniffer
Pa11y 默认用 HTML_CodeSniffer 引擎，但它对现代框架（如 React 的动态 aria-label 注入、Vue 的 v-if 切换）识别率偏低，常漏掉焦点管理、语义结构错乱等问题。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
axe-core 引擎更贴近真实辅助技术行为，覆盖 60% 的 WCAG 2.1 A/AA 规则，且支持更细粒度的交互模拟（比如自动触发 click 和 keydown）。
启用方式很简单，在命令中加参数：
pa11y https://example.com --runner axe --standard WCAG2AA
批量场景下，把 --runner axe 写进 pa11y-config.json 的 "runner" 字段即可：
"runner": "axe"
注意：axe 引擎在 Pa11y 9 中开箱即用，无需额外安装；但 Pa11y 8 需手动 npm install pa11y-runner-axe --save-dev 并注册。
输出报告别只看 HTML，优先用 CSV 或 JSON 做聚合分析
默认 pa11y-ci 输出 HTML 报告看着直观，但没法自动比对趋势、统计高频问题、或对接 Jira/Notion。真正用于团队协作的，是机器可读格式。
生成 CSV（方便 Excel 分析）：
pa11y-ci --urls urls.txt --reporter csv > report.csv
生成 JSON（适合脚本解析）：
pa11y-ci --urls urls.txt --reporter json > report.json
常见坑点：
-
--reporter必须紧贴命令末尾，不能放在中间，否则被当成 URL 解析 - CSV 中
type字段值是error/warning/notice，不是 WCAG 条款编号；真要映射条款，得查code字段（如color-contrast对应 WCAG 1.4.3） - JSON 输出里每个 URL 是独立对象，
issues数组里的context字段是出问题的 HTML 片段，别直接当 selector 用——它可能含动态 ID 或随机 class
最易被忽略的一点：Pa11y 不检测 CSS 渲染结果（比如高对比度模式下的文字消失），也不校验 JS 运行时逻辑（比如键盘导航跳过某个按钮）。它只检查“静态快照 + 可触发的 DOM 状态”。所以批量扫完，仍需人工抽检键盘流、屏幕阅读器实测、以及开启 Windows 高对比度模式验证。
