使用 IDE Android Studio 的程式設計師在編譯程式碼或在 Android 裝置 (真機或模擬器) 上執行時 會遇到 Gradle Project Sync Failed 錯誤訊息 Gradle Sync 是 Gradle 任務 主要功能是檢查 build.gradle 檔案中與 Android Studio 專案相關的所有依賴項 並下載指定版本 (若尚未下載)
此錯誤訊息有許多變體 您可能面臨簡單的網路連線問題 到 Gradle 編譯無法運作的複雜問題 本文將探討此問題發生的所有原因 然後說明解決方案
導致 Android Studio「Gradle Project Sync Failed」錯誤訊息的原因
如前所述 有多種原因導致 Gradle 專案無法編譯或同步 以下是部分原因 (每個可能不適用您):
- 網路連線不良: Gradle 需下載電腦缺少的所有執行專案所需版本 若無有效網路連線可能失敗
- Gradle 編譯器問題: 可能 Gradle 編譯器無法正常運作 此處可嘗試手動載入 Gradle 看是否解決
- Android Studio 快取損壞: Android Studio 使用電腦快取以正常運作 某些情況下快取損毀導致多模組問題 (包含 Gradle)
- 遺失檔案: 可能缺少執行 Gradle 所需檔案 安裝即可即時解決
- Proxy 伺服器: 雖然 Proxy 伺服器日益普及 但我們發現某些情況 Gradle 在其上無法正常同步 停用 Proxy 伺服器可解決問題
開始解決方案前 請確保目前專案已備份 儲存檔案並另存副本以防萬一 同時確保以管理員身分登入電腦
解決 方案 1: 檢查網路連線
Gradle 要求電腦有運作中的網路連線 因其主要工作是從網路下載電腦缺少的所有執行專案所需版本 必須有適當網路連線 您也可嘗試連接其他裝置至同一網路確認連線 確定非此問題後 可進行其他解決方案
解決 方案 2: 停用 Proxy 伺服器
Proxy 伺服器日益普遍 用於組織和機構提升當前頻寬 為所有用戶提供更好網路存取 然而 Proxy 伺服器有其限制 其中包括同步模組無法按需運作 包含 Gradle 以下是確保未使用 Proxy 伺服器的方法
- 按 Windows + R 輸入 inetcpl.cpl 並按 Enter
- 開啟 Internet Properties 點擊 Connections 標籤然後 LAN settings
- 若使用 Proxy 伺服器 欄位將勾選並填入詳細資料 取消勾選 任何啟用的 Proxy 伺服器 現在重新啟動 Android Studio 檢查問題是否解決
解決 方案 3: 安裝遺失元件
在深入技術方法前 應檢查是否缺少同步 Gradle 所需的必要模組 Gradle 本身非獨立 也需要其他服務正常運作
現在 每當嘗試同步 Gradle 出現錯誤訊息 檢查問題標題下是否有 超連結 Install missing platform(s) and sync project 點擊連結後 Android Studio 將開始下載並安裝所有缺少項目 現在嘗試同步專案 查看是否解決問題
解決 方案 4: 使用本地 Gradle 發佈版
每當建置專案啟動 Gradle 時 會連線到最新線上發佈版 從該處下載所有所需模組或版本 我們發現幾個案例 線上發佈版未如預期運作 導致 Gradle 同步失敗 另一替代方案是手動下載 Gradle 發佈版並使用 遵循以下步驟:
- 從官方 Gradle Release 網站下載最新版 Gradle
- 下載後 將所有檔案解壓縮至可存取資料夾
- 啟動 Android Studio 前往 File > Settings > Build, Execution, Deployment > Gradle
- 選擇 Local Gradle Distribution 選項 在 Gradle home 指向剛解壓縮檔案的路徑
注意: 若在 Global Gradle Settings 使用 offline work 請 取消勾選 該選項
- 現在嘗試建置專案 檢查 Gradle 是否正常同步 每次建立新專案需重複此步驟
解決 方案 5: 啟用 GPU Debugger
GPU Debugger 可讓您偵錯和分析 OpenGL ES 應用程式 具有多種功能 讓您檢查 GPU 狀態並理解導致渲染結果的原因 某些 Gradle 建置實例中 系統有 Bug 導致此功能未啟用 此解決方案我們將強制模組重新整理並安裝此元件
- 點擊 Tools 選擇 Android > SDK Manager
- 點擊 SDK Tools 標籤 取消勾選 Android SDK Build-Tools 等待約 5 秒後重新啟用
- 等待片刻直到列表重新整理並填入項目
- 新項目填入後 查看列表 勾選 GPU Debugging Tools 完成後按 OK
現在 這些工具將下載至 Android Studio 應用程式 您將能正常同步 Gradle 無任何問題
解決 方案 6: 重新整理快取
包括 Microsoft Windows 在內的每個應用程式到處都有快取 幫助應用程式順利運作無問題 它們作為暫存儲存空間 應用程式儲存偏好或暫存資料稍後提取 我們確定此快取若損毀 將中止 gradle 建置過程 此解決方案我們將重新整理整個快取 刪除現有 Gradle 檔案後 重新啟動 Android Studio 查看是否修復問題
- 導航至 File 點擊 Invalidate cache/Restart
- 程序完成後 完全關閉 Android Studio
- 導航至 Android Studio 安裝目錄中的 .gradle 資料夾 現在可剪下/貼上至其他位置或直接重新命名
現在 Android Studio 嘗試存取 Gradle 檔案時 將發現無檔案並嘗試再次下載整個內容 - 重新啟動 Android Studio 再次嘗試 Gradle sync 現在檢查問題是否解決
