
本文详解 `jsx-a11y/img-redundant-alt` 报错原因及解决方案,重点说明为何在 `alt` 中使用 “image”“photo”“picture” 等冗余词违反可访问性原则,并提供 react 中 svg 与 img 的合规写法。
在构建符合 WCAG 和无障碍标准(a11y)的 React 应用时,eslint-plugin-jsx-a11y 插件中的 img-redundant-alt 规则常被触发。该规则的核心逻辑是:屏幕阅读器(如 NVDA、VoiceOver)默认将 元素识别为“图像”,因此 alt 文本中再重复出现 “image”、“photo” 或 “picture” 等词不仅无意义,反而降低信息传达效率,属于冗余描述。
✅ 正确做法:用功能或内容替代类型词
alt 的本质是为无法看到图像的用户(如视障者、加载失败场景)提供等效的内容描述,应聚焦于“它是什么”或“它做什么”,而非“它是什么类型的元素”。
❌ 错误示例(触发警告)
@@##@@ @@##@@
⚠️ image 和 photo 属于规则默认禁止的冗余词(默认配置:["image", "picture", "photo"])。
✅ 正确示例(语义清晰、简洁有效)
@@##@@ @@##@@
✅ 描述具体对象/功能,不含类型标签,同时具备上下文信息(如时间范围、数值)。
⚠️ 特别注意:SVG 图标通常无需 alt
你提供的代码片段是一个装饰性 SVG(带 aria-hidden="true"),它根本不应使用 alt 属性——因为:
- aria-hidden="true" 已明确告知辅助技术忽略该元素;
- 若 SVG 是纯装饰(如图标、分隔线),应保持无文本描述;若具功能性(如按钮图标),需通过 aria-label 或 aria-labelledby 提供语义。
✅ 功能性 SVG 正确写法(带可访问性)
? 进阶:自定义规则(不推荐,仅作了解)
如团队有特殊命名规范(例如统一要求含 “icon”),可覆盖默认配置(eslint-config-airbnb 等主流配置中已禁用此规则,建议优先遵循标准):
// .eslintrc.json
{
"rules": {
"jsx-a11y/img-redundant-alt": ["error", { "components": ["Image"], "words": ["icon"] }]
}
}但请注意:添加新关键词需确保其真正提升可访问性,而非妥协标准。
✅ 总结检查清单
- [ ]
的 alt 文本是否完全避免 “image”/“photo”/“picture”? - [ ] 装饰性 SVG 是否移除了非法 alt 并设 aria-hidden="true"?
- [ ] 功能性 SVG 是否包裹在语义化容器(如
- [ ] 所有图像描述是否满足「盲人能据此理解内容」这一黄金标准?
遵循以上实践,即可彻底消除 Redundant alt attribute 警告,同时显著提升应用的包容性与专业度。











