Android Gradle 外掛程式 DSL/API 遷移時程

Android Gradle 外掛程式 (AGP) 是 Android 應用程式支援的建構系統，可支援編譯多種不同來源，並連結至應用程式中，然後在實體 Android 裝置或模擬器上執行。

本節將說明 AGP DSL 和 API 的預計發展。隨著新的 API 在穩定版中推出，舊版 API 會標示為已淘汰。這些已淘汰的 API 會在下一個穩定版中停用。以下各節提供各個主要 AGP 版本即將推出的異動相關資訊。

如要進一步瞭解 AGP API 淘汰或移除的詳細記錄，請參閱「AGP API 更新」。

AGP 10.0 (2026 年底)

Android Gradle 外掛程式 10.0 API 變更和現代化

AGP 10.0 會完成轉換，改用完全延遲載入的建構模型，並與設定快取相容。我們投入多年心力，終於在這個版本中，以更安全、效能更高的架構，取代舊版非延遲 API。

為什麼要採用延遲建構模型？

在舊版非延遲建構模型中，Gradle 會在每次同步或建構呼叫期間，主動評估物件、查詢變數資料，並設定所有專案模組的工作。這種急切評估方式會浪費 CPU 時間和記憶體，用於未執行的變體和工作，並導致複雜建構指令碼的評估順序發生衝突。

使用延遲供應器 (Provider<T>) 和新版 Variant API (androidComponents {}) 轉換為完全延遲建構模型後，系統只會在主動建構執行圖表需要時，才延遲計算屬性和工作連線。

本次發布版本移除的舊版 API 與現代架構基本上不相容。移除這些外掛程式後，AGP 就能完全支援 Gradle 設定快取和專案隔離功能，大幅提升 Android Studio 的建構速度和同步處理時間。

核心架構差異

舊版 BaseVariant API (applicationVariants.all {}) 採用急切模式，且以工作為中心。這項功能可讓開發人員在設定階段直接存取 Gradle 工作和內部設定，但這會破壞現代 Gradle 的效能功能。

新的 Variant API (androidComponents {}) 是以構件為中心，且為延遲式。這個外掛程式會大量使用 Gradle 的 Property API，並完全移除對 Task 和 TaskProvider 的所有參照，因此您必須與輸入和輸出內容 (Variant.artifacts) 進行互動，而不是與基礎工作本身互動。

移除和取代的內容

先前在舊版 DSL 和舊版 Variant API 中使用的介面和類別都已刪除。如要準備建構指令碼和自訂外掛程式，請從下列生命週期終止的 API 和標記遷移：

已移除的 API 或功能 需要更換或採取行動
直接存取工作：
  • getJavaCompile()
  • getMergeResourcesProvider()
  • getAssembleProvider()
 構件 API：請使用 variant.artifacts 附加、修改或取代在工作之間傳遞的實際檔案 (構件)，而非擷取工作來變更其行為。
急切來源註冊：
  • registerJavaGeneratingTask()
  • registerResGeneratingTask()
 來源 API：使用 variant.sources.java.addGeneratedSourceDirectory(...) 連接自訂工作的輸出目錄。
類別路徑 / 設定存取權：
  • getCompileConfiguration()
  • getCompileClasspath()
 Instrumentation API：如要修改或檢查位元碼 (類別路徑存取權最常見的用途)，請使用 variant.instrumentation.transformClassesWith(...) AsmClassVisitorFactory。
急切屬性突變：
  • buildConfigField()
  • resValue()
 延遲 `MapProperty` 執行個體：使用 variant.buildConfigFields.put(...) 和 variant.manifestPlaceholders.put(...)。
停用旗標：
  • android.newDsl
  • android.builtInKotlin
 沒有直接替代方案。從 gradle.properties 移除這些標記；系統會嚴格執行新式 DSL 和內建 Kotlin。
舊版 Variant API 擴充功能：
  • applicationVariants
  • libraryVariants
  • testVariants
  • unitTestVariants
 以 androidComponents.onVariants() 取代。
變化版本篩選 (variantFilter 區塊) 以 androidComponents.beforeVariants() 取代，使用變體選取器。
SDK 和 NDK 元件：
  • sdkDirectory
  • ndkDirectory
  • bootClasspath
  • adbExecutable
 使用 androidComponents.sdkComponents 存取 SDK 元件。
測試環境：
  • deviceProvider
  • testServer
 將自訂測試裝置註冊作業遷移至 Gradle 管理的裝置。
過時的註冊 API：
  • registerArtifactType
  • registerBuildTypeSourceProvider
  • registerProductFlavorSourceProvider
  • registerJavaArtifact
  • registerMultiFlavorSourceProvider
  • wrapJavaSourceSet
 已刪除，但未直接更換。
轉換 API 以 Artifacts API 和 AsmClassVisitorFactory 取代轉換。

