React Console Warning：images jsx-a11y/alt-text 警告原因、解決方法與 img alt 設定規範

在現代前端工程實務中，當我們使用 React 開發介面並執行編譯或進行程式碼檢查時，常會於終端機或開發者工具的 Console 中看到這道 jsx-a11y/alt-text 警告訊息：img elements must have an alt prop, either with meaningful text, or an empty string for decorative images jsx-a11y/alt-text。這項檢查是由 eslint-plugin-jsx-a11y 靜態分析工具所觸發，用來提醒開發者為 <img> 元素補上 alt 替代文字屬性。

問題原因與快速解法

1. 為什麼會觸發這個警告？（問題原因）

當專案中的 JSX 程式碼直接撰寫 <img> 標籤，卻完全沒有宣告 alt 屬性時，就會觸發 images jsx-a11y/alt-text 警告：

// ❌ 觸發警告的原始寫法（缺少 alt 屬性）
<img src={ImageUrl} />

2. 如何立即消除警告？（兩種解法）

依照這張圖片在畫面中的「實際用途」，有兩種對應的解法：

• 解法 A：具備實質內容的圖片（填入具體描述文字）
  如果這張圖片與網頁主題直接相關（例如商品圖、文章插圖、資訊圖表），請直接補上 alt 並寫入圖片描述：

// ✅ 解法 A：有意義的內容圖片，填入具體描述
<img src={ImageUrl} alt="圖片描述" />

• 解法 B：純裝飾性圖示或背景 Icon（填入空字串 alt=""）
  如果這張圖片只是純視覺點綴（例如按鈕旁的愛心 Icon、裝飾線條、背景小圖示），與網站核心文案無關，請加上 alt="" 空字串（切勿省略 alt，也不要亂填 icon-favorite 等無意義英文字）：

// ✅ 解法 B：純裝飾用的 Icon，保留 alt="" 空字串即可通過檢查且不汙染 SEO
<img className="icon" src="img/favorite.svg" alt="" />

---

1. 靜態分析背景與語意分級架構

1.1 靜態分析標準寫法與 3 大工程瓶頸

eslint-plugin-jsx-a11y 是前端團隊在建置管線（Pipeline）中常用的一套 ESLint 外掛，透過抽象語法樹（AST）靜態分析 JSX 語法結構。當編譯器掃描到 <img> 標籤卻未檢驗到對應的屬性時，便會強制中斷或發出警告。在實際大型專案開發中，常見的工程瓶頸包含：

1. 視覺裝飾圖標誤植語意文字：將介面純裝飾用的 Icon 或背景圖填入冗長的說明，導致輔助科技（如螢幕閱讀器）覆誦無意義字串。
2. SEO 索引雜訊汙染：裝飾性質的圖片被賦予不當的關鍵字，造成搜尋引擎爬蟲（Crawler）抓取到錯誤的圖片替代文字，降低頁面內容品質分數。
3. 動態圖片載入狀態遺漏：從遠端 API 取得圖片網址時，開發者常忽略預設的 alt 屬性捕捉，導致非同步渲染時觸發驗證警告。

1.2 alt 屬性語意分級與對照表

根據 WCAG 規範，alt 屬性依據圖片在介面中的功能與視覺傳達性質，可劃分出不同的填寫策略與對照機制：

圖片類型分類	屬性規範格式	適用情境與輔助科技行為	搜尋引擎優化（SEO）影響
具體內容圖	alt="詳細描述文字"	資訊圖表、文章插圖；螢幕閱讀器會完整朗讀該段文字。	提升圖片搜尋（Image Search）命中率，強化頁面語意關聯。
裝飾圖標	alt=""	純視覺點綴、UI Icon、無意義分隔線；螢幕閱讀器會自動略過。	避免搜尋引擎將裝飾性質圖標誤認為核心內容。
複合互動圖	alt="功能行為描述"	結合按鈕或連結功能的圖標（如加入最愛按鈕）；朗讀其實際互動目的。	幫助爬蟲理解該區塊的互動意圖與導航結構。

---

2. alt 使用注意事項：為什麼裝飾圖不該亂填文字？

圖片的 alt 屬性雖然主要功能是放置圖片描述，但有一個重要前提：如果你的圖片不具備實質內容意義（比方說只是 Icon、背景或純視覺點綴），請務必保持 alt="" 空字串，不要填寫任何文字。

舉例來說，畫面中有一個「加入追蹤」的功能，呈現上使用了一顆愛心 Icon：

// 原始未加 alt 的寫法
<img className="icon" src="img/favorite.svg" />

常見錯誤範例：填入無意義的檔案或元件名稱

許多開發者為了讓 Console 警告消失，會順手為不具意義的裝飾圖片填上檔名或 Class 名稱：

// ❌ 錯誤示範：為純裝飾 Icon 填入無意義的系統字串
<img className="icon" src="img/favorite.svg" alt="icon-favorte" />

這類做法雖然在語法檢查上不會報錯，但實際上會嚴重影響搜尋引擎（Google）呈現的網站摘要內容，因為搜尋引擎爬蟲會將 alt 文字視為網頁正文的一部分。

