技術標籤：androidgradle

gradle 新增構建依賴項

參考：新增構建依賴項

利用 Android Studio 中的 Gradle 構建系統，您可以輕鬆地將外部二進位制檔案或其他庫模組作為依賴項新增到您的 build 中。這些依賴項可位於您的計算機上或遠端程式碼庫中，並且它們宣告的所有傳遞依賴項也會自動包含在內。本頁介紹瞭如何在您的 Android 專案中使用依賴項，包括有關 Android Plugin for Gradle 特有的行為和配置的詳細資訊。如需更深入地瞭解 Gradle 依賴項的概念，您還應該參閱Gradle 依賴項管理指南。但請注意，您的 Android 專案只能使用本頁上定義的

依賴項配置。

注意：指定依賴項時，不應使用動態版本號，如 ‘com.android.tools.build:gradle:3.+’。使用此功能可能會導致意外的版本更新和難以解析版本差異。

###1. 依賴項型別

如需向您的專案新增依賴項，請在 build.gradle 檔案的 dependencies 程式碼塊中指定依賴項配置，如 implementation。

例如，應用模組的以下 build.gradle 檔案包含三種不同型別的依賴項：

apply plugin: 'com.android.application'

android { ... }

dependencies {
    // Dependency on a local library module
翻譯後： 依賴一個本地庫模組
    implementation project(":mylibrary")

    // Dependency on local binaries
翻譯後： 依賴一組本地二進位制檔案
    implementation fileTree(dir: 'libs', include: ['*.jar'])

    // Dependency on a remote binary
翻譯後： 依賴一個遠端二進位制檔案
    implementation 'com.example.android:app-magic:12.3'
}
 

其中每種依賴項配置都請求不同種類的庫依賴項，如下所示：

本地庫模組依賴項

implementation project(’:mylibrary’)
這聲明瞭對一個名為“mylibrary”（此名稱必須與在您的 settings.gradle 檔案中使用 include: 定義的庫名稱相符）的 Android 庫模組的依賴關係。在構建您的應用時，構建系統會編譯該庫模組，並將生成的編譯內容打包到 APK 中。

####本地二進位制檔案依賴項

implementation fileTree(dir: ‘libs’, include: [’*.jar’])
Gradle 聲明瞭對專案的 module_name/libs/ 目錄中 JAR 檔案的依賴關係（因為 Gradle 會讀取 build.gradle 檔案的相對路徑）。

或者，您也可以按如下方式指定各個檔案：
implementation files(‘libs/foo.jar’, ‘libs/bar.jar’)

####遠端二進位制檔案依賴項

implementation ‘com.example.android:app-magic:12.3’
這實際上是以下程式碼的簡寫形式：
implementation group: ‘com.example.android’, name: ‘app-magic’, version: ‘12.3’
這聲明瞭對“com.example.android”名稱空間組內的 12.3 版“app-magic”庫的依賴關係。

注意：此類遠端依賴項要求您宣告適當的遠端程式碼庫，Gradle 應在其中查詢相應的庫。如果本地不存在相應的庫，那麼當 build 需要它時（例如，當您點選Sync Project with Gradle Files圖示
或執行 build 時），Gradle 會從遠端站點提取它。

###原生依賴項

根據公開原生庫的 AAR，原生依賴項將自動提供給externalNativeBuild所使用的構建系統。如要從程式碼訪問這些庫，您必須在原生構建指令碼中連結到這些庫。如需瞭解詳情，請參閱使用原生依賴項。

###2. 依賴項配置
在 dependencies 程式碼塊內，您可以從多種不同的依賴項配置中選擇其一（如上面所示的 implementation）來宣告庫依賴項。每種依賴項配置都向 Gradle 提供了有關如何使用該依賴項的不同說明。下表介紹了您可以對 Android 專案中的依賴項使用的各種配置。此表還將這些配置與自 Android Gradle 外掛 3.0.0 起棄用的配置進行了比較。

注意：您不能將 compileOnly 配置與 AAR 依賴項配合使用。

lint: (敷傷口用的)紗布;(織物在製作過程中從表面掉落的)纖維屑，飛花;(毛料、棉布等的)絨毛
eg. （敷傷口用的）紗布 a type of soft cotton cloth used for covering and protecting wounds

