accessibility-linter是专用于前端HTML可访问性静态检查的工具，它不依赖浏览器环境，直接扫描JSX/Vue SFC/HTML模板源码，适合集成到pre-commit钩子或CI/CD流水线，但需注意配置解析器、合理启用规则及使用绝对路径忽略文件。
前端工程中HTML可访问性工具不是装上就能用的，关键在于选对类型、配对阶段、避开静态分析盲区——比如accesskey这类属性，大多数linter根本不会查，而运行时工具又容易漏掉SSR初始HTML里的问题。
如何在CI/CD中集成accessibility-linter做静态检查
它不依赖浏览器环境，直接扫描源码（JSX/Vue SFC/HTML模板），适合塞进pre-commit钩子或CI流水线。但必须注意三点：
- 配置文件需显式声明解析器：React项目要配
parserOptions: { parser: '@babel/eslint-parser' }，否则JSX里的aria-label可能被跳过 - 规则不能全开：像
jsx-a11y/alt-text对SVG内<title></title>的检查，在旧版Icon组件里会误报，建议先禁用再逐条启用 - 忽略文件要写绝对路径：
ignorePatterns: ['src/generated/**']比['generated/**']更可靠，否则构建生成的HTML模板可能逃逸检测
axe-core为何在E2E测试中常漏报role="toolbar"问题
因为axe-core检测的是渲染后的DOM，而role="toolbar"若没配aria-label或aria-labelledby，屏幕阅读器直接跳过该区域——但axe-core只报“缺少可访问名称”，不会指出“这个toolbar已被辅助技术忽略”。真实影响比报错更严重。
- 复现条件：组件首次挂载时
aria-label为空字符串或未设置，后续JS才补上 → axe-core快照抓的是初始状态 - 规避方式：在Playwright测试里加
await page.waitForFunction(() => document.querySelector('[role="toolbar"]').getAttribute('aria-label'))，确认属性已就位再跑axe检查 - 替代方案：用
eslint-plugin-jsx-a11y在代码层卡住，规则jsx-a11y/role-has-required-aria-props能直接揪出role="toolbar"缺命名的问题
为什么Lighthouse的可访问性审计不能代替人工验证
它跑的是单页快照，对动态内容、焦点管理、键盘流顺序这类交互逻辑无能为力。例如一个标签页组件，Lighthouse可能显示“所有role="tab"都有aria-controls”，但实际按→键切换时焦点卡死在第一个tab，它完全不报错。
立即学习“前端免费学习笔记（深入）”；
- 典型漏检场景：
aria-live区域更新后，屏幕阅读器未朗读（因aria-live="polite"被CSSdisplay: none临时遮盖） - 键盘测试必须手动做：Tab进组件→方向键切tab→Enter激活→Esc关闭→Shift+Tab回退，每步都要验证焦点位置和朗读内容
- Lighthouse报告里的“Passed”项，仅表示符合WCAG某条款的字面检查，不代表用户真能顺畅操作
工具链越长，越容易把可访问性当成一道过滤网——但真正卡住体验的，往往是那些工具既不报错、也不覆盖的边界行为：比如aria-current="step"值从"step"错写成"page"，axe和Lighthouse都沉默，只有真实用户在步骤向导里迷失时才会暴露问题。
