新增建構依附元件

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，並讓 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 符號處理器形式提供，請將其做為 ksp 依附元件使用。如要瞭解如何使用 Kotlin 符號處理工具，請參閱「從 kapt 遷移至 ksp」。
  • 如果處理器無法做為 Kotlin 符號處理器使用：
    • 如果專案包含 Kotlin 來源 (但也可以包含 Java 來源)，請使用 kapt 納入。
    • 如果專案只使用 Java 來源，請使用 annotationProcessor 納入。

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

使用這項設定時，請納入您在建構 Android 應用程式專案時，希望 Gradle 執行的 Lint 檢查作業。

請注意，如果 AAR 包含 lint.jar 檔案，系統會自動執行該 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 會在版本目錄檔案和「Project Structure」對話方塊中顯示 Lint 警告，表示「Google Play SDK Index」中的公開 SDK 有問題：

  • SDK 作者將其標示為過舊。
  • SDK 違反 Google Play 政策。
  • 這些 SDK 含有已知安全漏洞。
  • 這些 SDK 已遭作者淘汰。

收到警告就代表您應更新這些依附元件，因為使用過時版本可能會導致日後無法發布至 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'
}