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