如要存取所有替代 DSL 和 Variant API (androidComponents {}) 介面和類別，請一律在開發自訂 Gradle 外掛程式或建構邏輯時使用 gradle-api 構件。

遷移步驟

為確保順利且可預測地升級至 AGP 10.0，請遵循下列遷移做法：

  1. 執行 AGP 升級小幫手：直接升級至 10.0 版前，請先在 Android Studio (Tools > AGP Upgrade Assistant) 中執行官方 AGP 升級小幫手。這個小幫手會自動執行多項常見的 DSL 和建構指令碼遷移作業，並協助保留現有的建構行為。
  2. 在 Android Studio 中使用 Agent Mode 技能：善用 AI 升級技能 (例如 Android 技能存放區提供的 AGP 升級技能)，在 Android Studio 中自動執行及簡化複雜建構邏輯和 DSL 的遷移作業。
  3. 先修正 AGP 9.x 中的淘汰警告：將專案升級至最新的 AGP 9.x 版本，並解決所有現有的淘汰警告。如果您的專案能順利使用 9.x 版，且不依賴 android.newDsl=false 或 android.builtInKotlin=false，就能輕鬆升級至 10.0 版。
  4. 稽核第三方 Gradle 外掛程式：確保第三方外掛程式已升級至與 AGP 10.0 相容的版本。如果外掛程式仍依賴舊版擴充功能類型，就會導致建構失敗，例如 ClassCastException: ... cannot be cast to class BaseExtension。
  5. 使用官方遷移配方：如需複雜的實際遷移範例和並列比較，請參閱官方 gradle-recipes GitHub 存放區。

以下是遷移前後的比較，說明如何從急切查詢舊版變數，改為使用 androidComponents {} 延遲設定變數：

舊版：舊版 Variant API (已在 AGP 10.0 中移除)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

之後：新版變體 API (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

如何在 AGP 9.x 中測試 AGP 10.0 行為

您不必等到 AGP 10.0 發布，即可開始測試其建構行為並驗證相容性。在任何 AGP 9.x 版本上執行時，您可以驗證 gradle.properties 是否停用任何停用選項，並設定下列嚴格的行為旗標，明確強制執行 AGP 10.0 行為：

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

強制執行 android.newDsl=true 和 android.builtInKotlin=true，即可確認自訂建構邏輯和第三方外掛程式完全符合 AGP 10.0 的嚴格 API 規定。

在遷移期間選擇不採用部分子專案

如要為專案android.newDsl=true全域啟用，測試新版行為，但需要更多時間遷移特定子專案，您可以從 AGP 9.4.0-alpha04 開始，選擇性停用個別模組。將 android.newDsl.optOut 新增至 gradle.properties，指定專案路徑：

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

針對每個模組選擇性停用內建 Kotlin

如要在專案 (android.builtInKotlin=true) 中全域啟用內建 Kotlin，但需要更多時間將特定子專案從 kotlin-android 遷移 (或針對沒有 Kotlin 程式碼的模組)，請在 DSL 層級而非專案層級設定這些模組。在模組的建構檔案中設定 enableKotlin = false：

android {
    enableKotlin = false
}

意見回饋和錯誤回報工作流程

我們想確保新的 Variant API 支援您所需的使用案例。如果無法順利從舊版 API 遷移，且新版 Variant API 無法滿足您的用途，請按照下列步驟提供意見：

  1. 檢查現有項目：首先，請查看 AGP 10.0 Variant API Global Tracking Bug，確認您的遷移阻礙是否為已知問題，並為該問題 +1。
  2. 回報缺少的 API：如果您的用途較為特殊，請使用我們的特定變體 API 範本提出新功能要求，我們會進行調查並提供協助。

(暫定) 私人內部 AGP 類別的存取權已移除

現在依附於 gradle 成果已無法取用所有內部類別，且只能取得 gradle-api 成果中可用介面和類別的編譯存取權。這會影響外掛程式編譯。

您無法手動新增依附元件來取得內部類別的存取權。

AGP 9.0 (2026 年 1 月)

新的 Variant API 是穩定版，舊版 API 已淘汰

在 4.1 和 4.2 中發展的 Variant API 是穩定版，位於 gradle-api 構件中。先前在舊版 Variant API 中使用的介面和類別現已淘汰，如要使用，必須明確選擇加入。

新版 DSL 介面是穩定版，舊介面已淘汰

在 4.1、4.2 和 7.0 中發展的 DSL 介面現已是穩定版，位於 gradle-api 構件中。先前在 DSL 中使用的介面和類別現已淘汰，如要使用，必須明確選擇加入。

仍可存取私人內部 AGP 類別

即使是在其他構件中的 AGP 私人內部類別，在建構檔案和外掛程式編譯期間仍可存取，但我們不建議使用，因為這些類別可能隨時發生破壞性改變。