devgo.cn想象一下，你给网页上的图片都写好了 alt 文本（替代文本，屏幕阅读器用户听到的图片描述），自动化检查全部通过，绿色对勾。但屏幕阅读器用户实际听到的可能是“image”、一个文件名，或者连续五遍“3/5 stars”。这正是 2026 年 WebAIM Million 报告揭示的问题：在排名前一百万的主页中，16.2% 的图片完全没有 alt 文本，另外 10.8% 虽然有，但内容毫无信息量。自动化工具擅长发现“缺失”，却很难判断“质量”。
为什么难？因为“存在”是客观事实，属性在不在那里一目了然；而“质量”是主观判断，机器无法仅凭标记证明一句话是否充分描述了图片。但并非所有质量问题都是主观的。GitHub 团队在构建 alt 文本插件时，划了一条线：只检查那些能仅凭字符串本身证明的错误。他们用 Playwright（浏览器自动化测试工具）的 role-based locator 扫描页面，只处理进入无障碍树的图片，空 alt 被排除在外——那是作者明确声明图片是装饰性的，标记它反而会惩罚正确行为。然后实现了五个默认开启的确定性规则：属性缺失或纯空白；alt 是文件名（如 IMG_2847.jpg）；是占位符（如 TODO）；是泛泛的媒介词（如 image、logo、chart）；相邻图片重复使用同一 alt。这些规则不需要调用 AI 模型或网络请求。
这里的关键设计原则是宁缺毋滥。一个质量检查器靠误报率存活。如果规则太聪明，把“image of the login screen with the SSO button highlighted”也当成泛词，团队就会关掉它。所以规则采用闭集匹配，只对精确匹配的泛词报警。这当然会漏掉很多糟糕的 alt，但一个可靠的、开发者愿意开启的检查器，胜过被关掉的完美主义者。
最有趣的是重复 alt 的检测。最初版本按文档顺序遍历图片，把连续相同 alt 的片段标记出来。结果误报频出：页脚的“GitHub” logo 和页眉的“GitHub” logo 在 DOM（文档对象模型，网页的结构表示）顺序上可能相邻，但在屏幕上相隔甚远，用户根本不会把它们当成一组。问题不在 DOM，而在布局。于是规则改为检查页面布局，只有当两个图片的边界框之间的间隙相对于图片尺寸足够小时，才认为它们是连续的。这里有个细节：间隙乘数是一个经验值，不是从规范推导出来的，需要针对真实页面调参。当图片没有可测量的边界框时，检查会“失败开放”，即继续延长连续片段，因为漏报不可见，误报却很明显。
确定性规则只能处理字符串层面的问题。要判断“a smiling person”是否足够，必须知道页面上下文。GitHub 的可选质量检查会提取图片周围的上下文：最近的标题、页面标题、figcaption（图片说明文字）、图片是否在链接内，以及最多 600 字符的邻近文本。其中链接信号最重要：当图片是链接的唯一内容时，alt 就变成了链接的可访问名称，此时正确的 alt 应该描述目标地址而不是图片本身。不过插件目前只记录图片在链接内，不检查它是否是唯一内容，所以两种情况对模型来说是一样的。
这些上下文、alt 和图片一起通过 GitHub Models 发送给一个视觉模型（能理解图像内容的 AI 模型）。团队发现，模型的失败模式很少是看错图片，而是“有主见”。面对完全合格的 alt，模型也会建议修改，因为“还能更好吗？”这个问题语言模型总是回答“能”。于是每个图片都变成一个问题，信号就消失了。三个改动解决了这个问题：一是把提示词改成决策程序，按四个有序步骤走，匹配到哪步就输出哪步的结论（装饰性、与说明文字冗余、功能性、信息性）；二是加入明确的“反吹毛求疵”规则，信任作者的框架，区分“Image of”这种冗余前缀和“Photograph of”这种语义前缀，当周围文字已经分析了图片时，短 alt 也算正确；三是用结构化输出强制字段顺序，让模型先推理后下结论，逼它先构建论证再选标签。这些并不能让模型永远正确，但能让它足够一致，便于迭代。
仓库里还带了一个离线评分工具，基于 WebAIM、W3C 图片教程和 POET 这些公开教学材料构建。规则和评分工具共享同一个提示词，所以离线调优的结果就是 CI（持续集成，自动化测试流程）里实际运行的结果。不过这个评分工具只测试模型的判断，不测试整个流程。一个案例在评分里满分，不代表真实扫描中能到达模型。
最后是隐私和成本。一旦检查调用外部模型并发送网页数据，它就不再只是 lint 规则，需要仔细设计数据流。所以这个规则默认关闭，必须主动启用。
这个案例对任何做自动化检查的人都有启发。可证明的错误和可疑的质量之间有一条清晰的线，越线需要付出代价。布局问题提醒我们，用户感知的是屏幕上的位置，不是 DOM 顺序。而模型参与判断时，必须用决策程序和结构化输出约束它，否则它只会成为一个永远挑刺的批评家。这套思路可以迁移到其他需要“质量判断”的检查场景，比如文档标题、代码注释、UI 文案——先用确定性规则扫掉客观错误，再用模型处理需要上下文的判断，同时用离线测试集持续校准。
内容与图片版权归原作者所有 · 原文: https://github.blog/engineering/user-experience/your-alt-text-passes-automated-checks-that-doesnt-mean-its-any-good/