axe-cli默认不设非零退出码，需显式添加--exit-on-fail才可阻断CI；v4+支持--warning-exit-code，v3需脚本解析JSON手动退出；推荐分级控制规则并校验源码而非dist产物。
为什么 axe-cli 的 exit code 不能直接当门禁用
本地跑 npx axe-cli ./dist/index.html 报了 3 个 error，但 CI 流水线里构建依然成功——这是因为 axe-cli 默认只输出 JSON 或文本，**不主动设置非零退出码**。它把“是否阻断”完全交给你自己判断，不是工具默认行为。
必须显式加 --exit-on-fail 参数，才能让任意 error 导致 exit code ≠ 0；若只要 warning 就想拦截，还得配合 --warning-exit-code 1（注意：axe-cli v4+ 才支持该参数，v3 不支持）。
- CI 中漏掉
--exit-on-fail，等于把可访问性检查降级为“只看不拦” - 若用旧版 axe-cli v3，
--warning-exit-code无效，得靠后续脚本解析 JSON 输出再手动exit 1 - 多文件扫描时，
./dist/**/*.html在某些 shell 下需用find ./dist -name "*.html"避免 glob 失效
如何定义真正可落地的 a11y 红线规则
“所有 error 必须为 0”太粗放。真实项目里，有些 error 是构建插件注入导致的伪报（比如 <link rel="preload" as="picture"> 被标为 invalid as value），而有些 warning 实际影响巨大（如 <button> 缺 aria-label 且无可见文本）。
推荐在配置中分级控制：
立即学习“前端免费学习笔记（深入）”；
- 强制阻断项（error 级）：
color-contrast、label-title-only、duplicate-id - 警告即失败项（warning 升级为 error）：
landmark-one-main、heading-order，加到 axe-cli 的--rules列表并设--warning-exit-code 1 - 明确豁免项（不参与门禁）：
region（若未用 ARIA region）、document-title（若 SSR 框架动态生成 title）
配置示例（.axe-config.json）：
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
{
"rules": {
"color-contrast": { "enabled": true },
"label-title-only": { "enabled": true },
"landmark-one-main": { "enabled": true, "severity": "warning" }
},
"reporter": "json"
}CI 中怎么避免 false positive 拖垮发布节奏
常见误报来源：构建后插入的 <script>、动态 data- 属性、内联 SVG 的 <title> 标签被当成页面标题——这些不是代码缺陷，而是校验器与构建流程的错位。
解决方式不是关规则，而是隔离校验时机：
- 只在校验
src/或app/下原始 HTML 模板，**不校验构建产物 dist/** —— 因为 dist 里的问题，80% 来自构建插件而非源码 - 用
html-validate替代 axe-cli 做源码层语义校验（它不发 HTTP 请求，不解析 JS 注入内容），axe-cli 仅用于构建后最终产物快照验证 - 对第三方 CDN 资源（如 Google Fonts 的
<link href="//fonts.googleapis.com">）在 axe-cli 中加--url-ignore "https?://fonts\.googleapis\.com"，避免网络抖动导致误判
focus 管理类问题为什么很难被自动化捕获
tabindex="-1" 写没写、element.focus() 调没调、焦点是否落入模态框陷阱——这类逻辑行为，axe-cli 和 html-validate 都**完全看不到**。它们只检查静态属性和结构，不执行 JS。
能做的有限但关键：
- 用
html-validate启用no-autofocus规则，防<input autofocus>破坏键盘导航流 - 在 CI 中加轻量级 Puppeteer 脚本：打开页面 → 按 Tab 键 5 次 → 检查
document.activeElement是否为预期元素 → 失败则exit 1 - 禁止在 CSS 中写
*:focus { outline: none }，用html-validate的no-outline-none规则硬性拦截
真正的焦点逻辑闭环，只能靠组件单元测试覆盖，自动化检查只是守住底线。
