先说一个常见的开发场景自动化可访问性检查跑完提示“通过”你松了口气觉得图片的替代文本已经达标了。但把页面交给真实用户使用时读屏软件却念出一段让人完全摸不着头脑的描述甚至把整张插图的重点信息漏掉了。问题出在哪很可能是你把“自动化检查通过”等同于“alt 文本真正合格”而这两者之间存在一条很容易被忽略的鸿沟。本文讨论的可访问性中的 alt 文本指的是 HTML 中img标签的alt属性它用于向屏幕阅读器等辅助技术提供图片的文字替代说明和 Excel 里的 Alt 键、Photoshop 里的 Alt 键不是同一个概念。很多前端开发者在做页面改造时习惯以自动化工具的结果作为唯一标准只要 Lighthouse 或 axe 不报警就认为图片无障碍处理完备。但自动化检查只能判断“有没有”很难判断“对不对”。一张图片有没有alt属性是确定性的规则而 alt 文本是否准确、是否等价、是否满足上下文需求则需要人工判断和充分的内容理解。这篇文章会从自动化检查的原理与局限出发结合真实案例说明为什么“通过检查”和“真正合格”是两件事并给出从编写到审查的完整落地方法。适合前端开发、测试工程师、SEO 运营以及所有需要维护网站内容质量的开发者阅读。读完你会掌握alt 文本的合格标准、自动化工具测不出什么、以及如何建立一套可靠的人工校验机制。1. 背景与核心概念1.1 什么是 alt 文本alt 文本是 HTML 中图片元素的一个属性img srcchart-2024-sales.png alt2024 年各季度销售额柱状图 /当图片无法加载时浏览器会显示 alt 文本当用户使用屏幕阅读器时辅助技术会朗读 alt 文本当搜索引擎索引图片时alt 文本也是重要的语义信号。它同时服务于可用性、可访问性和 SEO 三个目标。无障碍领域有一个基本原则任何非文本内容都需要提供替代文本。alt 文本的职责不是“把图片里所有文字抄一遍”而是提供与图片功能等价的信息。如果图片本身是装饰性的那么它应该使用空 altalt如果图片承载了内容那么 alt 文本必须表达出图片在页面上下文中的含义。1.2 自动化检查能做什么自动化检查工具比如 Lighthouse、axe-core、WAVE 等是团队做无障碍治理的第一道防线。它们擅长执行有明确规则的检查项比如img元素是否缺少alt属性img元素是否包含空alt但周围没有等价文本按钮图片是否没有替代文本带有title或aria-label的元素是否与可见文本不一致背景图是否承载了内容信息。这些检查是确定性的属性在不在、是否为空、是否满足基本命名要求机器可以通过 DOM 快速判断。它们是成本极低、效率极高的基础筛选环节。1.3 自动化检查的边界但自动化检查有一个天然盲区它不理解图片在页面中的语义角色更不理解图片真实传达的内容。举一个最常见的例子img srcapi-flow.png alt流程图 /一名自动化检查工具跑完会认为这条通过因为alt存在且非空。但“流程图”这三个字对读屏用户来说几乎毫无价值。它没有告诉用户这是关于什么系统的流程图包含哪几个关键节点数据流向是怎样的如果一个图表展现的是订单从创建到支付再到发货的完整链路alt 文本只写“流程图”听用户等于只获得一个文件名级别的提示。这就是“能通过自动化检查但不代表真的合格”的核心矛盾。自动化工具看到的是属性存在性而用户需要的是信息等价性。两者之间的差距恰恰是 alt 文本质量提升的空间。2. 环境准备与工具选择2.1 涉及的技术栈本文的实践部分会覆盖以下工具和配置Chrome DevTools 和 Lighthouse版块式检测axe-core可集成到测试代码中的规则引擎HTML 或任意前端框架中的图片标签写法可选CI 流水线中接入自动化检查脚本。版本方面没有硬性要求自动化检查工具更新较快不同版本检查规则可能存在细微差异。本文重点是配置思路和判断逻辑你使用时需要根据项目实际情况调整版本。2.2 搭建一个测评环境为了方便验证我们创建一个极简的 HTML 示例页面。只需一个文件浏览器即可打开。mkdir alt-text-demo cd alt-text-demo touch index.html这个页面会包含几类带有 alt 文本的图片普通说明图、功能性按钮图、装饰图、图表图。接下来我们用自动化工具检查它再逐个人工审视 alt 文本是否真正合格。3. 自动化检查能查什么规则背后是“存在性”而非“质量”3.1 常用检查工具与基础规则以 axe-core 为例它基于 WCAGWeb 内容可访问性指南规则对页面进行检测。图片相关的核心规则包括规则 ID检查内容判断逻辑image-alt图片必须有替代文本检查img是否有alt属性button-name按钮必须有可访问名称检查button内部是否有文本或aria-labellink-name链接必须有可访问名称检查a是否包含文本内容image-redundant-alt图片 alt 文本不能与相邻文本重复检查是否冗余重复可以看到image-alt规则只验证“是否存在alt属性”不会判断 alt 文本是否准确、完整、有信息量。Lighthouse 的可访问性审计中也包含类似规则“Image elements have[alt]attributes”。审计逻辑同样只做存在性判断失败图片没有 alt 属性通过图片有 alt 属性无论内容是什么。这就是自动化检查的天花板。3.2 把 Lighthouse 集成到本地检测浏览器打开页面后按 F12 打开开发者工具切到 Lighthouse 面板选择 Accessibility 分类点击生成报告。报告会给出“通过”“警告”“失败”三类结果。命令行版本同样可用npx lighthouse https://example.com --only-categoriesaccessibility --outputjson --output-path./lighthouse-result.json不过 Lighthouse 是针对整体页面、使用模拟规则做审计所以直接使用 DevTools 面板即可快速验证。3.3 把 axe-core 集成到代码中如果你想在本地测试或 CI 里稳定使用image-alt这类规则可以在 Node.js 环境里跑一遍。npm init -y npm install axe-core --save-dev然后写一个简单脚本对 HTML 文件或页面 URL 执行检查// 文件路径check-alt.js const fs require(fs); const { JSDOM } require(jsdom); const axe require(axe-core); const html fs.readFileSync(./index.html, utf-8); const { window } new JSDOM(html); axe.run(window.document, (err, results) { if (err) { console.error(检测执行异常, err); return; } const violations results.violations.filter(v v.id image-alt || v.id button-name || v.id link-name ); if (violations.length 0) { console.log(✅ 通过未发现明显图片 alt 问题); } else { violations.forEach(v { console.log(❌ 违反规则, v.id); v.nodes.forEach(node console.log( - , node.target, node.html)); }); } });这段代码的作用是读取index.html使用 axe-core 规则引擎检查页面中的图片、按钮和链接并输出违规节点。运行方式npm install jsdom --save-dev node check-alt.js需要注意的是jsdom不会真实渲染图片也不会计算 CSS 样式所以 axe 的检测仅限于 DOM 结构层这样已经能满足image-alt这类规则检查。3.4 自动化检查的“假阳性”与“假阴性”理解“假阴性”是理解本文主题的关键。自动化检查中image-alt规则很难出现“假阳性”即没问题的图片被判违规但会出现大量“假阴性”即有问题但规则没抓到。例如alt图片从规则角度看它有 alt通过。从用户角度看等于没写alt这是产品图通过检查但用户可能完全不知道产品是什么、有什么特点alt且图片本质上是内容图如果周围没有等价文本规则不一定会报警但读屏用户会丢失信息。因此自动化检查更准确的定义是“机器可以执行的、规则化检查的最小集合”。它用来兜底防止低级遗漏但不能替代人工对信息质量负责。4. 真正合格的 alt 文本应该怎么写4.1 核心原则等价替代而不是字面描述WCAG 对非文本内容的要求用的是“equivalent alternative”也就是等价替代。这个词组包含两层意思图片传达的信息alt 文本也需要传达图片在页面语境中的功能alt 文本也需要满足。所以写 alt 文本时我们需要先问自己三个问题这张图片为什么出现在这个位置它想向用户传递什么信息如果把图片移除用户需要什么文字才能获得同样信息这三个问题的答案就是 alt 文本的核心内容。4.2 内容图的合格写法比如页面展示了一张地图标记了线下门店的位置。不合格img srcstore-map.png alt地图 /合格img srcstore-map.png alt门店位置地图标注了北京朝阳区望京 SOHO 塔 1 一层底商的位置。 /区别很明显。前者只是告诉用户“有一张地图”后者告诉用户地图上有什么关键信息。读屏用户听到后者可以形成有效认知甚至不需要视觉查看。再比如一张销售趋势折线图不合格img srcsales-trend.png alt销售趋势图 /合格img srcsales-trend.png alt2024 年每季度销售额折线图Q1 为 120 万Q2 为 150 万Q3 为 130 万Q4 为 210 万全年保持波动上升趋势。 /这里需要补充说明的是如果折线图数据非常复杂全部放进 alt 文本会导致朗读体验冗长此时更好的做法是使用表格描述数据并在图片旁边附上完整数据表alt 文本写为“2024 年销售额折线图具体数据见下表”。4.3 功能性图片与按钮图片当图片本身是按钮或链接的一部分时alt 文本应该描述操作结果而不是图片外观。a href/download/app img srcdownload-icon.png alt下载 App / /a这里写“下载 App”是对的告诉用户点击之后会下载 App。如果写成“蓝色箭头图标”对读屏用户没有任何用处。4.4 装饰图与空 alt如果图片只是为了视觉装饰没有信息价值应该使用空 altimg srcdecorative-line.png alt /注意这里的alt是刻意留空目的是让读屏软件跳过这张图片。很多新手会直接省略 alt 属性这两者是不同的。省略alt属性会导致某些读屏软件把图片文件名读出来反而造成干扰。所以在代码审查中装饰图必须明确写alt。4.5 上下文决定一切同一种图片在不同页面里可能出现不同 alt 文本。例如一张产品照片在产品列表页它可能需要 alt 写“白色无线耳机”因为用户通过文字和图片共同识别产品在产品详情页同一张照片的 alt 可以写“白色无线耳机侧面展示充电仓开合状态”因为这里的用户需要更多细节信息。这个例子可以直观说明alt 文本不是图片的静态标签而是图片和上下文之间的桥梁。自动化工具无法理解上下文差异这正是人工校验不可替代的原因。5. 实战案例从自动化通过到人工合格5.1 创建测试页面先准备一个包含图片的index.html!DOCTYPE html html langzh-CN head meta charsetUTF-8 / titleAlt 文本质量测试页/title /head body h12024 年门店运营报告/h1 section h2门店分布/h2 img srcstore-map.png alt地图 / /section section h2季度销售额/h2 img srcsales-trend.png alt销售趋势图 / /section section h2扫码下载 App/h2 a href/download img srcqrcode.png alt二维码 / /a /section section h2装饰元素/h2 img srcdivider.png alt分割线 / /section /body /html这个页面包含四种常见类型内容图、趋势图、功能性二维码、装饰分割线。自动化工具会怎么评判5.2 运行自动化检查如果你打开 DevTools 里的 Lighthouse会发现前三个图片的 alt 审计都能通过因为没有图片缺失 alt 属性。而第四个“分割线”图片它的 alt 写成了“分割线”审计也不会报错。用前面写的 axe-core 脚本执行node check-alt.js输出会提示“未发现明显图片 alt 问题”。从规则角度这个页面确实没有“明显问题”但真实用户体验呢5.3 人工审查结果如果我们是用户用读屏软件逐个听图片自动化结果实际可访问性问题级别门店地图通过只说“地图”用户完全不知道门店在哪高销售趋势图通过只说“销售趋势图”数据信息全部丢失高二维码通过“二维码”这个描述没有说明用途用户不知道扫码后是什么中分割线通过语义上属于装饰不应该出现在读屏列表中低经过人工评估后我们按合格标准修订img srcstore-map.png alt门店位置地图北京朝阳区望京 SOHO 塔 1 一层底商、上海静安区南京西路 1788 号一层。 / img srcsales-trend.png alt2024 年季度销售额折线图Q1 120 万、Q2 150 万、Q3 130 万、Q4 210 万整体呈上升趋势。 / a href/download img srcqrcode.png alt扫描二维码下载 App 客户端 / /a img srcdivider.png alt /同样的 DOM 结构自动化检查依然通过但信息完整性已经是完全不同的水平。这就是“能从自动化检查通过”和“真正合格”的本质区别。5.4 图表与复杂图片的进阶处理对于数据密集型的图表可以采取“双通道”策略视觉上展示图片文字上同时提供表格。这样既能保证常规用户看到图表读屏用户也能通过表格获得完整数据。h3季度销售额/h3 img srcsales-trend.png alt2024 年季度销售额折线图详细数据见下表 / table caption2024 年季度销售额/caption thead tr th scopecol季度/th th scopecol销售额万元/th /tr /thead tbody trtdQ1/tdtd120/td/tr trtdQ2/tdtd150/td/tr trtdQ3/tdtd130/td/tr trtdQ4/tdtd210/td/tr /tbody /table这种做法比把所有数据塞进 alt 文本更优雅也更符合 WCAG 的“内容等价”原则。原因在于读屏用户可以按表格逐行读取数据也可以快速跳转到表格之外的文字说明信息获取的灵活度更高。6. 常见问题与排查思路这一节汇总实际编写 alt 文本时最常见的问题问题现象常见原因解决思路自动化检查全部通过但盲人用户反馈无法理解页面空 alt 或过短 alt 过多对照图片逐张进行人工评审重点检查内容图alt 文本写了很长但用户觉得啰嗦把整张图片的视觉内容全部用文字复述提取核心信息详细数据放表格或正文同一张图片在多个页面重复出现alt 不统一没有建立内容审核机制在 CMS 或组件层集中维护 alt 字段图片加载失败时页面出现难看的空白图片虽然有 alt但 alt 为空确认图片是否为装饰图若是装饰图可留空否则补充描述装饰性图片加入了 alt导致读屏用户听到“图片”或文件名作者不知道怎么跳过装饰图使用alt并确保没有title/aria-label干扰动态渲染的图片 alt 还是默认占位符前端组件忽略了数据字段映射在渲染层输出真实 alt并在测试中校验 alt 非默认值用title属性替代alt对可访问性规范理解有误统一使用alt并移除多余的title除非需要额外提示排查时可以参考以下流程先跑一次自动化工具过滤掉明显缺 alt 的初级问题对通过检查的图片按页面上下文逐张人工评估把图片分成三类内容图、功能图、装饰图内容图检查信息完整性功能图检查操作说明装饰图确认是否留空用读屏软件抽测 3 到 5 个核心页面验证实际朗读效果。在团队协作中可以把这套流程固化到代码审查清单里而不是依赖某个人临时判断。7. 从自动化到人工建立可持续的 alt 文本质量保障机制7.1 自动化只能做第一道防线一个合格的前端项目自动化检查必须存在这是底线。它能快速发现“图片没有 alt 属性”这类基础问题也能在 CI 阶段阻止低水平遗漏合入主干。但这道防线的作用止步于此。更合理的定位是“自动化检查作为准入条件人工审核作为质量保障。”每个版本发布前由专门的角色抽检核心页面的 alt 文本质量。抽检比例不需要 100%但要覆盖最重要、流量最大的页面。7.2 建立组件层的 alt 规范在组件化开发中建议在组件定义时就约定清晰的 alt 字段使用方式// 文件路径components/ProductImage.jsx function ProductImage({ product, thumbnail false }) { const altText thumbnail ? ${product.name} : ${product.name}${product.color}${product.keyFeature}; return img src{product.imageUrl} alt{altText} loadinglazy /; }这里的核心思路是alt 文本不是由使用者随意填的而是由组件根据产品结构化数据自动生成避免人为遗漏或敷衍。当然自动生成的文本仍然需要人工审核至少保证命名规则符合信息等价原则。7.3 将 alt 文本纳入内容发布流程如果项目使用 CMS 管理内容建议在内容发布界面将 alt 字段设为必填项并设置最小长度提示。例如后台可以加一条 JS 校验// 文件路径admin/alt-validator.js function validateAlt(input) { const value input.value.trim(); if (!value) { alert(请填写图片替代文本); return false; } if (value.length 4) { alert(替代文本过短请补充能说明图片信息的描述); return false; } return true; }注意这个校验不能替代人工判断它只是最低阈值。但它能有效减少编辑或运营人员在发图文时随手填写“图”“1”“a”这类无效文本的情况。7.4 使用读屏软件做回归抽测人工审核最直接、最可靠的方式还是听一遍。免费的方案有 Windows 自带“讲述人”、macOS 自带 VoiceOver。抽测时不需要完整听完整个页面只需要重点听几个区域首屏的图片文章正文中的插图页头页脚的 logo 和图标按钮产品列表页的缩略图。听的时候关注一个问题如果看不到屏幕光靠这些朗读文本我能不能顺利理解页面结构和关键内容如果不能说明 alt 文本没有达到信息等价的目标。8. 最佳实践与工程建议8.1 针对图片编写者的规范建议写 alt 前先判断图片类型信息图、功能图、装饰图、文本图信息图的 alt 要描述信息和重点不要写“示意图”“照片”“图片”功能图的 alt 要描述操作目标例如“搜索”“提交”“关闭”装饰图一律alt文本图尽量少用如果必须用把图片中的文字完整放在 alt 里图片链接的 alt 描述跳转目标如“查看产品详情”同一页面中相同目标链接的 alt 文本保持一致图标按钮若同时有可见文字alt 可以为空避免重复朗读。8.2 针对前端工程师的落地建议在 UI 组件库中统一封装图片组件内置 alt 默认处理和校验提示在 ESLint 中接入jsx-a11y/alt-text插件在写代码阶段就暴露问题在 CI 中接入axe-core让自动化检查成为合并请求的门禁之一不要把自动化检查放在发布后应该在开发阶段就触发代码评审模板中加入“图片 alt 质量”检查项把它当作和代码逻辑同等重要的交付内容。8.3 针对测试工程师的验收建议测试用例中除了验证功能正确性还应该包含无障碍相关断言。例如// 文件路径tests/accessibility.spec.js const { expect } require(playwright/test); test(核心页面图片 alt 文本有效, async ({ page }) { await page.goto(/report); const images page.locator(img:not([alt])); const count await images.count(); for (let i 0; i count; i) { const altText await images.nth(i).getAttribute(alt); expect(altText.trim().length).toBeGreaterThan(4); expect(altText.trim()).not.toEqual(图片); expect(altText.trim()).not.toEqual(示意图); expect(altText.trim()).not.toEqual(二维码); } });这段脚本只是一个粗糙的“防呆”校验它能拦住“图片”“示意图”“二维码”这类毫无信息量的占位 alt但不能真正评估描述质量。测试工程师仍然需要人工浏览页面确认核心图片的描述是否准确。8.4 性能与 SEO 视角alt 文本对 SEO 也有一定影响搜索引擎通过它理解图片主题。但不要为了 SEO 堆砌关键词那会让读屏用户听到一大串无关词语体验非常糟糕。例如一张产品图alt 写成“2024 新款智能手表 运动手环 蓝牙通话 心率检测 防水手表 男 女”是典型的关键词堆砌。这种文本对 SEO 的作用越来越低但对辅助技术用户的干扰非常明显。正确的做法是使用自然语言描述产品本身例如“蓝色表盘的智能手表支持蓝牙通话和心率检测”。8.5 维护一份可复用的 alt 编写 checklist团队内部可以维护一份 checklist放在代码仓库根目录或协同文档中。建议包含以下要点图片加载失败时alt 是否能替代图片信息读屏用户是否能在不查看图片的情况下理解内容图片是否为装饰如果是是否已设置空 alt图片是否可点击alt 是否描述了操作目标图片中的文字是否在 alt 中体现是否能在保证有效描述的同时保持简洁每次新增图片或修改页面后对照 checklist 过一遍比依赖个人经验更稳定。9. 总结与下一步实践方向回到文章标题提出的问题你的 alt 文本能通过自动化检查不代表它真的合格。自动化检查是工具不是标准工具能发现“缺失”但很难评价“质量”。真正合格的 alt 文本必须建立在“信息等价”这个核心原则上。它需要写作者理解图片的语境、用户的场景和内容的优先级而这恰恰是长期被忽略的部分。读完这篇文章你应该已经掌握四件事一是明白 alt 自动化检查的规则边界二是能独立判断一张图片 alt 是否真正合格三是知道如何在项目流程中补充人工审查机制四是可以把 alt 文本质量纳入代码评审和测试验收。下一步建议你选择一个核心业务页面先用 Lighthouse 或 axe 做一次基础扫描再逐张人工评估图片 alt 文本把“自动化通过”和“人工合格”之间的差距记录下来。你会发现这个差距往往比预想的要大而每修复一个案例页面的真实可访问性就会提升一个台阶。如果这篇文章对你有帮助可以收藏备用后续做无障碍改造时直接对照操作。也欢迎在实践中遇到具体问题时再回来翻看排查表格结合你项目的实际场景调整策略。