Android Gradle Build System 基礎與依賴管理

Android Studio 使用 Gradle 作為自動化建置工具。Gradle 負責編譯程式碼、打包資源、處理依賴套件，最後生成可安裝的 APK 或 AAB (App Bundle) 檔案。

現代的 Android 專案使用 Kotlin DSL (.kts) 來撰寫 Gradle 腳本，相比舊版的 Groovy DSL，提供了更好的型別安全與 IDE 自動補全功能。

build.gradle.kts 核心概念

Plugins (外掛)

Gradle 本身是一個通用的建置工具，透過 Plugin 擴充功能來支援 Android 開發。

plugins {
    alias(libs.plugins.android.application) // 支援 Android App
    alias(libs.plugins.jetbrains.kotlin.android) // 支援 Kotlin
}

Android Block

android { ... } 區塊包含了所有 Android 相關的建置設定。

• compileSdk：編譯 App 時使用的 Android SDK 版本。建議總是使用最新的穩定版。
• minSdk：App 支援的最低 Android 版本。低於此版本的裝置無法安裝你的 App。
• targetSdk：App 針對哪個 Android 版本進行了測試與優化。這會影響執行時的行為（例如權限請求方式）。Google Play 要求此版本必須保持在最新範圍內。

Dependencies (依賴)

dependencies { ... } 區塊用來宣告專案需要的第三方函式庫。

Gradle 支援多種依賴類型：

• implementation：最常用的類型。該套件會被打包進 App 中，且不會暴露給依賴此模組的其他模組。
• api：類似 implementation，但會將依賴暴露給上層模組（在多模組開發時使用）。
• kapt / ksp：用於 Kotlin 的註解處理器（例如 Room, Dagger, Glide 需要生成程式碼）。KSP (Kotlin Symbol Processing) 是目前推薦的較快方案。
• testImplementation：僅在單元測試時使用。
• androidTestImplementation：僅在儀器測試（UI 測試）時使用。

如何加入第三方套件？

這是新手最常遇到的任務。假設我們想加入 Coil 圖片載入函式庫，步驟如下：

1. 找到 build.gradle.kts 檔案

Android 專案中通常有兩個 build.gradle.kts：

1. Project Level (MyApplication/build.gradle.kts)：管理全域設定，通常不需要動。
2. Module Level (MyApplication/app/build.gradle.kts)：管理 App 的依賴，我們要改的是這一個。

2. 加入 implementation 程式碼

打開 Module Level 的 build.gradle.kts，找到 dependencies 區塊，加入套件資訊：

dependencies {
    // ... 原有的依賴
    
    // 加入 Coil
    implementation("io.coil-kt:coil-compose:2.5.0")
}

3. Sync Now (同步專案) - 關鍵步驟！

只修改程式碼是不夠的，你必須讓 Gradle 下載並設定這些套件。 當你修改了 gradle 檔案，Android Studio 頂部會出現一個藍色橫條提示，或者你可以看到右上角有一個 "大象帶有藍色箭頭" 的圖示。

• 點擊 Sync Now (或大象圖示)。
• 等待底部進度條跑完。
• 如果沒有報錯 (Build Successful)，就代表套件安裝完成了！

如果 Sync 失敗，通常是因為：

1. 網路問題：Gradle 需要從網路下載套件 (Maven Central / Google Maven)。
2. 版本號錯誤：檢查套件版本是否存在。
3. 語法錯誤：檢查括號是否成對，引號是否正確。

Version Catalog (libs.versions.toml)

從 Android Studio Giraffe 開始，預設使用 Version Catalog 來管理版本。所有的版本號與套件名稱都定義在 gradle/libs.versions.toml 檔案中。

定義版本與套件 (libs.versions.toml)

[versions]
agp = "8.2.0"
kotlin = "1.9.0"
coreKtx = "1.10.1"
composeBom = "2023.08.00"

[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
androidx-ui = { group = "androidx.compose.ui", name = "ui" } # 版本由 BOM 管理

在 build.gradle.kts 中使用

dependencies {
    implementation(libs.androidx.core.ktx)
    
    // 使用 BOM (Bill of Materials) 管理版本
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.ui) // 不需要指定版本，跟隨 BOM
}

這樣做的好處是，當你要升級套件時，只需要在 .toml 檔案中修改一處，整個專案都會更新。

常見 Gradle 指令

雖然 Android Studio 提供了圖形介面，但在終端機或 CI/CD 流程中，我們常使用指令：

• ./gradlew assembleDebug：建置 Debug 版 APK。
• ./gradlew installDebug：建置並安裝到連接的裝置。
• ./gradlew check：執行所有檢查（Lint, Unit Test）。
• ./gradlew clean：清除建置快取（解決靈異問題時的第一招）。

依賴衝突解決

有時不同的函式庫會依賴同一個套件的不同版本，導致衝突。 你可以執行 ./gradlew app:dependencies 指令來查看完整的依賴樹，找出衝突的來源。一般來說，Gradle 會自動選擇較新的版本，但有時需要手動介入排除 (exclude)。

掌握 Gradle 基礎後，你就能自如地加入強大的第三方套件，為你的 App 增添更多功能。