dependencies {
  // Executes lint checks from the ':checks' project
  // at build time.
翻譯後：構建時從'：checks'專案執行 link 檢查
  lintChecks project(':checks')
  // Compiles lint checks from the ':checks-to-publish'
  // into a lint.jar file and publishes it to your
  // Android library.
翻譯後：將'：checks-to-publish'編譯lint檢查放入lint.jar檔案並將其釋出到你的Android庫
  lintPublish project(':checks-to-publish')
}

以上配置會將依賴項應用於所有構建變體。如果您只想為特定的構建變體原始碼集或測試原始碼集宣告依賴項，則必須將配置名稱的首字母大寫，並在其前面加上構建變體或測試原始碼集的名稱作為字首。
例如，如需只向“free”產品變種新增implementation依賴項（使用遠端二進位制檔案依賴項），請使用如下所示的程式碼：

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

不過，如果您想為將產品變種和構建型別組合在一起的變體新增依賴項，就必須在 configurations 程式碼塊中初始化配置名稱。以下示例向“freeDebug”構建變體添加了 runtimeOnly 依賴項（使用本地二進位制檔案依賴項）：

configurations {
    // Initializes a placeholder for the freeDebugRuntimeOnly dependency
    // configuration.
翻譯後：為freeDebugRuntimeOnly依賴項初始化一個佔位符 配置
1.
    freeDebugRuntimeOnly {}
}

dependencies {
2.
    freeDebugRuntimeOnly fileTree(dir: 'libs', include: ['*.jar'])
}

如需為本地測試和插樁測試新增 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.
翻譯後：僅為自動化測試的APK新增遠端二進位制依賴項。
    androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'
}

不過，某些配置在這種情況下沒有意義。例如，因為其他模組不能依賴於 androidTest，所以如果您使用 androidTestApi 配置，會收到以下警告：

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.
翻譯後：配置“ androidTestApi”已過時，並已替換為 'androidTestImplementation'

###3.添加註釋處理器
如果將註釋處理器新增到編譯類路徑，您將看到一條與以下內容類似的錯誤訊息

Error: Annotation processors must be explicitly declared now. 翻譯後：現在必須顯式宣告註釋處理器

如需解決此錯誤，請使用 annotationProcessor 配置依賴項，以將註釋處理器新增到您的專案，如下所示

dependencies {
    // Adds libraries defining annotations to only the compile classpath.
翻譯後：僅將定義註釋的庫新增到編譯類路徑
    compileOnly 'com.google.dagger:dagger:version-number'
    // Adds the annotation processor dependency to the annotation processor classpath.
翻譯後：將註釋處理器依賴項新增到註釋處理器類路徑
    annotationProcessor 'com.google.dagger:dagger-compiler:version-number'
}

注意：Android Plugin for Gradle 3.0.0 及更高版本不再支援android-apt外掛。
#####向註釋處理器傳遞引數
如果需要向註釋處理器傳遞引數，您可以使用模組構建配置中的AnnotationProcessorOptions程式碼塊執行此操作。例如，如果要以鍵值對形式傳遞基元資料型別，您可以使用argument屬性，如下所示：

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                argument "key1", "value1"
                argument "key2", "value2"
            }
        }
    }
}

不過，在使用 Android Gradle 外掛 3.2.0 及更高版本時，您需要使用 Gradle 的CommandLineArgumentProvider介面傳遞表示檔案或目錄的處理器引數。

使用CommandLineArgumentProvider可讓您或註釋處理器作者將增量構建屬性型別註釋應用於每個引數，從而提高增量構建和快取整潔構建的正確性和效能。

例如，下面的類實現了CommandLineArgumentProvider並註釋了處理器的每個引數。此外，此示例還使用了 Groovy 語言語法，並且直接包含在模組的build.gradle檔案中。

注意：通常，註釋處理器作者會提供此類或有關如何編寫這種類的說明。這是因為，每個引數都需要指定正確的構建屬性型別註釋，才能按預期執行。

class MyArgsProvider implements CommandLineArgumentProvider {

    // Annotates each directory as either an input or output for the
    // annotation processor.
翻譯後：通過 註釋處理器將每個目錄註釋為該目錄的輸入或輸出
    @InputFiles
    // Using this annotation helps Gradle determine which part of the file path
    // should be considered during up-to-date checks.
翻譯後：使用此註釋有助於Gradle確定在最新檢查期間應考慮檔案路徑的哪一部分 
自己理解為 更新的編譯
    @PathSensitive(PathSensitivity.RELATIVE)
    FileCollection inputDir

