Android R 檔案未生成圖片資源 ID：常見原因與修復清單

現象

• 專案編譯無誤，但 R.drawable.xxx 找不到特定圖片資源 ID。
• 手動在 R.java 加入常數，執行後又消失 (R.java 為自動生成，不可手改)。

核心原因排查 (由淺入深)

1. 檔案命名不合法： 資源檔名僅允許 [a-z0-9_.]，不可含大寫、空格、中文、特殊符號。如 myImage@2x.png、icon 大.png 會導致 aapt 忽略。
2. 放錯目錄： 圖片必須置於 res/drawable-* (或 mipmap-*) 下，直接放在 res/ 或 assets/ 不會生成 ID。
3. 檔案損毀或格式不支援： 0 bytes、非標準 PNG/JPG/WebP、色彩空間異常 (如 CMYK) 會導致 aapt 解析失敗並靜默跳過。
4. Gradle / aapt2 快取殘留： 執行 ./gradlew clean 或 Build > Clean Project，再 Rebuild。
5. 資源合併衝突： 多模組/庫專案同名資源，優先級導致預期資源被覆蓋。檢查 build/outputs/logs/manifest-merger-*-report.txt。
6. Android Gradle Plugin (AGP) 版本 Bug： 升級/降級 AGP 至穩定版 (如 8.1.x)。

1. 檢查檔名：全小寫、底線、數字、點。
2. 確認路徑：res/drawable-xxx/ 或 res/mipmap-xxx/
3. 執行 Clean + Rebuild。
4. Invalid Caches / Restart (Android Studio / IntelliJ)。
5. 刪除 .gradle、build 目錄後重新同步。
6. 檢查 Build Output 視窗的 aapt 錯誤訊息 (通常會提示具體檔案)。