Android Studio Layout 預覽失效：SDK 更新後無法渲染解決方案

問題現象

Android Studio 更新 SDK 後，Layout Editor 預覽顯示「Rendering Problems」、「Failed to instantiate one or more classes」或長時間轉圈無法渲染。Help → Check for Updates 提示已是最新版，但預覽功能不可用。

常見原因與對應解決方案

1. SDK Build Tools / Platform 版本不匹配（最常見）

AS 預覽依賴特定版本的 android.jar 與 layoutlib.jar。SDK 更新後，專案 compileSdkVersion 與安裝的 Platform 版本不一致會導致渲染失敗。

解決：

// build.gradle (Module: app)
android {
    compileSdkVersion 34  // 與 SDK Manager 安裝的 Platform 版本一致
    buildToolsVersion "34.0.0"  // 明確指定
}

SDK Manager → **SDK Platforms** 勾選對應 Android 版本（如 Android 14 / API 34）→ Apply。

2. Gradle Plugin / Android Gradle Plugin (AGP) 版本過舊

AGP 與 AS 版本強綁定。AS 更新後若未同步升級 AGP，預覽引擎不相容。

解決：

// build.gradle (Project)
dependencies {
    classpath 'com.android.tools.build:gradle:8.2.0'  // 對應 AS 版本
}

同步修改 gradle/wrapper/gradle-wrapper.properties：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip

3. 預覽渲染 API 級別選擇錯誤

Layout Editor 上方工具欄的 **Android 版本下拉框**（綠色機器人圖標旁）選擇的 API 級別，專案未安裝對應 Platform。

解決：切換至已安裝的 API 級別（如 API 34），或安裝該 API 級別 Platform。

4. Compose / Material3 依賴版本衝突

使用 Jetpack Compose 時，ui-tooling-preview、material3、compose-bom 版本必須嚴格對齊。

// 統一使用 BOM 管理版本
implementation platform('androidx.compose:compose-bom:2023.10.00')
implementation 'androidx.compose.ui:ui-tooling-preview'

5. 緩存損壞 / 索引錯誤

核彈級解決：File → Invalidate Caches / Restart → Invalidate and Restart

6. 佈局 XML 錯誤（自定義 View 未標註 @SuppressLint 等）

查看預覽面板下方 **「Rendering Problems」** 面板，點擊錯誤鏈接跳轉到 XML 行，修復具體問題（如缺少命名空間、自定義 View 構造函數參數不全）。

診斷步驟建議

1. 打開 **Logcat**，過濾 LayoutPreview、RenderTask 關鍵字，查看詳細異常堆疊
2. 嘗試 **Code → Inspect Code** 掃描專案潛在問題
3. 新建空專案測試預覽是否正常，排除 AS 全域配置問題
4. 檢查 idea.log（Help → Show Log in Files）尋找 ClassNotFoundException、NoSuchMethodError 等線索

避坑指南

• **不要**盲目點擊 SDK Manager 的「Update All」，建議僅更新 Platform、Build Tools、Emulator，保留穩定的 AGP/Gradle 版本
• 專案遷移至新 AS 版本時，參考 官方升級指南 同步升級 AGP/Gradle
• 使用 Version Catalog (TOML) 統一管理依賴版本，減少版本衝突

按順序執行：對齊 compileSdkVersion → 升級 AGP/Gradle → Invalidate Caches → 切換預覽 API 級別，90% 以上預覽失效問題可解決。