當使用者在 Google 搜尋你的網站時，搜尋結果頁面的摘要（Snippet）很可能會把這些圖片的 alt 抓出來拼湊在開頭。如果網站左上角 Logo 的 alt 寫成 logo-image，加上愛心圖示寫成 icon-favorte，使用者在 Google 搜尋結果看到的網站描述就會變成：

[logo-image icon-favorte 網站說明...]

因此，填寫 alt 內容前請先評估圖片的語意角色，純裝飾圖示一律使用空字串：

// ✅ 建議使用方式：裝飾性圖標保持空字串
<img className="icon" src="img/favorite.svg" alt="" />

---

3. 生產環境完整程式碼範本

範本一：具備內容語意與 SEO 優化的圖片元件實作

import React from 'react';

export function ContentImage({ imageUrl, caption, isDecorative }) {
  // 若為裝飾圖標，強制回傳空字串以符合無障礙與 SEO 規範
  if (isDecorative) {
    return <img src={imageUrl} alt="" className="decorative-icon" />;
  }

  return (
    <figure>
      <img src={imageUrl} alt={caption} className="content-img" />
      <figcaption>{caption}</figcaption>
    </figure>
  );
}

範本二：結合按鈕互動與狀態切換的圖標元件實作

import React from 'react';

export function ActionIconButton({ isFavorite, onToggle }) {
  const altText = isFavorite ? '從追蹤清單移除' : '加入追蹤清單';

  return (
    <button type="button" onClick={onToggle} className="icon-btn">
      <img 
        src={isFavorite ? 'img/favorite-active.svg' : 'img/favorite.svg'} 
        alt={altText} 
      />
    </button>
  );
}

---

4. 開發者高頻 Q&A 彙整

Q1：為什麼一定要在 HTML img 中強制加入 alt 屬性？

• 問題原因：當視障使用者使用螢幕閱讀器瀏覽網站時，若圖片缺少 alt 屬性，閱讀器往往會直接朗讀圖片檔案名稱（例如 image01.png），嚴重干擾資訊接收。
• 解法：基於全球網頁無障礙標準（WCAG），所有 <img> 標籤皆須明確定義 alt 屬性；eslint-plugin-jsx-a11y 即是透過在編譯階段強制檢查此屬性來把關無障礙與 SEO 品質。

Q2：如果圖片只是背景裝飾，alt 屬性可以直接省略不寫嗎？

• 問題原因：如果完全不寫 alt 屬性，eslint-plugin-jsx-a11y 仍然會判定為遺漏屬性而拋出警告，且螢幕閱讀器無法判斷該圖片是否應被略過。
• 解法：對於裝飾性圖片，應明確寫出空字串 alt=""，藉此告知輔助科技與搜尋引擎爬蟲該圖片可被安全略過。

Q3：為什麼不具備意義的圖標不應該隨便填寫英文字串如 icon-logo？

• 問題原因：搜尋引擎爬蟲會將 alt 內容視為網頁文本的一部分。若填入無意義的系統名稱，不僅無法幫助 SEO，還可能在搜尋結果頁面的摘要中出現奇怪的碎片文字（例如 [logo-image icon-favorite 網站說明...]）。
• 解法：非內容圖片統一填寫 alt=""；若為純視覺 Icon，亦可評估改用 CSS 背景圖或加上 aria-hidden="true" 的內聯 SVG。

Q4：如何在 ESLint 設定中調整或關閉這項檢查？

• 問題原因：部分舊專案在遷移時可能因歷史圖片數量龐大而出現大量警告。
• 解法：雖然可以在 .eslintrc.js 的 rules 中設定 "jsx-a11y/alt-text": "off" 暫時關閉，但從軟體工程與 SEO 長遠維護來看，建議維持開啟並依語意分批補齊 alt="" 或具體描述。

Q5：網站中的 Logo 圖片該如何撰寫適當的 alt 內容？

• 問題原因：許多開發者習慣將網站左上角 Logo 的替代文字寫成生硬的 alt="logo" 或 alt="logo-image"，浪費了首頁最重要的品牌權重位置。
• 解法：網站左上角的 Logo 通常具有導航回首頁的功能，其 alt 屬性應直接填寫網站的品牌名稱或核心定位（例如 alt="Sean 技術專欄首頁"），同時兼顧無障礙導覽與品牌 SEO。

參考資料與延伸閱讀

• 維基百科：搜尋引擎最佳化 (SEO) 運作原理與關鍵字策略
• 維基百科：靜態程式碼分析 (Static Program Analysis) 軟體工程技術
• 維基百科：替代文字 (Alt attribute) 在資訊傳播與人機介面中的角色
• 延伸閱讀：基於靜態分析與 WCAG 規範之 JSX-A11y Alt 屬性語意分級及搜尋引擎最佳化研究
• 延伸閱讀：Support for defaultProps will be removed from function components in a future major release. Use JavaScript default parameters instead 原因與解決方法