新增建構依附元件

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

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

新增及管理建構依附元件的最佳方式是使用版本目錄 新專案預設使用的方法本章節會說明 Android 專案使用的設定類型請參閱 Gradle 說明文件 ，瞭解更多選項。如需使用版本目錄的應用程式範例，請參閱 Android 即時情報。 如果您已經設定了建構依附元件 沒有版本目錄且擁有多模組專案 migrating。

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

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

  1. 為所需的依附元件版本新增別名 版本目錄檔案的 [versions] 部分，名為 libs.versions.toml (在 gradle 目錄的 「Project」檢視畫面或「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. 在 [libraries] 中為依附元件新增別名 ( 遠端二進位檔或本機程式庫模組) 或 [plugins] (針對 外掛程式)，libs.versions.toml檔案部分。

    [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) 中， 為程式庫系列及其版本分組。您可以在 版本目錄和建構檔案，並讓您管理這些版本。詳情請見 詳情請參閱物料清單。

  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 參照是很罕見的；請參閱 Dependencies 版本號碼。程式庫 參照不含 libraries 限定詞，因此您無法使用 程式庫開頭的 versions 或 plugins 別名。

設定依附元件

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

設定 行為
implementation Gradle 將依附元件新增至編譯的類別路徑，並將依附元件封裝到建構輸出內容。當您 模組會設定 implementation 依附元件 讓 Gradle 知道您不希望模組洩漏 在編譯期間對其他模組的依附元件。也就是說 但無法用於依附於 後續課程我們將逐一介紹 預先訓練的 API、AutoML 和自訂訓練

使用這個依附元件設定，而非 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 上很少使用，但常用於伺服器 來提供記錄實作。舉例來說 程式庫使用的 Logging API 即使未附上 。該圖書館的使用者可以將該資料庫新增為 implementation 依附元件並加入 實際記錄的 runtimeOnly 依附元件 。
ksp
kapt
annotationProcessor

這些設定提供處理註解的程式庫 和其他符號都必須先經過編譯通常 驗證程式碼或產生其他程式碼 而不需要寫入。

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

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

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

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

ksp 是 Kotlin Symbol 處理器，且是由 Kotlin 編譯器。

kapt 和 apt 是各自獨立的工具， 在執行 Kotlin 或 Java 編譯器之前，已完成處理註解。

在決定要使用何種設定時，請考量 包括：

  • 如果是以 Kotlin Symbol 處理器的形式提供處理器，請使用 做為 ksp 依附元件 請參閱「從 kapt 遷移至 ksp」一文。 。
  • 如果無法透過 Kotlin Symbol 處理器取得處理器：
    • 如果專案包含 Kotlin 來源 (但也可以 包括 Java 來源) 使用kapt 加入。
    • 如果專案僅使用 Java 來源，請使用 annotationProcessor 即可加入。

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

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

請注意，內含 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')
}

設定特定建構變數的依附元件

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

例如，如果只想將遠端二進位檔依附元件新增至「免費」產品 方法是使用 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.5.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.5.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 會納入描述程式庫的中繼資料 編譯成應用程式的依附元件上傳應用程式時，Google Play Play 管理中心會檢查這項中繼資料，提供有關 SDK 和 SDK 的已知問題快訊 應用程式使用的依附元件。在某些情況下，也會為 解決這些問題

資料會經過壓縮、使用 Google Play 簽署金鑰加密，並儲存在 發布應用程式的簽署區塊建議保留這項依附元件 以確保安全良好的使用者體驗您可以加入 追蹤 dependenciesInfo敬上 封鎖在模組的 build.gradle.kts 檔案中。

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」中顯示 Lint 警告 中公開 SDK 的結構對話方塊： 符合下列條件時適用的 Google Play SDK 索引：

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

下列警告是您應更新依附元件的信號，因為 使用舊版本時，可能無法在 Google Play 發布應用程式 Google Cloud 控制台

在沒有版本目錄的情況下新增建構依附元件

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

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')
}

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

Kotlin

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

Groovy

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

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

建構檔案也會宣告 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'
}