Android Studio 中的 Gradle 建構系統可做為依附元件,將外部二進位檔或其他程式庫模組加入建構作業中。依附元件可存放在本機或遠端存放區,且依附元件宣告的遞移依附元件也會自動加入。本頁面說明如何在 Android 專案中使用依附元件,更將詳加闡述 Android Gradle 外掛程式 (AGP) 的特定行為及設定。如需 Gradle 依附元件的相關概念指南,請一併參閱 Gradle 依附元件管理指南。提醒您,Android 專案只能使用本頁中定義的「依附元件設定」。
新增程式庫或外掛程式依附元件
新增及管理建構依附元件的最佳方式,就是使用版本目錄,也就是新專案預設採用的方法。本節說明 Android 專案使用的最常見設定類型;如需更多資訊,請參閱 Gradle 說明文件。如需使用版本目錄的應用程式範例,請參閱「Now in Android」。如果您已設定不含版本目錄的建構依附元件,且具有多模組專案,建議您遷移。
如需新增及管理原生依附元件 (罕見) 的相關指引,請參閱「原生依附元件」。
在以下範例中,我們在專案中加入了遠端二進位檔依附元件 (Jetpack Macrobenchmark 程式庫)、本機程式庫模組依附元件 (myLibrary
) 和外掛程式依附元件 (Android Gradle 外掛程式)。以下是在專案中加入這些依附元件的一般步驟:
在版本目錄檔案的
[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」的預設值。在
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,然後由系統為您管理這些版本。詳情請參閱使用物料清單一文。
為需要依附元件的模組建構指令碼,新增依附元件別名的參照。從建構指令碼參照別名時,將別名的底線和破折號轉換為點。模組層級建構指令碼看起來會像這樣:
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 |
Gradle 會將依附元件新增至編譯的類別路徑,並建構輸出內容。當模組包含 api 依附元件時,Gradle 便會知道該模組想要將依附元件間接匯出至其他模組,以便在執行階段和編譯時間使用。請謹慎使用這項設定,請只在您需要將資料連帶匯出至其他上游消費者的依附元件時使用。如果 |
compileOnly |
Gradle 僅將依附元件新增至編譯類別路徑,不會將其新增至建構輸出內容。若您要建立 Android 模組,且在編譯期間需要用到依附元件,這項做法就很實用,但在執行階段中,您可自行選擇是否提供依附元件。舉例來說,假使您依附的程式庫只包含編譯時間註解 (通常用來產生程式碼,但通常不會包含在建構輸出內容中),您可以標記該程式庫 compileOnly 。
假使採用上述設定,程式庫模組必須包含執行階段條件,以便檢查依附元件是否可用,之後程式庫模組將妥善變更其行為,確保如未提供,服務仍可正常運作。如此便能避免新增不重要的暫時依附元件,進而縮減最終應用程式的大小。
注意: |
runtimeOnly |
Gradle 僅將依附元件新增至建構輸出內容,供執行階段使用,因此不會加入編譯類別路徑。這很少用在 Android,但常用於伺服器應用程式來提供記錄實作。舉例來說,程式庫可以使用不含實作項目的記錄 API。該程式庫的取用端可將其新增為 implementation 依附元件,並加入實際使用記錄實作的 runtimeOnly 依附元件。 |
ksp |
這些設定會在編譯之前提供程式庫,以便處理程式碼中的註解和其他符號。這些程式庫通常會驗證程式碼或產生其他程式碼,減少您需要編寫的程式碼。 如要新增這類依附元件,您必須使用 假使 Android Gradle 外掛程式的 JAR 檔案包含下列檔案,就屬於註解處理工具:
假使外掛程式偵測到編譯類別路徑上的註解處理工具,便會產生建構錯誤。
在決定要使用何種設定時,請考量下列事項:
如要進一步瞭解如何使用註解處理工具,請參閱「新增註解處理工具」。 |
lintChecks |
請使用這項設定納入一個程式庫,其中包含您在建構 Android 應用程式專案時希望 Gradle 執行的 Lint 檢查項目。 請注意,包含 |
lintPublish |
在 Android 程式庫專案中使用這項設定,納入要讓 Gradle 編譯為 lint.jar 檔案並封裝 AAR 的 Lint 檢查項目。這會導致使用 AAR 的專案一併套用這些 Lint 檢查。假使您原先使用 lintChecks 依附元件設定在已發布的 AAR 中加入 Lint 檢查,則必須遷移這些依附元件,才能改用 lintPublish 設定。Kotlindependencies { // 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")) } Groovydependencies { // 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_A
和LIB_B
上的依附元件 (依順序)- 而
LIB_A
則取決於LIB_C
和LIB_D
(依順序) - 而
LIB_B
也受到LIB_C
影響
固定依附元件順序如下:
LIB_A
LIB_D
LIB_B
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 會在版本目錄檔案中顯示 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' }