新增建構依附元件

Android Studio 中的 Gradle 建構系統可讓您將外部二進位檔或其他程式庫模組當做依附元件，加入建構作業中。依附元件可存放在本機或遠端存放區，且依附元件宣告的遞移依附元件也會自動加入。本頁面說明如何在 Android 專案中使用依附元件，包括 Android Gradle 外掛程式 (AGP) 特有的行為和設定詳細資料。如需 Gradle 依附元件的相關概念指南，請一併參閱 Gradle 依附元件管理指南。提醒您，Android 專案只能使用本頁中定義的「依附元件設定」。

新增程式庫或外掛程式依附元件

新增及管理建構依附元件的最佳方式是使用版本目錄，而新專案預設會使用的方法。本節說明 Android 專案最常見的設定類型；如需更多選項，請參閱 Gradle 說明文件。如需使用版本目錄的應用程式範例，請參閱「Now in Android」。如果您已設定建構依附元件，但沒有版本目錄，且擁有多模組專案，建議您遷移。

如要瞭解如何新增及管理原生依附元件 (常見做法)，請參閱「原生依附元件」。

在以下範例中，我們在專案中加入遠端二進位檔依附元件 (Jetpack Macrobenchmark 程式庫)、本機程式庫模組依附元件 (myLibrary)，以及外掛程式依附元件 (Android Gradle 外掛程式)。以下是將這些依附元件新增至專案的一般步驟：

  1. 在版本目錄檔案的 [versions] 區段中，為所需的依附元件版本新增別名，其名稱為 libs.versions.toml (在「Project」檢視畫面的 gradle 目錄下，或「Android」檢視畫面中的「Gradle Scripts」)：

    [versions]
agp = "8.3.0"
androidx-macro-benchmark = "1.2.2"
my-library = "1.4"

[libraries]
...

[plugins]
...

    別名可包含破折號或底線。這些別名會產生巢狀值，您可以在建構指令碼中參照這些值。參照項目開頭為目錄名稱，也就是 libs.versions.toml 的 libs 部分。使用單一版本目錄時，建議保留預設值「libs」。

  2. 在 libs.versions.toml 檔案的 [libraries] (用於遠端二進位檔或本機程式庫模組) 或 [plugins] (用於外掛程式) 區段中，新增依附元件的別名。

    [versions]
...

[libraries]
androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }

[plugins]
androidApplication = { id = "com.android.application", version.ref = "agp" }

    部分程式庫可在已發布的物料清單 (BOM) 中使用，該清單會將程式庫組合和版本分組。您可以在版本目錄和建構檔案中加入 BOM，讓它為您管理這些版本。詳情請參閱「使用物料清單」。

  3. 在需要依附元件的模組中，將依附元件別名的參照新增至建構指令碼。從建構指令碼參照別名時，請將底線和破折號轉換為點。模組層級建構指令碼如下所示：

    Kotlin

    plugins {
  alias(libs.plugins.androidApplication)
}

dependencies {
  implementation(libs.androidx.benchmark.macro)
  implementation(libs.my.library)
}

    Groovy

    plugins {
  alias 'libs.plugins.androidApplication'
}

dependencies {
  implementation libs.androidx.benchmark.macro
  implementation libs.my.library
}

    外掛程式參照會在目錄名稱後方加上 plugins，版本參照則會在目錄名稱後方加上 versions (版本參照很少見，請參閱「同樣版本號碼的依附元件」中的範例)。程式庫參照並未包含 libraries 限定詞，因此您無法在程式庫別名的開頭使用 versions 或 plugins。

設定依附元件

在 dependencies 區塊內，您可以使用多種不同的依附元件設定 (例如先前顯示的 implementation) 來宣告程式庫依附元件。每項依附元件設定都會為 Gradle 提供不同的依附元件使用方式說明。下表說明可在 Android 專案中用於依附元件的各項設定。

設定 行為
implementation Gradle 將依附元件新增至編譯的類別路徑，並將依附元件封裝到建構輸出內容。模組設定 implementation 依附元件時，Gradle 會知道您不希望模組在編譯期間將依附元件洩漏至其他模組。也就是說，依附元件不會提供給依附目前模組的其他模組。

使用這項依附元件設定而非 api 可能會大幅改善建構時間，因為這樣可以減少建構系統需要重新編譯的模組數量。舉例來說，如果 implementation 依附元件變更其 API，Gradle 只會重新編譯該依附元件和直接依附的模組。大多數的應用程式和測試模組都應使用這項設定。
api Gradle 會將依附元件新增至編譯的類別路徑，並建構輸出內容。當模組包含 api 依附元件時，Gradle 便會知道該模組想將依附元件直接傳輸至其他模組，以便在執行階段和編譯時間使用。

