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,由 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 |
使用這項設定即可納入程式庫,內含您希望 Gradle 在建構 Android 應用程式專案時執行的 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 會在版本目錄檔案和 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」命名空間群組中,宣告「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' }