你有没有遇到过这种情况项目里配好了自动化可访问性检查CI 一路绿灯Lighthouse 可访问性评分接近满分但产品上线后依赖屏幕阅读器的用户仍然反馈“这个页面信息根本读不出来”。问题往往不在属性缺失而在于 alt 文本的质量。自动化检查能确认img标签上有一个 alt 属性却无法确认这个属性里写的内容是不是用户真正需要的信息。它可能会看到altIMG_20240713_143027.jpg然后判定“通过”因为属性存在、非空甚至符合某些规则的格式要求。但从用户体验角度看这句话和一个乱码没有区别。这篇文章想讨论一个容易被团队忽视的问题为什么 alt 文本能通过自动化检查不代表它真正合格以及一个可落地的 alt 文本质量保障方案应该怎么做。读完后你会得到三样东西一个能判断 alt 是否合格的决策清单一套能嵌入研发流程的分层检查机制以及推动团队改进可访问性时可以直接使用的评审话术。1. 为什么说“通过检查”和“真正合格”是两回事首先要明确一个分层alt 文本质量存在三个层级。规则层这个标签上有没有 alt 属性。这一层可以完全由机器完成。结构层alt 是否用了正确的策略——装饰图是否为空、功能图是否描述了目的、复杂图是否提供了替代文本。这一层部分可以被规则覆盖但需要语义判断。内容层alt 的文字本身是否准确、简洁、有用、与上下文匹配。这一层几乎无法靠自动化规则判断。当前大多数团队的自动化检查停留在第一层最多覆盖第二层的一小部分。axe-core、Lighthouse 这类工具的设计目标是帮你找出“明显违反可访问性原则”的问题而不是帮你判断“这句话写得好不好”。它们是底线检查器不是质量裁判。用写作来类比语法检查工具能发现句子缺主语但它无法告诉你段落是否逻辑清晰、是否有信息增量。alt 文本的自动化检查一样能发现 alt 缺失、空的 img 没有正确标记但它无法判断你写的“这是一张好看的图”对一个想了解图片内容的用户来说有没有价值。这也是许多团队容易产生“虚假安全感”的原因——自动化报告显示 0 violations评审时自然不会刻意去看 alt 内容结果最影响体验的部分反而没人管。可以做一个更直观的推断如果全站图片的 alt 都写成alt图片在 axe-core 的规则下大概率依然全部通过。但这样的页面对读屏用户来说几乎等于没有图片信息。所以这里要建立一个基本共识自动化检查是入场券不是免检标志。它解决的是“有没有”的问题解决不了“好不好”的问题。2. alt 文本的核心概念它到底在做什么alt 是 HTML 中 img 元素的替代文本属性全称 alternative text。它的存在不是为了给鼠标悬停显示提示而是为了给“无法查看图片”的用户提供等效信息。屏幕阅读器如 NVDA、VoiceOver、TalkBack在遇到带 alt 的图片时会直接朗读 alt 内容遇到没有 alt 的图片时行为因浏览器和读屏不同而有差异——有的会跳过有的会读取图片文件名而文件名往往是一串无意义的编号。这就是为什么“没有 alt”不光是规范问题而是真实的体验问题。一个典型例子p2024 年各季度营收变化如下/p img src/images/chart-revenue-2024.png alt2024 年各季度营收折线图Q1 到 Q4 呈持续上升趋势Q4 达到全年峰值 屏幕阅读器用户会听到一段完整的描述可以判断这张图传递的核心信息。如果 alt 缺失可能变成img src/images/chart-revenue-2024.png此时读屏软件可能直接读文件名chart-revenue-2024.png用户无法知道图中内容如果把 alt 写成alt图表虽然文件不再暴露但用户也只获得“这里有张图表”这个信息对于理解页面没有任何帮助。还要区分三个容易混淆的属性属性作用适用场景altimg 的替代文本图片不可见时替代图片本身普通图片、信息图、功能图title提示文本多数情况下鼠标悬停才显示补充说明不构成稳定的替代信息aria-labelARIA 体系中的可访问名称按钮、输入框等交互元素或需要覆盖可访问名称的场景对于 img 来说标准做法是优先用 alt只有当 img 同时充当按钮、链接等角色且可访问名称需要更强控制时才考虑结合 ARIA。不要在一张 img 上同时堆 alt、title、aria-label 三份内容这样反而会造成信息重复。3. 自动化检查到底能查什么、不能查什么以目前前端常用的检查工具为例axe-core一个可访问性规则引擎可以集成到浏览器扩展、Lint 插件或 CI 中。它的规则库覆盖 WCAG 的很多检查项。对于图片它重点检查“是否有替代文本”以及“某些场景下是否不应有替代文本”。LighthouseChrome DevTools 内置的审计工具可访问性类别也包含图片 alt 的检查规则与 axe 类似。eslint-plugin-jsx-a11yReact 项目的 ESLint 插件alt-text规则要求 JSX 中的 img 必须写 alt。这些工具的共同点是基于 DOM 结构做规则判断。它们能看到“有没有 alt”、“alt 是否是空字符串”、“img 是否被 aria-hidden 标记”。它们看不到“alt 内容和图片实际内容是否一致”、“alt 是否适合当前页面的上下文”、“同一张图在不同页面是否应该给出不同描述”。检查能力axe-coreLighthouseeslint-plugin-jsx-a11y检测 img 缺失 alt是是是检测装饰图未使用空 alt部分规则可识别部分部分检测 alt 是否为文件名否否否检测 alt 是否准确描述图片否否否检测 alt 是否与上下文重复否否否判断复杂图表是否需要扩展描述否否否举个例子npx axe-core/cli https://example.com --exit如果页面里有一张img srcbanner.jpg altbanner.jpgaxe-core 大概率不会报错因为图片有 alt 属性且非空。但从用户视角看banner.jpg这个文本毫无信息量。这类问题只能靠人来判断。Lighthouse 也是如此。它可能给你一个绿色分数但它测量的是“符合规则的比率”而不是“图片描述质量的评分”。你可以在 alt 里写满无序字符只要格式不违反规则得分不会变。所以结论是自动化检查的价值在于建立最低门槛把“忘了写 alt”“装饰图写成了普通图”这类硬伤挡在发布前但它无法替代人对内容的判断。这也是本文标题想说的核心——通过检查只是及格。4. alt 文本不合格的典型模式在实际项目里能看到很多“能通过检查但实际不合格”的 alt 写法。这里列几种典型模式。4.1 把文件名当 altimg src/uploads/640edc9f3a21.jpg alt640edc9f3a21这是最容易出现的情况尤其是在内容管理系统里编辑直接使用系统自动填写的默认值。自动化检查看属性非空合法通过。用户听到的是一串哈希值。大部分时候这比不写 alt 好不了多少甚至更让人困惑。4.2 用“图片”二字填充img srcarchitecture.png alt图片这个写法在视觉上完全正常检查也不会报错因为属性存在。但它没有提供任何信息。“图片”两个字用户本来就通过页面结构知道这里是一张图alt 的作用是替代不是复述标签类型。4.3 装饰图没有用空 alt装饰图是指“去掉之后不影响页面理解”的图片。正确的做法是alt让读屏软件忽略它。但很多人担心alt会被检查工具判为“缺失”于是写成alt装饰或altline。结果是屏幕阅读器会把“装饰”两个字读出来用户听的一头雾水。自动化检查认为没问题因为属性非空。这里恰恰是规则和用户感知最容易错位的地方。4.4 alt 与周围文字完全重复h2关于我们/h2 img srcabout-us.png alt关于我们当图片内容已经通过标题或正文完整表达时alt 应该为空而不是再念一遍。重复会让屏幕阅读器用户多听一条无意义的信息同时也增加操作成本。4.5 复杂图表只写一个标题img srcsales-by-region.png alt各地区销售统计图对于柱状图、折线图、地图这类复杂图表单一标题无法传递数据的核心信息。常见的做法是在 alt 里写一个简短概括再在图表下方提供完整数据表格或文字说明。否则用户听到“各地区销售统计图”后仍然不知道数据是什么、趋势是什么。4.6 同一张图在不同位置有不同含义却只写一个固定 alt比如一个产品缩略图在列表页可能只需要产品名在详情页可能需要简要卖点。如果全站都用同一套 alt总有一部分页面语义不对。这属于上下文问题自动化检查完全无法感知。5. 什么样的 alt 文本才算合格一个决策清单判断 alt 是否合格建议按以下顺序走一遍决策流程。这不是复杂的算法而是每次写 alt 时都可以在心里过一遍的清单。第一步判断图片的角色。如果图片是装饰性的、信息已经由周边文本表达、或者移除后不影响理解使用空alt。同时建议给 img 加上rolepresentation或直接用 CSS 背景图降低读屏软件读它的概率。第二步如果图片承载信息判断信息的呈现方式。如果图片本身就是内容比如一个截图、一件商品图、一个人物照片alt 应该用一句话准确描述图片中的关键视觉信息。如果图片是可点击的比如图标按钮、链接里的图片alt 描述的是“点击之后会发生什么”而不是图片的物理外观。第三步检查 alt 与上下文的关系。同样的图片放在“新闻标题”旁边和放在“商品介绍”里alt 很可能不一样。判断标准是屏幕阅读器用户在听到 alt 之后是否获得了与当前段落一致的信息增量如果 alt 只是重复了周围的文字可以删掉。第四步处理复杂图表。复杂图表建议简短概括在 alt 中完整数据以表格、列表或段落形式放在页面中。如果数据量太大无法全部呈现至少要给出结论性描述。把典型的对比整理出来场景不合格示例合格示例信息图alt柱状图alt2024 年各区域销售额对比华东区最高约 1200 万元西北区最低约 400 万元链接图片alt搜索图标alt搜索装饰图alt装饰alt商品图alt图片 12345alt白色无线蓝牙耳机入耳式设计与标题并列的图alt关于我们标题已有alt“搜索图标”这个场景值得额外解释如果图外已有文字“搜索”可以空 alt如果图标是唯一可点击元素alt 必须写“搜索”而不是“放大镜”因为用户关心的是功能不是外观。这段逻辑可以总结成一句话alt 的价值由目标和上下文共同决定而不是由图片文件本身决定。6. 工程化落地把 alt 文本质量嵌入研发流程前面几节说的是“什么是对的”这一节说“怎么在团队里做到”。一个容易执行的方案是分三层第一层提交时用 ESLint 强制 alt 属性存在。第二层CI 中用 axe-core 做整体可访问性规则检查。第三层代码评审或验收时由人按照决策清单对 alt 做抽查。三层各有不可替代的作用。React 项目场景ESLint 配置示例// .eslintrc.js 片段 module.exports { plugins: [jsx-a11y], rules: { jsx-a11y/alt-text: [error, { img: [Image], object: [Object], area: [Area], input[typeimage]: [InputImage] }] } }这段配置只解决“有没有 alt”的问题。它不能保证 alt 内容合格但能在开发早期拦截“漏写属性”这种高频率错误。CI 中可以加一条命令npx axe-core/cli https://staging.example.com --exit --tags wcag2a,wcag2aa--exit让工具在检测到违规时返回非零状态码从而让流水线失败。具体参数以官方文档为准不同版本略有差异。但注意这条命令只检查规则级别的违规。axe 的结果是 0不代表 alt 内容就是合格的。第三层人工评审。建议在 PR 模板中加一段可访问性自检让开发者自己先过一遍**可访问性自检请在合入前确认** - [ ] 本 PR 涉及的新增图片alt 是否正确描述了图片信息或功能 - [ ] 装饰性图片是否已使用 alt 或背景图方式呈现 - [ ] 复杂图表是否提供了文字总结或数据表格 - [ ] 图片作为链接时alt 是否描述链接目的这套流程可以做到机器人负责硬性规则人负责语义质量。两者不互相替代而是互为补充。7. 常见问题与排查思路实际落地时团队会遇到很多看起来矛盾的情况。下面整理几个高频问题。问题现象可能原因排查方式解决方案Lighthouse 可访问性满分但用户仍反馈图片信息不可读alt 存在但内容是文件名或“图片”等无效描述抽查页面源码看 alt 的实际值引入人工评审清单对 alt 内容做抽检ESLint 已经开启 alt-text但仍出现缺失 alt 的图片图片来自富文本编辑器或第三方组件绕过 ESLint 检查检查渲染后的 DOM用浏览器扩展查看 img在内容管理侧增加提交校验或对富文本输出做后置清洗页面里装饰图被读屏软件念出来装饰图写成了普通 alt而非空 alt用屏幕阅读器浏览页面改为alt或改用 CSS 背景图复杂图表 alt 写太长朗读冗长把完整数据全部塞进 alt用屏幕阅读器试听 altalt 写结论正文提供数据表格同一张图在不同页面 alt 不一致不同团队维护不同页面缺少统一规范对全站图片 alt 做一次抽样审计建立图片描述规范并与内容管理流程绑定排查时有一个通用顺序先看渲染后的 DOM再看真实用户操作路径最后才看工具报告。工具报告可以帮助定位疑似问题但永远不能替代“打开读屏软件听一遍”的验证。8. 最佳实践与团队协作建议如果想把 alt 文本质量真正做上去不能只靠前端单方面努力。它涉及产品、设计、内容运营和测试。下面几条经验值得参考。第一把 alt 作为需求文档的一部分。在产品需求或设计稿中对有信息量的图片直接标注“这张图的 alt 建议写什么”。而不是等前端自己猜。很多不合格 alt 的根源是开发者在需求里只看到一张图不知道它想表达什么。第二建立“空 alt 也是一种合格答案”的团队认知。很多团队不敢用alt是因为怕检查报错。但如果正确使用它比写“图片”更合理。团队需要统一理解空 alt 和缺失 alt 是两回事。缺失会触发违规空且语义正确是推荐做法。第三复杂图表优先提供文字数据。alt 只写核心结论完整数据放在图表下方。这样既满足读屏用户也方便所有用户复制和检索数据。第四用屏幕阅读器做体验验收。测试阶段不要只看自动检查结果建议至少选一款主流读屏软件让测试人员用真实操作路径走一遍。听到的声音比代码里的规则更能反映问题。第五对自动生成的 alt 保持警惕。现在很多图片理解模型可以自动生成图像描述但机器生成的描述容易出现“看起来通顺、实际信息缺失”的问题。例如一张统计图模型可能只描述“图表中显示了多条线”关键趋势需要人工补充。自动生成的 alt 必须经过编辑审核才能在正式内容中使用。第六做定期抽检而不是只靠上线前检查。alt 质量问题是存量问题不是增量问题。老内容的 alt 可能长期不合格建议按页面访问量排序分批修复并在每次内容更新时重新检查。9. 从“检查通过”到“用户可用”本文的核心观点可以浓缩成一句自动化检查是 alt 文本质量的底线不是天花板。一个团队如果只能做一件事先把 alt 属性的硬性缺失堵住如果能做两件事加一个自动化检查如果能做三件事把人工评审清单嵌入 PR 流程。三件事做完页面的 alt 质量才能从“看起来没违规”走到“用户真正能理解”。从现在开始可以用一个最小行动验证你的页面打开生产环境的任意一个内容页用读屏工具听一遍首页前 10 张图的 alt再对照第 5 节的决策清单打一次分。这只需要十几分钟但往往能发现自动化检查给出的 0 violations 之外的真实问题。后续如果想继续深入可以关注 WCAG 2.1 和 2.2 中关于非文本内容的标准以及 ARIA Authoring Practices Guide 中对图片、按钮、链接可访问名称的说明。学习这些标准的目的不是为了把规则背下来而是当你面对一张新图片时能自然判断出它该说什么、不该说什么。