    @OutputDirectory
    File outputDir

    // The class constructor sets the paths for the input and output directories.
翻譯後：類建構函式設定輸入和輸出目錄的路徑
    MyArgsProvider(FileCollection input, File output) {
        inputDir = input
        outputDir = output
    }

    // Specifies each directory as a command line argument for the processor.
    // The Android plugin uses this method to pass the arguments to the
    // annotation processor.
翻譯後：將每個目錄指定為處理器的命令列引數。  Android外掛使用此方法將引數傳遞給註釋處理器。

    @Override
    Iterable<String> asArguments() {
        // Use the form '-Akey[=value]' to pass your options to the Java compiler.
翻譯後：使用格式“ -Akey [= value]”將您的選項傳遞給Java編譯器。
        ["-AinputDir=${inputDir.singleFile.absolutePath}",
         "-AoutputDir=${outputDir.absolutePath}"]
    }
}

android {...}

建立一個實現CommandLineArgumentProvider的類後，您需要對其進行初始化並使用annotationProcessorOptions.compilerArgumentProvider屬性將其傳遞給 Android 外掛，如下所示。

// This is in your module's build.gradle file.
翻譯後：這是在你的模組的build.gradle檔案中
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                // Creates a new MyArgsProvider object, specifies the input and
                // output paths for the constructor, and passes the object
                // to the Android plugin.
翻譯後：建立一個新的MyArgsProvider物件，指定輸入並輸出建構函式的路徑，並傳遞物件至Android外掛
                compilerArgumentProvider new MyArgsProvider(files("input/path"),
                                         new File("output/path"))
            }
        }
    }
}

如需詳細瞭解實現CommandLineArgumentProvider如何幫助提高構建效能，請閱讀快取 Java 專案。
####停用註釋處理器錯誤檢查
如果編譯類路徑中的依賴項包含您不需要的註釋處理器，您可以通過將以下程式碼新增到 build.gradle 檔案來停用錯誤檢查。請注意，您新增到編譯類路徑中的註釋處理器仍不會被新增到處理器類路徑中。

    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                includeCompileClasspath false
            }
        }
    }
}

如果在將專案的註釋處理器遷移到處理器類路徑後遇到問題，您可以通過將 includeCompileClasspath 設為 true，允許編譯類路徑中包含註釋處理器。不過，不建議將此屬性設為 true，在 Android 外掛的未來更新中將會移除用來執行此操作的選項。
####排除傳遞依賴項
隨著應用的範圍不斷擴大，它可能會包含許多依賴項，包括直接依賴項和傳遞依賴項（應用中匯入的庫所依賴的庫）。如需排除不再需要的傳遞依賴項，您可以使用 exclude 關鍵字，如下所示

    implementation('some-library') {
        exclude group: 'com.example.imgtools', module: 'native'
    }
}

####從測試配置中排除傳遞依賴項
如果您需要從測試中排除某些傳遞依賴項，上面所示的程式碼示例可能無法按預期發揮作用。這是因為，測試配置（例如 androidTestImplementation）擴充套件了模組的 implementation 配置。也就是說，當 Gradle 解析配置時，測試配置始終包含 implementation 依賴項。

因此，如需從測試中排除傳遞依賴項，必須在執行程式碼時執行此操作，如下所示：

    variant.getCompileConfiguration().exclude group: 'com.jakewharton.threetenabp', module: 'threetenabp'
    variant.getRuntimeConfiguration().exclude group: 'com.jakewharton.threetenabp', module: 'threetenabp'
}

注意：您仍可在依賴項程式碼塊中使用exclude關鍵字（如排除依賴項部分的原始程式碼示例所示），以省略測試配置特有的傳遞依賴項，也就是其他配置不包含的傳遞依賴項。
####使用變體感知型依賴項管理機制
Android 外掛 3.0.0 及更高版本包含一種新的依賴項機制，該機制可在使用庫時自動匹配變體。這意味著，應用的debug變體會自動使用庫的debug變體，依此類推。在使用變種時，這種機制也同樣適用 - 應用的freeDebug變體將使用庫的freeDebug變體。

