新增建構依附元件

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，讓它為您管理這些版本。詳情請參閱使用物料清單。

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 專案中用於依附元件的各項設定。

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

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 設定，為「免費」產品口味新增遠端二進位檔依附元件，請使用以下設定：

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

不過，如果您想為合併產品變種版本和建構類型的變數新增依附元件，就必須初始化設定名稱：

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

如要為本機測試和檢測設備測試新增 implementation 依附元件，如下所示：

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

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 會在版本目錄檔案和「Google Play SDK Index」中的公開 SDK「Project Structure」對話方塊中顯示 Lint 警告：

• 作者已將 SDK 標示為過舊。
• SDK 違反 Play 政策。

這些警告是應更新這些依附元件的信號，因為使用過時版本可能會導致日後無法發布至 Google Play 管理中心。

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

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

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

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」程式庫的依附元件。遠端二進位檔依附元件宣告的簡寫如下：

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

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 區塊例外。

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

如果您有單一模組專案，可以在模組層級建構指令碼中明確指定版本，並將專案層級建構指令碼留空：

plugins {
    id("com.android.application") version "8.3.0"
}

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}