請謹慎使用此設定，並只在您需要將資料連帶匯出至其他上游消費者的依附元件時使用。如果 api 依附元件變更其外部 API，Gradle 會在編譯期間重新編譯可存取該依附元件的所有模組。擁有大量 api 依附元件可能會大幅增加建構時間。除非您想將依附元件的 API 公開至其他模組，否則程式庫模組應改用 implementation 依附元件。
compileOnly Gradle 僅將依附元件新增至編譯的類別路徑 (也就是不會將其新增至建構輸出內容)。若您要建立 Android 模組，且在編譯期間需要用到依附元件，這項做法就很實用，但在執行階段中，您可自行選擇是否提供這項模組。舉例來說，假如您依附的程式庫僅包含編譯時間註解 (通常用於產生程式碼，但通常不含在建構輸出內容中)，則可將該程式庫標示為 compileOnly。

假使採用上述設定，程式庫模組必須包含執行階段條件，以便檢查依附元件是否可用，之後程式庫模組將妥善變更其行為，確保如未提供，服務仍可正常運作。如此便能避免新增不重要的暫時依附元件，進而縮減最終應用程式的大小。

注意：compileOnly 設定無法搭配 Android Archive (AAR) 依附元件使用。
runtimeOnly Gradle 僅將依附元件新增至建構輸出內容，供執行階段使用，因此不會加入編譯類別路徑。這項功能很少在 Android 上使用，但通常會用於伺服器應用程式，以提供記錄實作。舉例來說，程式庫可以使用不含實作項目的記錄 API。該程式庫的使用者可以將其新增為 implementation 依附元件，並納入 runtimeOnly 依附元件，以便實際記錄實作使用。
ksp
kapt
annotationProcessor

這些設定提供的程式庫會先處理程式碼中的註解和其他符號，再加以編譯。這些工具通常會驗證程式碼或產生額外的程式碼，減少您需要編寫的程式碼。

如要新增這類依附元件，您必須使用 ksp、kapt 或 annotationProcessor 設定，將依附元件新增至註解處理工具類別路徑。使用這些設定可將編譯類別路徑與註解處理工具類別路徑分開，進而提升建構效能。如果 Gradle 在編譯類別路徑中找到註解處理工具，便會停用避免編譯的功能，對建構時間將造成負面影響 (Gradle 5.0 以上版本將忽略編譯類別路徑上的註解處理工具)。

假使 Android Gradle 外掛程式的 JAR 檔案包含下列檔案，就屬於註解處理工具：

META-INF/services/javax.annotation.processing.Processor

假使外掛程式偵測到編譯類別路徑上的註解處理工具，便會產生建構錯誤。

ksp 是 Kotlin 符號處理器，由 Kotlin 編譯器執行。

kapt 和 apt 是不同的工具，可在 Kotlin 或 Java 編譯器執行前處理註解。

決定要使用的設定時，請考量以下幾點：

  • 如果是以 Kotlin Symbol 處理器的形式提供處理器，請將其做為 ksp 依附元件使用。如要進一步瞭解如何使用 Kotlin Symbol 處理器，請參閱「從 kapt 遷移至 ksp」。
  • 如果處理器無法做為 Kotlin 符號處理器：
    • 如果專案包含 Kotlin 來源 (但也可以包含 Java 來源)，請使用 kapt 納入來源。
    • 如果您的專案僅使用 Java 來源，請使用 annotationProcessor 加入。

如要進一步瞭解如何使用註解處理工具，請參閱「新增註解處理工具」。
lintChecks

使用這項設定即可納入程式庫，內含您希望 Gradle 在建構 Android 應用程式專案時執行的 Lint 檢查。

請注意，包含 lint.jar 檔案的 AAR 會自動執行該 lint.jar 檔案中定義的檢查項目，因此您不需要新增明確的 lintChecks 依附元件。這樣就能在單一依附元件中定義程式庫和相關聯的 Lint 檢查，確保系統會在取用端使用程式庫時執行檢查。
lintPublish 在 Android 程式庫專案中使用這項設定，納入要讓 Gradle 編譯為 lint.jar 檔案並封裝 AAR 的 Lint 檢查項目。這會導致使用 AAR 的專案一併套用這些 Lint 檢查。假使您原先使用 lintChecks 依附元件設定在已發布的 AAR 中加入 Lint 檢查，則必須遷移這些依附元件，才能改用 lintPublish 設定。

Kotlin

dependencies {
  // Executes lint checks from the ":checks" project at build time.
  lintChecks(project(":checks"))
  // Compiles lint checks from the ":checks-to-publish" into a
  // lint.jar file and publishes it to your Android library.
  lintPublish(project(":checks-to-publish"))
}

Groovy