為了讓外掛準確匹配變體，您需要在無法進行直接匹配的情況下提供匹配回退機制。不妨假設您的應用配置了一個名為“staging”的構建型別，但該應用的一個庫依賴項沒有進行相應配置。當外掛嘗試構建“staging”版本的應用時，它不知道要使用哪個版本的庫，因此您將看到一條與以下內容類似的錯誤訊息：

Error:Failed to resolve: Could not resolve project :mylibrary.
翻譯後： 無法解決專案：mylibrary
Required by:
    project :app

解決與變體匹配相關的構建錯誤
外掛包含一些 DSL 元素，這些元素有助於控制 Gradle 應如何解決應用與依賴項之間無法進行直接變體匹配的問題。請參閱下表，以確定應使用哪個 DSL 屬性來解決與變體感知依賴項匹配相關的特定編譯錯誤。

// In the app's build.gradle file.
android {
    buildTypes {
        debug {}
        release {}
        staging {
            // Specifies a sorted list of fallback build types that the
            // plugin should try to use when a dependency does not include a
            // "staging" build type. You may specify as many fallbacks as you
            // like, and the plugin selects the first build type that's
            // available in the dependency.
翻譯後：
指定後備構建型別的排序列表， 外掛在不包含依賴項時應嘗試使用 “ staging”構建型別。
您可以指定與您一樣多你喜歡的後備廣告，然後外掛在依賴項中可選擇第一個構建型別 。
            matchingFallbacks = ['debug', 'qa', 'release']
        }
    }
}

// In the app's build.gradle file.
android {
    defaultConfig{
    // Do not configure matchingFallbacks in the defaultConfig block.
    // Instead, you must specify fallbacks for a given product flavor in the
    // productFlavors block, as shown below.
翻譯後：
不要在defaultConfig塊中配置matchFallbacks。 相反，您必須在 productFlavors塊 給定fallbacks，如下所示。

  }
    flavorDimensions 'tier'
    productFlavors {
        paid {
            dimension 'tier'
            // Because the dependency already includes a "paid" flavor in its
            // "tier" dimension, you don't need to provide a list of fallbacks
            // for the "paid" flavor.
翻譯後：
因為依賴項已在“層”維度的依賴項中包含“付費”形式， 對於“付費”口味您無需提供後備列表。
        }
        free {
            dimension 'tier'
            // Specifies a sorted list of fallback flavors that the plugin
            // should try to use when a dependency's matching dimension does
            // not include a "free" flavor. You may specify as many
            // fallbacks as you like, and the plugin selects the first flavor
            // that's available in the dependency's "tier" dimension.
翻譯後：
在不包含“免費”的味道外掛時候，後備味道的排序列表 應該在依賴項的匹配維度確實起作用時。您可以 根據需要指定儘可能多的後備fallbacks，然後在依賴項的“tier”維度中可用的第一個樣式外掛。
            matchingFallbacks = ['demo', 'trial']
        }
    }
}

// In the app's build.gradle file.
android {
    defaultConfig{
    // Specifies a sorted list of flavors that the plugin should try to use from
    // a given dimension. The following tells the plugin that, when encountering
    // a dependency that includes a "minApi" dimension, it should select the
    // "minApi18" flavor. You can include additional flavor names to provide a
    // sorted list of fallbacks for the dimension.
翻譯後：
外掛應嘗試從一個維度使用一組指定的口味的排序列表。下面告訴外掛，當遇到 包含“ minApi”維的依賴項，應選擇 “ minApi18”風味。您可以包括其他風味名稱以提供 維度的後備列表排序
    missingDimensionStrategy 'minApi', 'minApi18', 'minApi23'
    // You should specify a missingDimensionStrategy property for each
    // dimension that exists in a local dependency but not in your app.
翻譯後：
您應該為每個屬性指定一個丟失維度策略屬性 ，那些存在於本地依賴項中但不存在於您的應用程式中的維度
存在於本地依賴關係中，但不存在於您的應用中
    missingDimensionStrategy 'abi', 'x86', 'arm64'
    }
    flavorDimensions 'tier'
    productFlavors {
        free {
            dimension 'tier'
            // You can override the default selection at the product flavor
            // level by configuring another missingDimensionStrategy property
            // for the "minApi" dimension.
翻譯後：
您可以覆蓋產品口味的預設選擇，通過配置另一個missingDimensionStrategy屬性進行級別 //用於“ minApi”維度
            missingDimensionStrategy 'minApi', 'minApi23', 'minApi18'
        }
        paid {}
    }
}

