怎么在自动化发布流程中设置HTML可访问性阻断性红线-html教程-PHP中文网

axe-cli默认不设非零退出码，需显式添加--exit-on-fail才可阻断ci；v4+支持--warning-exit-code，v3需脚本解析json手动退出；推荐分级控制规则并校验源码而非dist产物。

怎么在自动化发布流程中设置html可访问性阻断性红线

为什么 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></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）：

Article To Html

文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。

下载

{
  "rules": {
    "color-contrast": { "enabled": true },
    "label-title-only": { "enabled": true },
    "landmark-one-main": { "enabled": true, "severity": "warning" }
  },
  "reporter": "json"
}

CI 中怎么避免 false positive 拖垮发布节奏

常见误报来源：构建后插入的 <script></script>、动态 data- 属性、内联 SVG 的 <title></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 规则硬性拦截