Android Studio 新建項目報錯：SDK 路徑配置錯誤的排查與修復

新手安裝 Android Studio 後新建項目報錯，SDK Manager 顯示已安裝但項目識別不到，常見原因是未正確設置 SDK 路徑或缺少平台工具。

典型報錯現象

• 「SDK location not found」
• 「Missing platform-tools」
• Gradle Sync 失敗：Failed to find target with hash string 'android-XX'
• SDK Manager 顯示已安裝，但 local.properties 里 sdk.dir 為空或錯誤

核心修復步驟

1. 設置正確的 SDK 路徑（最關鍵）

File → Settings → Appearance & Behavior → System Settings → Android SDK

• 「Android SDK Location」必須指向 SDK 根目錄（包含 platforms/、build-tools/、platform-tools/ 子目錄）
• 常見路徑：
  Windows: C:\Users\用戶名\AppData\Local\Android\Sdk
  macOS: /Users/用戶名/Library/Android/sdk
  Linux: /home/用戶名/Android/Sdk
• 點 Apply → OK，AS 會自動掃描並識別已安裝平台

2. 確認必要組件已安裝

在同一 SDK 設置頁面，勾選並安裝：

• SDK Platforms：至少一個 Android 版本（如 Android 14 / API 34）
• SDK Tools 籤：
  ✅ Android SDK Build-Tools (最新版)
  ✅ Android SDK Platform-Tools
  ✅ Android SDK Command-line Tools
  ✅ Android Emulator (如需模擬器)
  ✅ Google Play Services (如需地圖/推送)

3. 檢查項目級 local.properties

項目根目錄下 local.properties 必須包含：

sdk.dir=C\:\\Users\\用戶名\\AppData\\Local\\Android\\Sdk
# Windows 路徑冒號需轉義，或用正斜杠
sdk.dir=/Users/用戶名/Library/Android/sdk

若缺失或錯誤，手動修改並重新 Sync Project。

4. JDK 配置驗證

• File → Project Structure → SDK Location → JDK location
• 推薦使用 JDK 17 (Android Gradle Plugin 8.0+ 必須) 或 JDK 11 (AGP 7.x)
• 環境變量 JAVA_HOME 指向 JDK 根目錄（非 bin 目錄）

5. 代理/網絡設置（中國大陸必做）

# gradle.properties (全局或項目級)
systemProp.http.proxyHost=127.0.0.1
systemProp.http.proxyPort=7890
systemProp.https.proxyHost=127.0.0.1
systemProp.https.proxyPort=7890
# 或設置鏡像源
# File → Settings → Build Tools → Gradle → Android Studio → Maven Repository → 阿里云/騰訊云鏡像

常見坑點總結

按順序檢查：SDK 路徑 → 組件完整性 → local.properties → JDK → 代理，99% 問題迎刃而解。