####遠端程式碼庫
當您的依賴項不是本地庫或檔案樹時，Gradle 會在build.gradle檔案的repositories程式碼塊中指定的所有線上程式碼庫中查詢相關檔案。各個程式碼庫的列出順序決定了 Gradle 在這些程式碼庫中搜索各個專案依賴項的順序。例如，如果從程式碼庫 A 和 B 均可獲得某個依賴項，而您先列出了程式碼庫 A，則 Gradle 會從程式碼庫 A 下載該依賴項。

預設情況下，新的 Android Studio 專案會將Google 的 Maven 程式碼庫和 JCenter 指定為專案的頂級build.gradle檔案中的程式碼庫位置，如下所示

allprojects {
    repositories {
        google()
        jcenter()
    }
}

如果您要從 Maven 中央程式碼庫獲取某些內容，則新增 mavenCentral()；對於原生代碼庫，則使用 mavenLocal()：

allprojects {
    repositories {
        google()
        jcenter()
        mavenCentral()
        mavenLocal()
    }
}

或者，您也可以按如下方式宣告特定的 Maven 或 Ivy 程式碼庫：

    repositories {
        maven {
            url "https://repo.example.com/maven2"
        }
        maven {
            url "file://local/repo/"
        }
        ivy {
            url "https://repo.example.com/ivy"
        }
    }
}

如需瞭解詳情，請參閱Gradle 程式碼庫指南。

###Google 的 Maven 程式碼庫
Google 的 Maven 程式碼庫中提供了以下 Android 庫的最新版本：

• Android 支援庫
• 架構元件庫
• 約束佈局庫
• AndroidX 測試
• 資料繫結庫
• Android 免安裝應用庫
• Wear OS
• Google Play 服務
• Google Play 結算庫
• Firebase

您可以在Google 的 Maven 程式碼庫索引中檢視所有可用的工件（如需瞭解以程式設計方式訪問，請參閱下文）。

如需將其中某個庫新增到您的 build 中，請在頂級build.gradle檔案中包含 Google 的 Maven 程式碼庫：

maven :專家
allprojects {
    repositories {
        google()

        // If you're using a version of Gradle lower than 4.1, you must instead use:
        // maven {
        //     url 'https://maven.google.com'
        // }
翻譯後:
如果您使用的Gradle版本低於4.1，則必須使用： maven{ url “ https://maven.google.com” //} //備用網址是'https://dl.google.com/dl/android/maven2
        // An alternative URL is 'https://dl.google.com/dl/android/maven2/'
    }
}

然後，將所需的庫新增到模組的dependencies程式碼塊中。例如，appcompat 庫如下所示

    implementation 'com.android.support:appcompat-v7:28.0.0'
}

不過，如果您在嘗試使用舊版上述庫時依賴項失敗，則表明 Maven 程式碼庫中未提供該版本，您必須從離線程式碼庫獲取該庫。
####以程式設計方式訪問
如需以程式設計方式訪問 Google 的 Maven 工件，您可以從 maven.google.com/master-index.xml 獲取工件組的 XML 列表。然後，您可以從以下位置檢視任意組的庫名稱和版本資訊：

maven.google.com/group_path/group-index.xml

例如，android.arch.lifecycle 組中的庫就列在 maven.google.com/android/arch/lifecycle/group-index.xml 中。

您也可以從以下位置下載 POM 和 JAR 檔案：

maven.google.com/group_path/library/version/library-version.ext

例如：maven.google.com/android/arch/lifecycle/compiler/1.0.0/compiler-1.0.0.pom。

####SDK 管理器中的離線程式碼庫
對於無法從 Google Maven 程式碼庫中獲得的庫（通常是舊版庫），您必須從 SDK 管理器下載離線 Google 程式碼庫軟體包。

然後，您可以照常將這些庫新增到 dependencies 程式碼塊中。

離線庫儲存在 android_sdk/extras/ 中。
####依賴項順序
依賴項的列出順序指明瞭每個庫的優先順序：第一個庫的優先順序高於第二個，第二個庫的優先順序高於第三個，依此類推。在合併資源或將清單元素從庫中合併到應用中時，此順序很重要。

例如，如果您的專案宣告以下內容：

• 依賴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。

如需詳細瞭解如何合併不同專案來源/依賴項的清單，請參閱合併多個清單檔案。