Pa11y 9 强制要求 Node.js 20/22/24，低于此版本（如 18.x）会报 ERR_UNSUPPORTED_ESM_URL_SCHEME 或 Cannot find module 'node:fs'；需升级 Node 或降级至 pa11y@8，并配置 axe 引擎、合理 wait/timeout 值以保障动态页面检测准确性。
Pa11y 9 默认不支持 Node.js 18 及更早版本，直接运行会报 ERR_UNSUPPORTED_ESM_URL_SCHEME 或 Cannot find module 'node:fs' ——这不是配置错，是环境硬性不兼容。
确认 Node.js 版本是否满足 Pa11y 9 要求
Pa11y 9 强制要求 Node.js 20/22/24。低于这个版本（比如你用 nvm 切到 18.20.4）就会启动失败，连 pa11y --version 都执行不了。
- 运行
node -v，输出必须是v20.x、v22.x或v24.x - 若不符合：要么用
nvm install 20升级 Node，要么降级 Pa11y：npm install -g pa11y@8（注意：Pa11y 8 默认只支持 WCAG 2.0，不含 2.1 新规） - 验证安装：
pa11y --version应返回类似9.6.0或8.5.0，而非空或报错
用 pa11y-ci 批量扫描多个 URL（推荐方式）
别手写 for 循环或拼接命令——pa11y-ci 是官方为批量和 CI 场景设计的稳定工具，自带超时重试、并发控制和统一报告格式。
- 准备
urls.txt，每行一个 URL（末尾不要空行）：https://example.com/https://example.com/abouthttps://example.com/contact - 运行：
pa11y-ci --config pa11y-config.json --urls urls.txt - 也可从站点地图拉取：
pa11y-ci --config pa11y-config.json --sitemap https://example.com/sitemap.xml
pa11y-config.json 关键配置项说明
配置文件里几个字段直接影响结果可信度，尤其对 React/Vue 页面：
anything-to-html
下载
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
-
"standard": "WCAG2AA"—— 推荐起始标准，比 A 实用，比 AAA 可行；Pa11y 8 默认是WCAG2A，需显式指定 -
"runner": "axe"—— 必须设！默认htmlcs引擎对动态内容（如v-if、aria-label注入）识别率低；axe支持模拟 click/keydown，覆盖更多 WCAG 2.1 规则 -
"timeout": 30000—— 设 30 秒防卡死，单页加载慢时很关键 -
"wait": 2000—— 等 JS 渲染完成再检测，否则 React 页面可能只扫到骨架 -
"ignore": ["color-contrast"]—— 可临时忽略争议项，但别长期写进配置；真要忽略，用规则 ID 如"WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail"
输出报告与自动化对接要点
批量扫描后，报告格式决定后续能否自动分析。CSV/JSON 是 CI 流程中最实用的：
- 加
--reporter csv > report.csv输出 CSV，适合 Excel 查看或脚本解析 - 加
--reporter json > report.json输出结构化 JSON，便于写 Python/Node 脚本统计失败数、按规则聚合问题 - CI 中建议加
--threshold 0：只要发现任意违规就让构建失败（pa11y-ci默认不失败） - 注意：Pa11y 9 的 JSON 报告字段名和 8 不同，例如
issues→results，对接旧解析脚本前先cat report.json | head -n 20看结构
真正麻烦的不是跑命令，而是等页面 JS 加载完、等 axe 模拟交互、等所有异步资源加载完毕再判断——wait 和 timeout 值没调对，结果就不可信。别省这几秒，先调通单页，再扩到批量。
