在无障碍审核中alt 文本经常是最容易被误解的一项。扫描工具报告“全部通过”页面上的图片却可能对依靠屏幕阅读器访问页面的用户造成严重的信息断层。原因在于alt 文本是否合格本质上不是字段填写问题而是一个语义决策问题。自动化检查可以确认img标签存在、alt 属性非空、长度不超限但它无法判断这段替代文本在当前页面上下文里是否准确、简洁、功能完整。这篇文章从 alt 文本的消费机制讲起分析自动化检查的能力边界再用具体案例说明什么样的 alt 文本才算真正合格最后给出可执行的评价规范和团队落地建议。1. 先理解 alt 文本的机制再谈自动化检查为什么局限1.1 alt 文本不是“图片描述”而是图片在特定上下文中的功能替代很多开发者在写 alt 文本时习惯把它当成“图片标题”或者“图片注释”于是写出alt公司团建照片、alt产品图片这类内容。严格来说这个理解从起点就偏了。alt 文本的正式名称是 alternative text作用是“当图片无法被用户感知时用文本向用户提供与图片等价的信息”。注意重点是“等价信息”不是“图片里有什么”。一张展示销售数据的柱状图如果 alt 写成“柱状图”用户只知道自己读的页面上有一张柱状图但不知道数据趋势如果 alt 写成“2024 年 Q1 到 Q4 销售额从 120 万增长到 320 万”用户即使完全看不到图也能获得图片要传达的核心结论。所以判断 alt 是否合格第一个标准不是“有没有写”而是“写完后看不到图片的人是否获得了和看到图片的人等量的关键信息”。这个标准天然依赖上下文同样一张人物照片放在新闻正文里当配图与放在“领导团队”列表里作为成员头像合格的 alt 内容完全不同。1.2 浏览器和屏幕阅读器如何消费 alt 文本先看 HTML 中图片的标准写法!-- 装饰性图标不传达信息 -- img srcdecorative-line.png alt !-- 链接内图片alt 描述链接目标 -- a hrefhttps://example.com/download img srcdownload-icon.png alt下载安装包 /a !-- 页面顶层需要描述的配图 -- img srccampus-2024.jpg alt2024 年新投入使用的东区教学楼外立面为灰色石材与玻璃幕墙浏览器在正常显示图片时alt 文本是隐藏的用户通常不会看到。但发生以下情况时alt 文本会直接进入用户的感知通道图片加载失败浏览器在图片占位区域渲染 alt 文本用户使用屏幕阅读器例如 NVDA、JAWS、VoiceOver图片被跳过改为朗读 alt 文本用户使用纯文本浏览器或开启“减少动态效果”“关闭图片”等设置搜索引擎索引图片时将 alt 文本作为判断图片内容的重要信号。屏幕阅读器用户的操作流程需要重点理解。当焦点或浏览光标进入一张图片时读屏软件通常会把图片角色和 alt 内容一并读出例如有 alt 的图片读作“图片2024 年新投入使用的东区教学楼……”alt的图片直接跳过没有 alt 属性的图片读作“图片”——只有角色没有任何内容有 alt 但内容是文件名altDSC00123.JPG的图片读作“图片DSC 00123 JPG”。由此可见altDSC00123.JPG比空 alt 更糟因为用户不仅没有得到信息还要处理噪音。真正合格的 alt 目标是让读屏用户获得的信息结构与视觉用户尽量一致既不缺失也不冗余。1.3 自动化检查到底在检查什么常见的自动化检查工具包括 Lighthouse、axe-core、pa11y、W3C HTML Validator以及各类前端工程里集成的 eslint-plugin-jsx-a11y。它们对图片的检查规则大体集中在以下三类图片元素必须包含 alt 属性alt 属性不能为空字符串除非图片被标记为rolepresentation或aria-hiddentrue标题属性与 alt 不应完全重复避免读屏软件重复朗读。在 axe-core 的规则文档中与图片直接相关的规则是image-alt它只检查 img 元素是否有可访问名称。如果 alt 属性缺失会报Ensures img elements have alternate text。如果 alt 属性存在且不为空工具就会判定通过。这带来一个典型误读Lighthouse 无障碍分数 100图片来源就全部合格。实际上自动化工具默认了一个前提只要作者手动写了 alt作者就具备判断能力。它无法判断这段 alt 是否准确、是否和页面文字重复、是否包含了图片传达的全部关键信息、是否适合当前语言环境。这些都需要人类判断或者需要更高维度的系统约束。下面用一个快速验证的示例说明自动化检查的粒度!-- 场景 A会被工具判定为通过 -- img srcchart-revenue.png alt营收图 !-- 场景 B会被工具判定为通过 -- img srcchart-revenue.png alt2024 年各季度营收曲线整体呈上升趋势Q1 为 120 万Q4 为 320 万 !-- 场景 C会被工具判定为通过 -- img srcchart-revenue.png alt营收图 2024 年各季度营收曲线整体呈上升趋势 Q1 为120万 Q4 为320万 数据来源 财务部 制表人 张三三个场景在 axe 和 Lighthouse 面前等效但在真实用户面前差异极大。场景 A 信息不足场景 B 相对合格场景 C 虽然信息全但冗余、不聚焦。自动化检查无法区分这些差异这是它最核心的能力边界。2. 自动化检查能发现的问题和无法发现的问题2.1 自动化检查能稳定发现的问题先说自动化工具擅长的事情。这类工具适合做“机器可判定的语法和结构检查”对于以下问题很可靠图片缺少 alt 属性装饰性图片使用altsome-id而非空 altimg 被aria-hiddentrue包裹但内部仍有内容同时使用 alt 和 title且二者内容完全一致可能导致重复朗读CSS background 图片无法获取 alt 文本这个通常不会被 image-alt 报出来但会被人工评审发现。把自动化检查当作“语法层”把关是合理的。它可以在 CI 中拦截明显不合规的写法提醒开发人员补写属性减少人工评审的低级轮次。2.2 自动化检查必然误判的场景下面这五类场景自动化工具几乎都判断不了但它们恰恰是 alt 文本质量差异的主要来源。第一类是纯装饰图片和功能图标的区分。页面背景上的装饰性线条图案视觉上没有任何信息正确写法是alt。而链接中的下载图标功能是告诉用户“点击后下载”正确写法是alt下载 PDF 合同模板。工具只能检查 alt 是否存在无法判断这个图片到底是装饰还是功能。第二类是 alt 与周围文本是否互为补充。如果标题下面已经写明了“2024 年 Q1 营收 120 万”图片 alt 再写“2024 年 Q1 营收 120 万”读屏用户会听到两遍相同信息。这属于冗余但自动化工具会认为 alt 写得很好。第三类是 alt 是否准确描述图片功能。一个“联系我们”的按钮图标alt 写成alticon读屏用户听到“链接图片icon”无法判断点击后会进入哪个页面。自动化工具不会判断“icon”是否有意义。第四类是图片中是否包含文字。如果一张截图里包含关键操作路径例如菜单路径“设置 安全中心 两步验证”alt 没有把这些文字放进去使用读屏软件的视障用户就完全无法感知截图内容。该场景在微信、文档工具、管理后台截图里极其常见。第五类是语言和地区语义。一个简体中文网站配一个altCompany Overview虽然非空但读屏用户听到的是一句英文这种问题工具也发现不了。2.3 自动检查与人工评审结果对照检查维度自动化工具能力人工评审能力说明alt 属性是否存在强弱工具可以自动拦截缺失alt 是否为空字符串弱强需要结合图片是否为装饰判断alt 内容是否与图片功能匹配无强需要理解页面目标alt 内容是否与页面周边文本重复无强需要读取上下文alt 是否覆盖图片中的关键文字无强截图类图片尤其重要alt 是否适合目标语言无强多语言站点必须人工抽查alt 长度是否合理部分强工具只能设置硬长度上限装饰图是否正确使用空 alt无强需要视觉判断这张表的结论很清楚自动化检查在“形式完整”这一层有用到“内容合格”这一层几乎无效。正确策略是让自动化工具承担入口拦截让人工评审承担质量判断。3. 用真实案例区分“通过检查”和“真正合格”3.1 案例一装饰性图片写成非空 alt信息没增加反而更糟常见场景是页面装饰分割线、圆角装饰、渐变背景上的小光点。有些开发者为了通过自动化检查把这类图片写为img srcyellow-dot.png alt黄点自动化检查通过。但读屏用户听到“图片黄点”完全不知道这个黄点代表什么。更合理写法是img srcyellow-dot.png alt这样读屏用户不会收到任何噪音页面信息不因装饰图而中断。判断标准只有一个如果把这行 img 从页面中删除视觉用户看到的信息有没有变化。没有变化就使用空 alt。3.2 案例二按钮图标 alt 写成图片文件名交互目标丢失管理后台常见的操作为“编辑”“删除”“导出”三个图标。如果写成a href/edit/1001 img srcedit.png altedit.png /a读屏用户听到“链接图片edit.png”。用户不知道链接是指向编辑功能还是打开一个名为 edit.png 的下载文件。这是功能性 alt 失效的典型情况。正确写法是描述链接行为而不是描述图片视觉a href/edit/1001 img srcedit.png alt编辑订单 1001 /a这类 alt 的检查点在读屏体验上等价于“这个链接的文本是什么”。如果图片不可见用户能够仅凭 alt 判断点击结果就算合格。3.3 案例三信息图只有一句描述关键结论全部丢失信息图是最容易暴露 alt 质量问题的图片类型。一张包含“四个步骤、六条数据、两条注意事项”的总览图如果 alt 只写“安全迁移系统步骤图”读屏用户只能知道页面有一张图但不知道任何步骤。正确的做法有两种。第一种是图片本身简单把所有关键信息写进 altimg srcmigration-steps.png alt系统迁移四步备份数据库关闭旧应用切换配置启动新应用并验证访问 第二种是图片信息复杂在正文中提供等价数据表格或文字说明figure img srcmigration-steps.png alt系统迁移步骤示意图 figcaption 系统迁移四个步骤 1. 备份数据库 2. 关闭旧应用 3. 切换配置 4. 启动新应用并验证访问。 /figcaption /figure第二种做法更适合信息量大的图。alt 提供概览figcaption 或相邻文字提供完整数据读屏用户获得的信息与视觉用户基本一致。3.4 案例四alt 与相邻文本重复读屏变得啰嗦设计系统里的常见页面一般长这样h22024 年第四季度营收/h2 p2024 年 Q4 营收为 320 万元环比增长 15%。/p img srcq4-revenue.png alt2024 年第四季度营收为 320 万元环比增长 15%自动化工具看到非空 alt标记通过。读屏用户却会听到两遍相同的数字。此时 alt 应该只承担图片图形结构的信息例如“折线图展示 2024 年 1 月至 12 月营收逐月变化年中有一段时间平缓年末快速上升”。数字和结论已经在页面文字中不需要重复放入 alt。4. 建立可执行的 alt 文本评价规范4.1 四个评价维度功能、简洁、上下文、独立把真正合格的 alt 文本拆成四个可判断的维度团队评审时不必凭感觉打分。第一个维度是功能性。先问这个图片在页面里承担什么职责是传达数据还是引导跳转还是纯装饰。职责不同写法完全不同。第二个维度是简洁性。alt 文本不是图片说明文。在完成功能目标的前提下能用一个短语表达的不要写成一个段落能写一句话的不要写两句话。过长的 alt 不仅干扰读屏也让维护变得困难。第三个维度是上下文相关性。alt 必须结合它在页面中的位置来判断。同一个人物照片在“团队成员”页面和“新闻人物”页面写法不同。在团队成员页面会写“张三研发部后端工程师”在新闻页面会写“张三在技术峰会上讲解系统架构设计”。第四个维度是独立性。读屏用户通常先听到 alt再听到周边文字。alt 应该在脱离图片的情况下可以独立理解不能包含“如上图所示”“见下图”这类依赖视觉位置的表达。4.2 常见图片类型的推荐写法与不推荐写法下面这张表可以直接作为团队评审依据图片类型不推荐写法推荐写法理由装饰性分割线alt分隔线alt无信息避免噪音链接图标alt图标alt下载合同模板需要描述链接目标数据图表alt柱状图alt2024 年 Q1 到 Q4 营收从 120 万增长到 320 万需要传达数据结论信息图alt流程示意图alt系统迁移四步流程概览详见下方说明复杂图需要配套文字人物头像alt头像alt张三产品部负责人团队成员场景需要人物身份产品图片alt产品图片alt灰色机械键盘87 键布局商品详情需要基本外观信息验证码图片alt验证码alt请输入图片中的四位字符无法识别时可点击刷新验证码 alt 不写具体字符二维码alt二维码alt扫码进入微信公众号公众号名称为 XX提供扫码后的目标说明背景装饰图alt背景alt背景图通常应使用 CSS不应出现在 HTML 中验证码图片需要额外说明。出于安全考虑验证码的 alt 不应直接包含验证码字符否则自动化程序可以直接读取。正确做法是提示用户输入图片中的字符并附加“无法识别时可点击获取新验证码”的说明。4.3 开发侧如何落实评价规范评价规范只有在落在代码审查和组件封装中才具备约束力。推荐做三件事。第一件事是建立可复用的图片组件。在 React 项目中可以封装一个带 alt 校验的组件占位实际项目需要结合自己的技术栈调整type AccessibleImageProps { src: string; alt: string; decorative?: boolean; }; function AccessibleImage({ src, alt, decorative false }: AccessibleImageProps) { if (decorative) { return img src{src} alt rolepresentation /; } if (!alt || alt.trim().length 0) { // 开发环境抛出错误构建阶段也可以集成 lint 规则 console.error([AccessibleImage] 非装饰图片必须提供 alt 文本。); } return img src{src} alt{alt.trim()} /; }这个组件只是最小示例。真实项目中还可以把 alt 的文案规则写进团队的代码规范文档中并在 code review 时专门检查 alt 字段。第二件事是配置 eslint 规则。eslint-plugin-jsx-a11y的alt-text规则可以覆盖缺失 alt 的情况虽然它不能判断语义质量但能在第一时间拦截“写了 img 却忘记 alt”的低级遗漏。第三件事是把人工审查模板化。评审页面时不要只问“alt 有没有写”要按下面的清单逐项确认。这个清单可以直接贴在代码仓库的 pull request 模板或者部门无障碍检查单里。5. 团队协作自动化工具 人工评审 组件约束5.1 CI 管道中接入自动检查自动化检查虽然不能替代人工判断但可以在早期把基础问题挡在门外。前端项目可以在 CI 中执行以下命令# 使用 lighthouse-ci 对目标页面做基础无障碍扫描 npx lighthouse https://example.com/form-page --only-categoriesaccessibility --outputjson --output-path./lighthouse-report.json # 使用 pa11y 扫描页面 npx pa11y https://example.com/form-page在本地开发阶段也可以直接针对单个 HTML 文件执行 axe# 全局安装 axe-core 与辅助脚本后运行扫描 npx axe-core/cli https://example.com/list接入 CI 的核心目标是让“图片缺失 alt”这类问题在合并代码前被拦截避免把基础错误带进生产环境。CI 中的检查结果不要作为唯一标准它更像是提交代码前的门槛。5.2 人工评审矩阵人工评审通常出现在页面改造、设计走查、无障碍专项审计三种场景。评审时可以使用下面这个矩阵给每个图片打分图片定位alt 是否存在alt 是否为空功能是否映射是否与正文重复是否覆盖关键信息是否语言一致结论首页 Banner 图是否是否是是通过数据图表是否部分是否是需修改用户头像是是是否是是通过装饰飘带是是不适用不适用不适用不适用通过评审结果不是“通过/不通过”二选一而是给出修改方向。评审重点放在信息完整性而不是机械地填满 alt。5.3 用组件封装和 lint 规则兜底组件封装可以改变团队默认行为。例如如果团队使用 Vue可以要求所有图片统一走业务封装的 Image 组件组件内部强制 alt 参数template img :srcsrc :altdecorative ? : altText :roledecorative ? presentation : undefined /template script setup import { computed } from vue; const props defineProps({ src: { type: String, required: true }, altText: { type: String, default: }, decorative: { type: Boolean, default: false }, }); /script组件封装解决的是“格式统一”lint 解决的是“属性缺失”人工评审解决的是“语义是否合格”。三者组合才能形成完整闭环。另外后台内容编辑中的图片更需要注意。CMS 系统如果允许运营人员上传图片前端最好能够校验 alt 是否填写并在图片库列表中把“alt 为空”作为筛选条件。许多实际项问题并不是开发时写错而是运营后台上传的图片 alt 被留空前端只能显示默认 alt 或文件名。6. 常见问题排查与质量清单6.1 常见误区与排查链路在实际项目验收中容易反复出现以下问题第一个误区是“自动化得满分就是无障碍合格”。一个页面如果所有图片都有 alt但 alt 全部是alt图片自动化检查会通过实际体验却很差。排查方式是用读屏软件实际走一遍页面或者让一位不了解页面的同事只凭读屏输出描述页面内容如果描述完整清晰才算合格。第二个误区是“装饰图片和功能图片无法区分就统一填空”。最稳妥的方法是建立设计规范设计稿中标注哪些图片是装饰、哪些图片包含功能。前端实现时严格按照标注填写 alt。经验欠缺的团队可以先从页面头部、侧边栏、按钮图标三个高频位置开始标注。第三个误区是“alt 越长越好”。alt 过长会让读屏用户难以抓住重点建议优先用正文承载详细数据alt 只做定位和概要。例如正文表格已经列出全部数据时图片 alt 写“按月份排列的收支柱状图”即可不需要重复整张表。第四个误区是“图片里的文字不用写进 alt”。审批系统中一张截图包含“任务已驳回”的状态如果 alt 只写“审批截图”读屏用户完全不知道任务被驳回。正确写法至少是“审批截图状态为已驳回批注为材料不全”。排查问题时可以按以下链路从现象倒推根因现象可能原因检查方式处理建议读屏用户反馈“听到一串图片名”alt 写的是文件路径或随机 ID打开浏览器开发者工具检查 img 元素改写为语义化 alt读屏用户反馈“页面很吵重复听到同一句话”alt 与页面标题或正文重复对照 alt 与相邻文本精简 alt只保留图形层信息自动化工具报 image-alt 错误img 缺少 alt 属性检查是否用了自闭合 img 且漏写属性补写 alt 或标记装饰图图片加载失败后页面显示文件名alt 来自动态参数未做兜底检查前端渲染逻辑增加默认 alt 和空值校验多语言站点英文 alt 未翻译文案接入时只处理了 visible text抽查多语言页面源码将 alt 文案纳入翻译资源管理截图类图片信息缺失alt 只写“截图”人工评审截图内容将截图中的关键文字写入 alt 或 figcaption6.2 alt 文本审核清单给开发、测试和内容编辑共用建议打印出来作为页面发布前的检查项检查页面中每个 img 元素是否都有 alt 属性。区分装饰图片和功能图片装饰图片使用alt不使用非空文字。对链接里的图片确认 alt 描述的是链接目标而不是图片外观。对按钮里的图片确认 alt 描述的是操作结果。对数据图确认 alt 已经传达核心数据结论而不是只写“柱状图”。对信息图确认 alt 提供概览完整数据在正文或可访问表格中提供。对截图类图片确认截图中的关键文字、按钮、状态已被替代文本覆盖。检查 alt 与页面周边文本是否存在重复重复部分从 alt 中移除。检查多语言页面中 alt 是否使用了与页面语言一致的文本。不要把重要信息只放在 title 属性中title 依赖鼠标悬停移动端和读屏设备都不可靠。6.3 继续深入的方向alt 文本只是可访问性的一个环节。真正完整的无障碍建设还需要考虑键盘可操作、焦点顺序、颜色对比度、表单标签、ARIA 使用规范、动态内容提示等。从团队落地角度建议先从图片 alt 开始因为它的整改成本低、判断规则清晰、影响范围广。进阶时可以继续做三件事一是为内容编辑提供可视化 alt 编辑与预览工具二是建设图片素材库时强制填写 alt 元数据三是在设计评审阶段就把 alt 内容纳入验收标准。越早在流程中定义 alt后期返工成本越低。对开发团队最实用的建议是不要只在合规审计前才检查 alt。把 alt 质量纳入每次代码评审和页面验收的固定项目并让熟悉屏幕阅读器的成员定期做真实走查。自动化工具的价值在于兜底语法人工评审的价值在于保障语义两者缺一不可。