自动化测试工具跑完整个面板都是绿的无严重问题。这时候点击发布看起来没有任何毛病。但屏幕阅读器用户打开同一张页面听到的可能是“图片、图片、按钮、图片”三连击。原因很简单自动化检查工具查的是alt属性存不存在而不是alt文本内容合不合格。alt图片工具认定合格altimage001.jpg工具大概率也认定合格alt1照样不违反任何自动规则。而这些文本对辅助技术用户来说约等于没有替代文本。先说明一下本文说的alt是 HTML 里img标签的alt属性解决的是图片替代文本质量问题不是键盘上的 Alt 键也不是 Excel 里 AltEnter 批量换行。如果你是因为搜索“alt”点进来建议先确认一下要找的是哪个 alt。这次我们不谈“随便加几个字母就能通过检测”的做法而是讨论自动化检查的真实边界、什么样才算真正合格的 alt 文本、以及怎么在团队流程里把 alt 质量真正管起来。适合前端开发、内容编辑、无障碍测试和做 SEO 的技术人员阅读。看完你会得到一套可落地的检查清单、几段可以直接复制的替代文本示例以及一段能跑的快速排查脚本。1. 自动化检查的能力边界先分清“硬伤”和“软伤”要理解为什么“自动化通过”不等于“alt 合格”首先得把 alt 问题分成两类硬伤和软伤。硬伤是指不依赖语义理解、机器就能判定的问题。比如img标签根本没有alt属性、alt属性为空但图片又不是装饰图、alt里写的是photo_20240101.jpg这类文件名。这些问题很明确任何自动化工具都能稳定发现。软伤则完全不同。它需要理解图片内容、页面上下文、用户意图才能判断 alt 写得好不好。比如一张柱状图alt柱状图在自动化检查里不会报错但屏幕阅读器用户什么都得不到再比如一个购物车图标按钮alt购物车只是描述了图标外形没有描述“加入购物车”这个功能。这类问题自动化工具基本无能为力。为了更直观可以把自动化工具axe DevTools、Lighthouse、WAVE 等的能力边界整理成一张表检查维度自动化工具能做什么是否等于“alt 合格”img标签缺失alt属性能直接报错不合格alt为空且图片非装饰图部分能结合role判断通常是问题alt为“图片”“image”“jpg”等通用词部分工具能识别模板词不合格alt与周围文本完全重复部分工具能检测需要人工复核alt是否准确描述图片内容无法判断核心问题alt是否结合页面上下文无法判断核心问题alt是否说明链接或按钮功能无法判断核心问题图表类图片是否传达关键数据无法判断核心问题alt语言表达是否适合朗读无法判断体验问题从这张表能清楚看到自动化检查的覆盖范围基本止步于“属性是否存在、格式是否合法”。一旦进入“内容是否合理”的语义层工具就帮不上忙了。这不是工具的问题而是自然语言理解本身就没有稳定标准。同一张图片在不同页面里合格的 alt 可能完全不同。机器无法理解“这张图片在这个页面里承担什么角色”这个决策只能由人来做。2. 自动化检查能查出什么先把机器能解决的问题解决掉不是说自动化检查没有价值它的价值恰恰在于快速、稳定地解决硬伤。一个项目里图片数量动辄几十上百张人不可能每张都盯一遍但工具可以。实际使用中自动化工具通常能查出这些问题img标签缺少alt属性。这是最基础也最严重的问题WCAG 1.1.1 非文本内容要求下没有替代文本等于让辅助技术用户直接丢失图片信息。alt属性为空但图片不是装饰性图片。工具会检查图片是否被标记为rolepresentation或alt如果都没有就会提示异常。alt里包含明显无意义的模板词比如image、photo、picture、图片、截图、文件等。alt与图片附近的标题、正文完全重复。部分工具做了查重逻辑能发现这种冗余。a标签包裹的图片没有 alt或者 alt 没有描述链接目标。这会让屏幕阅读器用户不知道链接要去哪里。alt文本异常过长超过工具设定的阈值。这些问题的共同点是不依赖语义理解机器看一眼 HTML 结构就能判断。所以我的建议是先用自动化工具把硬伤全部清掉这是最基础的一步。但清完之后不要直接去发布接下来要进入语义层人工判断。3. 自动化检查查不出什么真正影响体验的“软伤”这一节重点说自动化工具永远查不出来的问题。这些问题才是 alt 文本质量的核心。第一个问题是语义错位。图片里是夜景alt 却写“蓝天下的建筑”图片里是三季度数据alt 却写“二季度销售情况”。不打开图片的人永远发现不了问题但屏幕阅读器用户听到的就是错误信息。工具只能看到字符串无法理解图片内容。第二个问题是上下文冗余。图片旁边已经有一段文字详细描述了图表结论alt 又把同样的文字重复一遍。屏幕阅读器用户会连续听两遍完全相同的长文本体验很差。这种时候 alt 应该写alt让图片在辅助技术语境下变成装饰性存在。第三个问题是功能缺失。最常见的是按钮和链接图。一个购物车图标alt 写“购物车图标”用户听到的还是图标本身不知道点击后是“加入购物车”还是“查看购物车”。信息图和功能图的 alt 是两个完全不同的写作方向工具却无法区分。第四个问题是图表数据遗漏。alt 写“2025 年销售趋势柱状图”听起来像是有作用但用户听不到趋势是什么。是上升还是下降哪个季度最高增长了几个百分比这些关键信息全丢了。自动化检查把这种 alt 判为通过恰恰是整个流程中最危险的一步。第五个问题是过度依赖视觉术语。alt 写成“左箭头指向绿色按钮”对能看到图片的人来说很形象但屏幕阅读器用户听到的是视觉方位描述和内容无关。更好的写法是直接说功能“点击进入下一步”。第六个问题是冗长不当。有人把整段页面文案塞进 alt导致屏幕阅读器朗读几十秒。alt 的目标不是“把图片里所有文字抄一遍”而是“用最少的语言传递图片真正承载的信息”。信息特别复杂的图表应该用短 alt 配合长描述或者额外的数据表格而不是在 alt 里堆字。第七个问题是误导性表达。alt 写“点击这里”但链接指向哪里用户完全不知道。还有的 alt 为了 SEO 堆砌关键词读出来像一串标签这是把 alt 当成了关键词堆料场。这些软伤即使是最新的人工智能辅助检查工具也很难稳定识别。因为合格与否高度依赖业务上下文。4. 合格的 alt 文本应该怎么写从“通过”变成“真的有用”写合格 alt 的第一步是分清图片的作用。同样一张图片在不同页面、不同角色下正确写法完全不同。先看信息图。如果图片本身就是信息载体alt 要传达的是图片里的消息而不是图片的存在。比如!-- 信息图图片内容就是信息本身 -- img srcquarter-sales.png alt2025年第三季度销售额达到120万元环比增长18%。再看功能图。如果图片是按钮、链接的一部分alt 要描述功能目标而不是外形。比如!-- 功能图搜索按钮 -- button img srcsearch-icon.png alt搜索 /button !-- 功能图购物车链接 -- a href/cart img srccart-icon.png alt查看购物车 /a如果是纯装饰图比如分割线、背景纹理、装饰性图标alt 应该为空并且通过rolepresentation或者直接alt告诉辅助技术跳过!-- 装饰图不传递任何信息 -- img srcdecorative-line.png alt rolepresentation图片旁边已经有文字说明时不要重复写一遍。比如下面这种情况alt 应该留空p本月新增用户 2,800 人/p img srcgrowth-chart.png alt如果图表比较复杂比如多维度数据图短 alt 负责给出结论再通过aria-describedby指向一段长描述把完整数据或者数据出处放在页面里img srcsales-trend.png alt近6个月销售额逐月上升 aria-describedbysales-detail div idsales-detail 2025年1月销售额为80万元2月为95万元3月为110万元 4月为128万元5月为136万元6月为152万元。整体呈上升趋势。 /div写 alt 时还要避开几个常见习惯不要写“图片”“照片”“图”这样的词用处为零不要直接使用文件名不要把视觉位置当成内容描述不要在 alt 里塞关键词堆砌的长难句。读者的注意力应该放在“失去图片的人会损失什么信息”上。5. 人工确认方法一套五问评估法既然自动化工具只能查硬伤人工语义审查就必然要做。这里给出一套五问评估法每次写完 alt或者收到 PR 时拿这五个问题过一遍绝大多数软伤都能暴露出来。第一问这张图片在页面里的作用是什么是传达信息、触发操作、装饰页面还是补充说明正文不同功能决定 alt 的写作方向。第二问如果这张图片被完全移除用户会损失什么信息或操作如果答案是“什么都不损失”说明 alt 应该为空如果答案是“用户不知道按钮点击后去哪”alt 就要写清功能。第三问能不能用一句口语化的描述说清楚这个损失比如“图表显示 6 月销量达到全年最高”而不是“柱状图”。一句口语说不清楚说明这张图可能还需要长描述。第四问这句描述和页面已有文字是否重复、冲突重复就考虑置空冲突就调整措辞否则用户会听到两遍不同版本的信息。第五问屏幕阅读器用户能听懂这句描述吗不要用“上图所示”“横轴纵轴”“左侧红色区域”这类依赖视觉位置的表达。要假设用户从头到尾“看不见”只能听。人工审查的具体操作建议按这几步走第一步用自动化工具跑一遍全站修掉所有硬伤。 第二步用 Tab 键或者屏幕阅读器快速扫读重点页面听图片节点的朗读顺序和内容。 第三步抽样检查核心页面至少包括首页、转化页、内容详情页用五问评估法逐张过。 第四步找一个不认识图片内容的人让他只读 alt 文本看能不能还原关键信息。能还原说明合格还原不了说明还要改。这四步做下来alt 质量会明显上升而且不会花费太多时间。6. 把 alt 质量检查嵌入团队流程人工检查如果只靠自觉很容易流于形式。更可靠的做法是把 alt 质量要求嵌进技术基建和协作流程。前端组件层是最容易卡住的一层。设计系统里的Image组件应该把alt设为必填参数至少在开发阶段强制提示。对 React 项目可以使用eslint-plugin-jsx-a11y它的alt-text规则能检查img标签是否缺失 altimg-redundant-alt规则能识别altphoto、altimage这类模板词。一个最小配置长这样{ plugins: [jsx-a11y], rules: { jsx-a11y/alt-text: [error, { elements: [img] }], jsx-a11y/img-redundant-alt: [error] } }这份配置能在 CI 阶段挡住缺失 alt 的硬伤。但它依然拦不住“alt 写了内容但不准确”的软伤所以 CI 只是第一道关卡。第二道关卡是代码评审。PR 模板里可以加一项检查清单“本次改动的图片 alt 是否描述了信息或功能而不是描述图片外形”评审人不需要多专业只要看到alt图片就能直接打回。第三道关卡是内容后台。如果团队有 CMS在图片上传表单里把 alt 字段设为必填并加上占位提示。提示内容可以写成“用一句话说明这张图片显示的关键信息或功能不要填写‘图片’‘照片’等通用词”。这就从源头拦掉了一半问题。第四道关卡是发布前验证。每次发布前用 WAVE、Lighthouse 或者自己写的脚本跑一遍再人工抽样五个图片。抽样时重点关注带链接的图片和图表类图片。这样的流程组合起来alt 质量就不再依赖某个人的自觉而是成了系统的一部分。7. 快速扫描脚本给硬伤兜底除了现成的工具这里提供一个简单的 Node.js 脚本用于快速排查一个 HTML 文件里的可疑 alt。它不能替代语义判断但能在本地开发时快速兜底。先强调一下这个脚本用正则解析 HTML只适合快速自查。真实生产环境建议使用htmlparser2、jsdom这类正规解析器避免正则误判。const fs require(fs); const filePath process.argv[2]; if (!filePath) { console.error(用法: node check-alt.js index.html); process.exit(1); } const html fs.readFileSync(filePath, utf-8); const imgRe /img\b[^]*/gi; const altRe /alt\s*\s*([^]*)/i; const genericWords [ /^image$/i, /^photo$/i, /^picture$/i, /^图片$/, /^照片$/, /^图$/, /^截图$/, /\.(png|jpg|jpeg|gif|webp|svg)$/i ]; let match; let hasIssue false; while ((match imgRe.exec(html)) ! null) { const tag match[0]; const altMatch tag.match(altRe); if (!altMatch) { console.log(缺少 alt 属性:, tag.slice(0, 100)); hasIssue true; continue; } const alt altMatch[1].trim(); if (!alt) { console.log(空 alt请确认是否为装饰图:, tag.slice(0, 100)); hasIssue true; } else if (genericWords.some((re) re.test(alt))) { console.log(疑似通用模板 alt:, tag.slice(0, 100)); hasIssue true; } else if (alt.length 2) { console.log(alt 过短信息量可能不足:, tag.slice(0, 100)); hasIssue true; } else if (alt.length 150) { console.log(alt 过长建议拆分或用长描述:, tag.slice(0, 100)); hasIssue true; } } if (!hasIssue) { console.log(扫描完成未发现明显的硬伤问题。); } else { console.log(扫描完成以上为可疑项需人工复核。); }在命令行里可以直接运行node check-alt.js index.html脚本输出的每一项都是“可疑项”不是最终判决。比如空 alt 可能是装饰图是合理的alt 过长也可能是复杂图表需要详细说明。它存在的意义是快速把需要人工关注的点挑出来避免眼睛扫漏。8. 常见误区与排查实际项目中alt 质量问题往往集中在几个固定模式上。下面用表格整理出来方便对照排查。常见误区自动化检查结果对辅助技术用户的真实影响正确做法alt图片通常通过听到“图片”零信息按图片作用写具体内容或功能altphoto_20240101.jpg部分工具报疑似文件名朗读文件名无意义写内容语义不用文件名装饰图写了alt装饰线通过无意义朗读干扰浏览alt或rolepresentation图片旁已有文字alt 再重复一遍部分工具查重复同一信息被朗读两次置空 alt 或用极简补充alt点击这里通过不知道链接目标描述链接后的目标或动作图表 alt 只写“柱状图”通过不知道数据趋势和结论短 alt 给结论配合长描述或数据表除了这些误区排查时还经常遇到一种情况自动化工具全绿但屏幕阅读器读起来就是不对。这时候不要继续盯报告直接开一个无障碍环境实测。macOS 和 iOS 上可以用 VoiceOverWindows 上可以用 NVDAAndroid 上可以用 TalkBack。打开后按快捷方式跳到图片节点听一下朗读的上下文。重点听三个东西朗读顺序对不对、alt 文本前后是否通顺、和周围的页面文字组合起来能不能理解。这一步能暴露出很多“语法合格但语义混乱”的问题。如果页面里图片很多建议先修核心页面再铺开到全站。优先级是首页、产品列表页、详情页、购物流程相关页面、表单页面最后才是博客和内容页。9. 最佳实践与合规建议alt 文本质量不是纯粹的技术问题它同时涉及无障碍合规、内容质量和 SEO。这里给几条工程化建议可以直接吸收到团队的工作方式里。第一把“自动化通过”当成最低标准而不是完成标准。无障碍合规的判断标准应该回到真实用户替代文本是否真的替代了图片的信息。WCAG 1.1.1 非文本内容的核心就是“文本替代是否等价”不是“标签里有没有字符串”。第二对复杂图表建立长描述机制。遇到多维度图、地图、流程图单纯靠 alt 很难说清楚。最好的方案是用短 alt 给结论再配合aria-describedby长描述或者直接在页面正文里附一份数据表格。这样既能保证屏幕阅读器用户拿到完整信息又不影响普通用户的阅读体验。第三不要为了 SEO 在 alt 里堆关键词。alt 的正文价值在于替代图片而不是关键词排名。堆砌关键词会让屏幕阅读器用户听到一串不知所云的标签也会让页面文本混乱。搜索引擎对 alt 的理解越来越接近语义真正准确的描述反而更有利于相关性判断。第四每次发布前做一次屏幕阅读器抽样。不需要全站跑挑一个含信息图、含功能按钮图、含装饰图的页面用 VoiceOver 或 NVDA 听一遍。整个流程十分钟以内能拦住绝大多数软伤。第五把 alt 编写规范沉淀到团队文档里。规范里至少包含图片作用分类、各类图片的写法示例、禁用词清单、复杂图表处理方案、五问评估法。这样新同事也能快速上手不会凭空猜测。第六注意内容版权和图片授权。如果用到的图片本身来自第三方素材库、用户上传、或者包含人脸、商标、字体等信息使用前必须确认授权范围。alt 文本不要虚构图片里不存在的信息也不要放大图片没有明确呈现的数据结论。第七对用户上传图片的内容平台alt 生成逻辑要谨慎。如果完全依赖自动生成生成结果必须经过人工或半人工审核避免出现描述错误、偏见表达或不适合的场景。尤其是电商、社交平台、新闻媒体这类高流量内容场景。10. 总结与下一步这篇文章的核心判断其实只有一句话自动化检查通过只代表你的 alt 文本没有语法级硬伤不代表它真的合格。真正决定合格与否的是图片在页面里的作用是否被准确传达给了看不见图片的人。最值得优先动手验证的是拿一张当前项目里的信息图把 alt 从“XX图”改成一句具体信息然后用屏幕阅读器听一遍前后差异。这个过程会让你对“替代文本”这四个字有更直观的感受。最容易踩的坑也很明确看到工具全绿就发布。工具是过滤器不是裁判。它可以帮你拦住低级问题但高级问题必须靠人和流程。后续可以继续扩展的方向包括在 CI 里接入 ESLint 规则和自定义扫描脚本、在 CMS 后台增加 alt 质量提示、给团队建立图片替代文本抽查机制以及针对图表类图片设计长期可复用的长描述模板。建议收藏备用。下次再看到“全部通过”的检查报告至少要先问一句真的合格吗