Lighthouse Accessibility总分不能只看，因其不执行JS、仅扫描静态HTML，结构性硬伤如缺失main、导航未包nav等默认不报，须手动勾选SEO/Best Practices才在Diagnostics中显示；70%扣分项靠改HTML即可解决，如补alt、用button替代div、配label与id、禁跳级标题；color-contrast报错多因CSS变量、暗色模式或Shadow DOM导致，需axe DevTools验证；CI中断言失效常因collect.url异常、assertions未显式声明categories:accessibility、minScore未写为小数（如0.9），或结构规则未单独声明。
为什么Lighthouse Accessibility分数不能只看总分
Lighthouse的Accessibility审计不执行JS，只扫描静态HTML，所以总分高≠语义结构合规。它可能给出92分，但页面里有多个<main></main>、<header></header>里塞了两个<h1></h1>、<nav></nav>被包在<div class="wrapper">里——这些结构性硬伤，Lighthouse默认不报，除非你主动勾选<code>SEO和Best Practices类别。
真正拉低可访问性体验的，往往是这些“看不见的错”：读屏器靠<main></main>跳转主内容，靠<h1></h1>定位页面起点，靠<nav></nav>识别导航区块。Lighthouse只在Diagnostics面板里把它们列为红色条目，不是“Opportunities”，不点开根本看不到。
- 跑分前务必在Lighthouse面板点
Options→ 勾选Emulate mobile device和Clear storage，否则缓存DOM可能掩盖<main></main>未提升的问题 - 如果用
lhci autorun，默认断言不含结构校验，必须手动加"document-has-main-element": ["error"]这类规则 - React/Vue项目要等
document.querySelector('main')存在后再触发审计，否则SSR hydration失败会导致<main></main>还卡在<div id="root">里 <h3>哪些HTML修改能立刻提升Lighthouse Accessibility得分</h3> <p>70%的Accessibility扣分项，改HTML就能解决，不需要动JS或CSS。核心是让每个节点具备明确语义和可读文本上下文。</p> <ul> <li> <code><img alt="HTML代码可访问性怎么审计？Lighthouse评估与修复" >必须带alt：功能性图写描述，装饰性图统一用alt="" role="presentation"（只写alt=""会被判为缺失） - 别用
<div onclick="submit()">模拟按钮，换成<button type="button">；若必须保留div，得加role="button" tabindex="0" -
<input id="email">必须配<label for="email">，for值与id严格一致（大小写、拼写、空格都算错） - 导航菜单必须包在
<nav>里，主标题用<h1>，禁止跳级（<h1>后直接<h3>） - 避免内联样式写死颜色，比如
style="color:#333;background:#fff"——Lighthouse计算对比度依赖CSS继承链，内联样式可能打断它
Lighthouse报告里color-contrast报错却找不到问题元素
color-contrast项持续红，大概率不是HTML缺属性，而是CSS层面的问题：颜色被var(--text-color)变量控制、被@media (prefers-color-scheme: dark)覆盖、或落在Shadow DOM内部——Lighthouse静态扫描无法提取这些运行时计算值。
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
这时候别在HTML里瞎补aria-label，该换工具验证：
- 用
axe DevTools插件，打开后勾选Include automated checks only，再点Analyze，它会标出具体DOM路径（如#header > h1:nth-child(1)） - 用在线
Contrast Checker手动输入背景色和文字色，确认是否真低于4.5:1 - 检查是否有
!important覆盖了CSS变量，或font-size太小导致对比度阈值提高（18px以上字体要求3:1即可）
CI中Lighthouse Accessibility断言为什么没生效
常见现象：CI流水线跑完Lighthouse，accessibility得分为0，但构建依然通过。这不是配置写错，而是断言链路在三个环节就断了。
-
collect.url返回404或重定向：确保npx serve -s dist -p 3000已启动，且lhci collect访问的是http://localhost:3000而非http://127.0.0.1:3000（某些CI镜像DNS解析不一致） -
assert.assertions没显式声明"categories:accessibility"：只写"categories:performance"不会自动带出可访问性校验，Lighthouse CI不做隐式推导 -
minScore写成整数：{"minScore": 90}无效，必须是小数{"minScore": 0.9}，否则该断言静默忽略
结构类问题更难进CI：比如document-has-main-element这种诊断项，默认不在accessibility分类下，得放进assertions里单独声明，且需确保Lighthouse收集阶段已启用SEO和Best Practices审计。