dependencies {
  // Executes lint checks from the ':checks' project at build time.
  lintChecks project(':checks')
  // Compiles lint checks from the ':checks-to-publish' into a
  // lint.jar file and publishes it to your Android library.
  lintPublish project(':checks-to-publish')
}

設定特定建構變化版本的依附元件

上述設定會將依附元件套用至所有建構變數。如果您只想宣告特定建構變化版本來源集或測試來源集的依附元件，則必須將設定名稱大寫，並加上建構變化版本或測試來源集的名稱做為其前置字串。

舉例來說，如果只想使用 implementation 設定，為「免費」產品口味新增遠端二進位檔依附元件，請使用以下設定：

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Groovy

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

不過，如果您想為合併產品變種版本和建構類型的變數新增依附元件，就必須初始化設定名稱：

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Groovy

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

如要為本機測試和檢測設備測試新增 implementation 依附元件，如下所示：

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

Groovy

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

然而，在這種情況下，部分設定並不合理。舉例來說，由於其他模組不能使用 androidTest，因此假使您使用 androidTestApi 設定，便會收到以下警示：

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

依附元件順序

依附元件的列出順序會指出各存放區的優先順序：第一個程式庫的優先順序高於第二個，第二個程式庫的優先順序高於第三個，依此類推。假使資源合併或資訊清單元素合併至應用程式，應用程式順序就相當重要。

舉例來說，假使您的專案宣告了下列項目：

  • LIB_A 和 LIB_B 上的依附元件 (依順序)
  • 而 LIB_A 則取決於 LIB_C 和 LIB_D (依順序)
  • 而 LIB_B 也受到 LIB_C 影響

固定依附元件順序如下：

  1. LIB_A
  2. LIB_D
  3. LIB_B
  4. LIB_C

這可確保 LIB_A 和 LIB_B 能覆寫 LIB_C；並且 LIB_D 的優先順序高於 LIB_B，因為 LIB_A (視實際情況而定) 的優先順序高於 LIB_B。

如要進一步瞭解如何合併不同專案來源/依附元件的資訊清單，請參閱「合併多個資訊清單檔案」。

Play 管理中心的依附元件資訊

建構應用程式時，AGP 會加入中繼資料，說明編譯至應用程式中的程式庫依附元件。上傳應用程式時，Play 管理中心會檢查這項中繼資料，針對 SDK 和依附元件的已知問題提供快訊，在某些情況下也會提供可行的意見回饋，協助解決這些問題。

資料會經過壓縮、使用 Google Play 簽署金鑰加密，並儲存在發布應用程式的簽署區塊中。建議您保留這個依附元件檔案，以便提供安全良好的使用者體驗。如要選擇不採用，請在模組的 build.gradle.kts 檔案中加入以下 dependenciesInfo 區塊。

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

如要進一步瞭解我們的政策，以及依附元件的潛在問題，請參閱「在應用程式中使用第三方 SDK」的支援頁面。

SDK 深入分析

如果發生下列問題，Android Studio 會在版本目錄檔案和 Google Play SDK 索引中，公開 SDK 的專案結構對話方塊顯示 Lint 警告：

  • SDK 的作者已將這些 SDK 標示為已過時。
  • SDK 違反 Play 政策。

這些警告是更新這些依附元件的訊號，因為使用過時版本可能會導致日後無法發布至 Google Play 管理中心。

新增沒有版本目錄的建構依附元件

建議您使用版本目錄新增及管理依附元件，但簡單的專案可能不需要這些依附元件。以下是未使用版本目錄的建構檔案範例：

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Groovy

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

這個建構檔案會宣告「com.example.android」命名空間群組中 12.3 版「app-magic」程式庫的依附元件。遠端二進位檔依附元件宣告的簡寫如下：

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Groovy

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

建構檔案也會宣告名為「mylibrary」的 Android 程式庫模組依附元件；此名稱必須符合您在 settings.gradle.kts 檔案中定義的程式庫名稱 include:。建構應用程式時，建構系統會編譯程式庫模組，然後在應用程式中封裝產生的編譯內容。

建構檔案也會宣告 Android Gradle 外掛程式 (com.application.android) 的依附元件。如果您有多個模組使用相同的外掛程式，則所有模組的建構類別路徑上只能有一個版本的外掛程式。請不要在每個模組建構指令碼中指定版本，而是應在根建構指令碼中加入外掛程式依附元件和版本，並指出不要套用該版本。新增 apply false 會告知 Gradle 記下外掛程式的版本，但不會在根建構中使用該版本。通常根建構指令碼是空白的，只有這個 plugins 區塊例外。

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Groovy

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

如果您有單一模組專案，可以在模組層級的建構指令碼中明確指定版本，並讓專案層級的建構指令碼保持空白：

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

Groovy

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}