axe-core 可直接在浏览器控制台运行检测可访问性问题，返回 violations、incomplete 和 passes 对象，重点关注 violations 中的 color-contrast、image-alt、heading-order 等 id；需确保页面加载完成、启用 shadowdom 支持，并检查 alt、role、lang 属性是否缺失。

用 axe-core 直接在浏览器控制台跑检测

不需要装插件、不依赖构建流程，打开任意 HTML 页面，按 F12 进入控制台，粘贴执行这行代码就能拿到可访问性问题列表：

await (await fetch('https://cdn.jsdelivr.net/npm/axe-core@4.10.2/axe.min.js')).text().then(eval); axe.run().then(console.log)

它会返回一个包含 violations（严重问题）、incomplete（需人工确认）和 passes 的对象。重点盯 violations 里的 id 字段，比如 color-contrast、image-alt、heading-order —— 这些就是真实影响屏幕阅读器或键盘导航的硬伤。

常见卡点：

• 页面还没加载完就运行 axe.run()，结果为空 → 改成 document.readyState === 'complete' && axe.run()
• 用了 Shadow DOM 或动态渲染内容 → 加 {shadowDom: true} 参数，如 axe.run({shadowDom: true})
• 某些内联 SVG 或 Canvas 内容被误报 → 检查 impact 字段是否为 minor，别一概当 bug 修

检查 alt、role、lang 这三个最常漏写的属性

静态 HTML 里 80% 的可访问性漏洞集中在三处：图片缺 alt、交互元素没 role 或 tabindex、页面没声明语言。它们无法靠 JS 补救，必须写在 HTML 源码里。

快速筛查命令（Linux/macOS 终端）：

grep -n '@@##@@]*src=' index.html | grep -v 'alt="'

grep -n '<button>]*href' index.html | grep -v 'role="\|tabindex="'</button>

grep -n '
<p>注意：</p><div class="aritcle_card flexRow artxards">
											<div class="artcardd flexRow">
												<a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill4293" title="Doc To HTML"><img
														src="https://img.php.cn/upload/skill/000/000/081/178998486916110.jpg" alt="Doc To HTML" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a>
												<div class="aritcle_card_info flexColumn">
													<a rel="nofollow" href="/xiazai/skill4293" title="Doc To HTML" class="overflowclass">Doc To HTML</a>
													<p class="overflowclass">使用 MinerU 文档处理引擎将 Word 文档（.doc、.docx）转换为保留结构和格式的干净 HTML。</p>
												</div>
												<a rel="nofollow" href="/xiazai/skill4293" title="Doc To HTML" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span>
												</a>
											</div>
										</div>

• alt="" 是合法的（装饰图），但 alt 属性本身不能缺失
• <button onclick="..."></button> 必须带 type="button"，否则部分屏幕阅读器会误读为提交按钮
• lang 值要匹配实际内容，比如中英文混排页写 lang="zh-CN" 不够，得用 lang="zh" + span lang="en" 显式标注英文段落

用 Lighthouse 扫描时避开“假阳性”陷阱

lighthouse 命令行或 DevTools 里的 Lighthouse 面板默认启用全部审计项，但对纯静态 HTML 来说，很多“可访问性”失败其实是环境干扰导致的：

• 它会模拟移动设备视口，可能把桌面端正常的字号/间距判为 color-contrast 不足 → 加 --emulated-form-factor=desktop 参数重试
• 如果页面含 iframe 且跨域，Lighthouse 无法审计其内部结构，会把整个 iframe 标为 frame-title 失败 → 检查该 iframe 是否真需要标题，还是可以加 title 属性临时绕过
• 它检测 skip-link 时要求第一个聚焦元素是跳转链接，但静态页若用 main 语义化标签且无 JS，其实已满足 WCAG 2.1 → 判定为“低风险”，不必强加 <a href="https://www.php.cn/link/7481bf1c256a66dac3bf1f5721056ca6"></a>

真正该优先处理的是标为 critical 或 serious 的项，比如 aria-input-field-name（表单控件无名称）、duplicate-id（重复 ID）——这些会导致屏幕阅读器直接崩溃或跳过关键内容。

为什么不用 WAVE 或 AChecker 在线工具

WAVE 和 AChecker 看起来方便，但对静态 HTML 分析有硬伤：

• 它们依赖远程服务器抓取页面，如果你的 HTML 是本地 file:// 协议打开，会因 CORS 被拒，返回空结果
• 不支持批量扫描多个 HTML 文件，每次只能输一个 URL，没法集成进 CI 流程
• 对自定义元素（如 <my-button></my-button>）或 Web Component 的 shadowRoot 内容基本不识别，报错为“无法解析 DOM”

axe-core 和 Lighthouse 都能离线运行、支持本地文件路径（lighthouse file:///path/to/index.html），还能输出 JSON 供脚本解析。真正需要自动化或批量检查时，别被界面友好性骗了。

最后提醒一句：所有工具都只能发现“技术层面”的可访问性缺陷。像“按钮文案是否足够明确”“错误提示是否对认知障碍用户友好”，还得靠人眼+真实用户测试。工具扫出的 violations 是底线，不是终点。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！