新增建構依附元件

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，由 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.5.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.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 會加入中繼資料，說明編譯至應用程式中的程式庫依附元件。上傳應用程式時，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 管理中心。

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

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

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」命名空間群組中，宣告「app-magic」程式庫 12.3 版的依附元件。遠端二進位檔依附元件宣告的簡寫如下：

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