新增建構依附元件

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.tomllibs 部分。使用單一版本目錄時,建議保留「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 限定詞,因此您無法在程式庫別名的開頭使用 versionsplugins

設定依附元件

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

這些設定會在編譯之前提供程式庫,以便處理程式碼中的註解和其他符號。這些程式庫通常會驗證程式碼或產生其他程式碼,減少您需要編寫的程式碼。

如要新增這類依附元件,您必須使用 kspkaptannotationProcessor 設定,將這類依附元件新增至註解處理工具類別路徑。使用這些設定會將編譯類別路徑與註解處理工具類別路徑分開,藉此提升建構效能。如果 Gradle 發現編譯類別路徑上的註解處理工具,便會停用 避免編譯的功能,對建構時間將造成負面影響 (Gradle 5.0 以上版本將忽略編譯類別路徑上的註解處理工具)。

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

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

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

ksp 是 Kotlin Symbol Processor,由 Kotlin 編譯器執行。

kaptapt 是不同的工具,會在 Kotlin 或 Java 編譯器執行前處理註解。

在決定要使用何種設定時,請考量下列事項:

  • 如果處理器能夠以 Kotlin Symbol Processor 的形式提供,請使用該處理器做為 ksp 依附元件。如要進一步瞭解如何使用 Kotlin Symbol 處理器,請參閱「從 kapt 遷移至 ksp」。
  • 如果處理器無法做為 Kotlin Symbol Processor:
    • 如果專案包含 Kotlin 來源 (但也可以包含 Java 來源),請使用 kapt 加入來源。
    • 如果您的專案只使用 Java 來源,請使用 annotationProcessor 加入來源。

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

lintChecks

請使用這項設定納入一個程式庫,其中包含您在建構 Android 應用程式專案時希望 Gradle 執行的 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.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_ALIB_B 上的依附元件 (依順序)
  • LIB_A 則取決於 LIB_CLIB_D (依順序)
  • LIB_B 也受到 LIB_C 影響

固定依附元件順序如下:

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

這可確保 LIB_ALIB_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 會在版本目錄檔案中顯示 Lint 警告,也會在 Google Play SDK 索引的「Project Structure」對話方塊中顯示公開 SDK 的「Project Structure」對話方塊

  • 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」命名空間群組中,宣告「app-magic」程式庫 12.3 版的依附元件。遠端二進位檔依附元件宣告是在下列環境中使用:

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