Thêm phần phụ thuộc của bản dựng

Hệ thống xây dựng Gradle trong Android Studio cho phép bạn đưa các thành phần bên ngoài tệp nhị phân hoặc mô-đun thư viện khác vào bản dựng dưới dạng phần phụ thuộc. Các phần phụ thuộc có thể nằm trên máy hoặc trong một kho lưu trữ từ xa, đồng thời các phần phụ thuộc bắc cầu mà các phần phụ thuộc đó khai báo cũng tự động được đưa vào. Trang này mô tả cách sử dụng các phần phụ thuộc trong dự án Android, bao gồm chi tiết về các hành vi và cấu hình dành riêng cho trình bổ trợ Android cho Gradle (AGP). Để được hướng dẫn khái niệm chuyên sâu hơn về phần phụ thuộc Gradle, bạn cũng nên xem Hướng dẫn quản lý phần phụ thuộc Gradle nhưng hãy nhớ rằng dự án Android của bạn chỉ được sử dụng các Cấu hình phần phụ thuộc được xác định trên trang này.

Thận trọng: Khi chỉ định các phần phụ thuộc, bạn không nên sử dụng số phiên bản động, chẳng hạn như 'com.android.tools.build:gradle:3.+'. Việc sử dụng tính năng này có thể gây ra cập nhật phiên bản không mong muốn, khó giải quyết sự khác biệt về phiên bản và sẽ mang lại hiệu suất kém.

Thêm phần phụ thuộc trình bổ trợ hoặc thư viện

Cách tốt nhất để thêm và quản lý các phần phụ thuộc của bản dựng là sử dụng danh mục phiên bản, mà các dự án mới sử dụng theo mặc định. Phần này đề cập đến các nguyên tắc phổ biến nhất các loại cấu hình dùng cho các dự án Android; tham chiếu đến Tài liệu về Gradle để có thêm lựa chọn. Để xem ví dụ về một ứng dụng sử dụng danh mục phiên bản, hãy xem Now in Android. Nếu bạn đã thiết lập phần phụ thuộc của bản dựng không có danh mục phiên bản và có một dự án nhiều mô-đun, bạn nên di chuyển.

Để xem hướng dẫn về cách thêm và quản lý các phần phụ thuộc gốc (không phổ biến), hãy xem Phần phụ thuộc gốc.

Trong ví dụ sau, chúng ta thêm tệp nhị phân từ xa phần phụ thuộc (ứng dụng Jetpack Macrobenchmark thư viện), mô-đun thư viện cục bộ phần phụ thuộc (myLibrary) và một trình bổ trợ phần phụ thuộc (trình bổ trợ Android cho Gradle) vào dự án của chúng ta. Sau đây là những thông tin chung các bước để thêm những phần phụ thuộc này vào dự án của bạn:

Lưu ý: Bạn có thể khai báo danh mục phiên bản trong phần cài đặt , nhưng bạn nên sử dụng một tệp toml riêng biệt để được hỗ trợ thêm về mã các đề xuất và đánh dấu nổi bật của Android Studio.

1. Thêm bí danh cho phiên bản của phần phụ thuộc mà bạn muốn trong Phần [versions] của tệp danh mục phiên bản, có tên là libs.versions.toml (trong thư mục gradle trong Chế độ xem Project (Dự án) hoặc Gradle Scripts (Tập lệnh Gradle) trong chế độ xem Android):

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   Bí danh có thể bao gồm dấu gạch ngang hoặc dấu gạch dưới. Các bí danh này tạo ra các giá trị lồng nhau mà bạn có thể tham khảo trong tập lệnh bản dựng. Các tham chiếu bắt đầu bằng tên của danh mục, phần libs của libs.versions.toml. Thời gian khi sử dụng một danh mục phiên bản duy nhất, bạn nên giữ nguyên giá trị mặc định của "libs".

2. Thêm bí danh cho phần phụ thuộc trong [libraries] (cho tệp nhị phân từ xa hoặc mô-đun thư viện cục bộ) hoặc [plugins] (dành cho trình bổ trợ) của tệp libs.versions.toml.

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

   Một số thư viện có trong Bảng kê khai thành phần (BOM) đã được xuất bản nhóm các họ thư viện và phiên bản của chúng. Bạn có thể thêm Bảng kê khai thành phần trong danh mục phiên bản và tệp bản dựng, đồng thời để Google quản lý các phiên bản đó cho bạn. Xem Sử dụng Bảng kê khai thành phần để biết chi tiết.

3. Thêm mục tham chiếu đến bí danh phần phụ thuộc vào tập lệnh bản dựng của mô-đun yêu cầu phần phụ thuộc. Chuyển đổi bí danh dấu gạch dưới và dấu gạch ngang vào dấu chấm khi bạn tham chiếu mã từ một tập lệnh bản dựng. Tập lệnh bản dựng cấp mô-đun sẽ có dạng như sau:

   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
   }
   

   Các mục tham chiếu đến trình bổ trợ bao gồm plugins sau tên danh mục, và các phần tham chiếu phiên bản bao gồm versions sau tên danh mục (phiên bản tham chiếu không phổ biến; xem phần phụ thuộc có cùng số phiên bản để tham khảo ví dụ về tham chiếu phiên bản.) Thư viện tệp đối chiếu không bao gồm bộ hạn định libraries, nên bạn không thể sử dụng versions hoặc plugins ở đầu thư viện bí danh.

Định cấu hình phần phụ thuộc

Bên trong khối dependencies, bạn có thể khai báo phần phụ thuộc thư viện bằng cách sử dụng trong số nhiều cấu hình phần phụ thuộc (chẳng hạn như implementation được hiển thị) trước đó). Mỗi cấu hình phần phụ thuộc cung cấp cho Gradle các hướng dẫn khác nhau về cách sử dụng phần phụ thuộc. Bảng sau đây mô tả từng cấu hình phần phụ thuộc có thể sử dụng trong dự án Android.

Cấu hình	Hành vi
implementation	Gradle thêm phần phụ thuộc vào classpath biên dịch và đóng gói phần phụ thuộc đó vào đầu ra của bản dựng. Khi mô-đun định cấu hình phần phụ thuộc implementation, đó là cho Gradle biết rằng bạn không muốn mô-đun làm rò rỉ các mô-đun khác vào thời gian biên dịch. Đó là phần phụ thuộc không được cung cấp cho các mô-đun khác phụ thuộc vào . Sử dụng cấu hình phần phụ thuộc này thay vì api có thể giúp cải thiện đáng kể thời gian xây dựng vì công cụ này giúp giảm số lượng mô-đun mà hệ thống xây dựng cần để biên dịch lại. Ví dụ: nếu implementation phần phụ thuộc thay đổi API, Gradle chỉ biên dịch lại phần phụ thuộc đó và các mô-đun phụ thuộc trực tiếp vào mã đó. Hầu hết ứng dụng và thử nghiệm các mô-đun nên sử dụng cấu hình này.
api	Gradle thêm phần phụ thuộc vào đường dẫn lớp biên dịch và đầu ra bản dựng. Khi một mô-đun có phần phụ thuộc api, đó là cho Gradle biết rằng mô-đun này muốn xuất bắc cầu phần phụ thuộc đó với các mô-đun khác, để họ truy cập được tại cả thời gian chạy và thời gian biên dịch. Hãy thận trọng và chỉ sử dụng cấu hình này với những phần phụ thuộc bạn cần xuất chuyển đổi sang những người tiêu dùng cao cấp khác. Nếu một Phần phụ thuộc api thay đổi API bên ngoài, Gradle biên dịch lại tất cả các mô-đun có quyền truy cập vào phần phụ thuộc đó khi biên dịch bất cứ lúc nào. Việc có một số lượng lớn các phần phụ thuộc api có thể sẽ làm tăng đáng kể thời gian xây dựng. Trừ phi bạn muốn hiển thị thành một mô-đun riêng biệt, các mô-đun thư viện phải sử dụng các phần phụ thuộc implementation.
compileOnly	Gradle chỉ thêm phần phụ thuộc vào đường dẫn lớp biên dịch (tức là không được thêm vào kết quả của bản dựng). Điều này rất hữu ích khi tạo một mô-đun Android và cần có phần phụ thuộc trong quá trình biên dịch, nhưng không bắt buộc phải thêm phần phụ thuộc này tại thời gian chạy. Cho Ví dụ: nếu phụ thuộc vào một thư viện chỉ chứa chú giải thời gian biên dịch (thường dùng để tạo mã nhưng thường không được đưa vào kết quả của bản dựng), bạn có thể đánh dấu thư viện đó là compileOnly. Nếu sử dụng cấu hình này, bạn phải đưa điều kiện thời gian chạy vào mô-đun thư viện để kiểm tra xem phần phụ thuộc có sẵn hay không, sau đó thay đổi linh hoạt hành vi của mô-đun để vẫn có thể hoạt động nếu như phần phụ thuộc không được cung cấp. Điều này giúp giảm kích thước của ứng dụng cuối cùng bằng cách không thêm các phần phụ thuộc bắc cầu không quan trọng. Lưu ý: Bạn không thể sử dụng compileOnly với các phần phụ thuộc Android Archive (AAR).
runtimeOnly	Gradle chỉ thêm phần phụ thuộc vào đầu ra của bản dựng, để sử dụng trong thời gian chạy. Điều này sẽ không được thêm vào đường dẫn lớp biên dịch. Thao tác này hiếm khi được sử dụng trên Android, nhưng thường được sử dụng trong máy chủ để cung cấp cách triển khai ghi nhật ký. Ví dụ: một có thể sử dụng API ghi nhật ký không bao gồm trong quá trình triển khai. Người dùng thư viện đó có thể thêm thư viện đó làm Phần phụ thuộc implementation và bao gồm phần phụ thuộc Phần phụ thuộc runtimeOnly để ghi nhật ký thực tế để sử dụng.
ksp kapt annotationProcessor	Các cấu hình này cung cấp cho các thư viện xử lý chú giải và các ký hiệu khác trong mã trước khi biên dịch. Thông thường, xác thực mã của bạn hoặc tạo mã bổ sung, giúp giảm mã bạn cần cần viết. Để thêm một phần phụ thuộc như vậy, bạn phải thêm phần phụ thuộc đó vào classpath trình xử lý chú giải bằng cách sử dụng cấu hình ksp, kapt hoặc annotationProcessor. Sử dụng các cấu hình cải thiện hiệu suất của bản dựng bằng cách tách trình biên dịch đường dẫn lớp ( classpath) trong classpath của trình xử lý chú giải. Nếu Gradle tìm thấy trình xử lý chú giải trên đường dẫn lớp biên dịch, công cụ này sẽ vô hiệu hoá tránh biên dịch, vốn tác động tiêu cực đến thời gian xây dựng (Gradle 5.0 trở lên bỏ qua trình xử lý chú giải được tìm thấy trên trình biên dịch đường dẫn lớp). Trình bổ trợ Android cho Gradle giả định một phần phụ thuộc là trình xử lý chú thích nếu tệp JAR của phần phụ thuộc đó có chứa tệp sau: META-INF/services/javax.annotation.processing.Processor Nếu trình bổ trợ phát hiện một trình xử lý chú thích trên đường dẫn lớp biên dịch, một lỗi bản dựng sẽ xảy ra. ksp là một Trình xử lý biểu tượng Kotlin và được chạy bởi Trình biên dịch Kotlin. kapt và apt là các công cụ riêng biệt xử lý chú giải trước khi trình biên dịch Kotlin hoặc Java thực thi. Khi quyết định sử dụng cấu hình nào, hãy cân nhắc sau: Nếu một bộ xử lý có thể dùng như một Bộ xử lý biểu tượng Kotlin, hãy sử dụng nó dưới dạng phần phụ thuộc ksp. Xem bài viết Di chuyển từ kapt sang ksp để biết thông tin chi tiết về cách sử dụng Bộ xử lý biểu tượng Kotlin. Nếu bộ xử lý không hoạt động như một Bộ xử lý biểu tượng Kotlin: Nếu dự án của bạn có chứa nguồn Kotlin (nhưng cũng có thể bao gồm nguồn Java), sử dụng kapt để đưa công nghệ này vào. Nếu dự án của bạn chỉ sử dụng nguồn Java, hãy sử dụng annotationProcessor để bao gồm chế độ xem này. Để biết thêm thông tin về cách sử dụng trình xử lý chú giải, xem Thêm trình xử lý chú giải.
lintChecks	Sử dụng cấu hình này để thêm một thư viện chứa công cụ tìm lỗi mã nguồn các bước kiểm tra mà bạn muốn Gradle thực thi khi tạo ứng dụng Android dự án. Xin lưu ý rằng các AAR chứa tệp lint.jar sẽ tự động chạy các bước kiểm tra được xác định trong tệp lint.jar đó; bạn không cần thêm phần phụ thuộc lintChecks rõ ràng. Nhờ vậy, bạn có thể xác định các thư viện và quá trình kiểm tra tìm lỗi mã nguồn liên kết trong một phần phụ thuộc, đảm bảo rằng các bước kiểm tra của bạn sẽ được chạy khi người tiêu dùng sử dụng thư viện của bạn.
lintPublish	Sử dụng cấu hình này trong các dự án thư viện Android để đưa các phần kiểm tra tìm lỗi mã nguồn mà bạn muốn Gradle biên dịch vào một tệp lint.jar và gói trong AAR của bạn. Điều này khiến các dự án sử dụng AAR của bạn cũng áp dụng phần kiểm tra lỗi mã nguồn đó. Nếu trước đó bạn đã sử dụng cấu hình phần phụ thuộc lintChecks để đưa các phần kiểm tra tìm lỗi mã nguồn vào trong AAR đã phát hành, thì bạn cần di chuyển các phần phụ thuộc đó để sử dụng cấu hình lintPublish. Kotlin 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")) } Groovy 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') }

Định cấu hình phần phụ thuộc cho một biến thể bản dựng cụ thể

Tất cả cấu hình ở trên đều áp dụng các phần phụ thuộc cho tất cả biến thể bản dựng. Nếu thay vào đó, bạn muốn khai báo phần phụ thuộc chỉ cho một bản dựng cụ thể nhóm tài nguyên biến thể hoặc cho một nguồn thử nghiệm tập hợp, bạn phải viết hoa cấu hình và thêm tiền tố là tên của biến thể bản dựng hoặc nhóm tài nguyên kiểm thử.

Ví dụ: để chỉ thêm phần phụ thuộc tệp nhị phân từ xa vào thuộc tính "free" (miễn phí) sản phẩm phiên bản bằng cấu hình implementation, hãy sử dụng:

Kotlin

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

Groovy

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

Tuy nhiên, nếu bạn muốn thêm phần phụ thuộc cho một biến thể kết hợp một sản phẩm phiên bản và loại bản dựng, thì bạn phải khởi tạo tên cấu hình:

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

Để thêm các phần phụ thuộc implementation cho quy trình kiểm thử cục bộ và quy trình kiểm thử đo lường, bạn có thể xem đoạn mã sau:

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

Tuy nhiên, một số cấu hình nhất định không có ý nghĩa trong trường hợp này. Chẳng hạn, vì các mô-đun khác không thể phụ thuộc vào androidTest, nên bạn sẽ nhận được cảnh báo sau nếu sử dụng cấu hình androidTestApi:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Thứ tự phần phụ thuộc

Thứ tự liệt kê các phần phụ thuộc của bạn phản ánh rõ mức độ ưu tiên: thư viện đầu tiên có mức độ ưu tiên cao hơn thư viện thứ hai, thư viện thứ hai có mức độ ưu tiên cao hơn thư viện thứ ba, v.v. Thứ tự này rất quan trọng trong trường hợp tài nguyên được hợp nhất hoặc các phần tử tệp kê khai được hợp nhất vào trong ứng dụng từ thư viện.

Ví dụ: nếu dự án của bạn khai báo như sau:

• Phần phụ thuộc trên LIB_A và LIB_B (theo thứ tự đó)
• Và LIB_A phụ thuộc vào LIB_C và LIB_D (theo thứ tự đó)
• Và LIB_B cũng phụ thuộc vào LIB_C

Khi đó, thứ tự phần phụ thuộc cố định sẽ như sau:

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

Điều này đảm bảo rằng cả LIB_A và LIB_B đều có thể ghi đè LIB_C; và LIB_D vẫn sẽ có mức độ ưu tiên cao hơn LIB_B vì LIB_A (phụ thuộc vào LIB_D) có mức độ ưu tiên cao hơn LIB_B.

Để biết thêm thông tin về cách hợp nhất các tệp kê khai từ nhiều nguồn/phần phụ thuộc của các dự án khác nhau, hãy xem Hợp nhất nhiều tệp kê khai.

Thông tin phần phụ thuộc dành cho Play Console

Khi xây dựng ứng dụng, AGP sẽ thêm siêu dữ liệu mô tả thư viện được biên dịch vào ứng dụng của bạn. Khi tải ứng dụng lên, Play Console sẽ kiểm tra siêu dữ liệu này để đưa ra cảnh báo về các vấn đề đã biết liên quan đến SDK và các phần phụ thuộc mà ứng dụng của bạn sử dụng và trong một số trường hợp, cung cấp thông tin phản hồi thiết thực để giải quyết các vấn đề đó.

Dữ liệu được một khoá ký Google Play nén, mã hoá và lưu trữ trong khối ký của ứng dụng phát hành. Bạn nên giữ lại phần phụ thuộc này để cung cấp trải nghiệm người dùng an toàn và tích cực. Bạn có thể chọn không tham gia bằng cách thêm đang theo dõi dependenciesInfo trong tệp build.gradle.kts của mô-đun.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Để biết thêm thông tin về các chính sách cũng như vấn đề tiềm ẩn về phần phụ thuộc, hãy xem trang hỗ trợ của chúng tôi về Sử dụng SDK của bên thứ ba trong ứng dụng của bạn.

Thông tin chi tiết về SDK

Android Studio cho thấy các cảnh báo tìm lỗi mã nguồn trong tệp danh mục phiên bản và Project (Dự án) Hộp thoại cấu trúc dành cho các SDK công khai trong phần Chỉ mục SDK của Google Play khi các vấn đề sau xảy ra:

• Tác giả đánh dấu các SDK này là đã lỗi thời.
• Những SDK đó vi phạm các chính sách của Play.

Cảnh báo là tín hiệu cho biết bạn nên cập nhật các phần phụ thuộc đó, vì nếu dùng phiên bản lỗi thời, bạn có thể không phát hành được lên Google Play Google Play Console trong tương lai.

Thêm phần phụ thuộc của bản dựng mà không cần danh mục phiên bản

Bạn nên sử dụng danh mục phiên bản để thêm và quản lý các phần phụ thuộc, nhưng cách làm này đơn giản các dự án có thể không cần đến các mã này. Dưới đây là ví dụ về một tệp bản dựng không sử dụng danh mục phiên bản:

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

Tệp bản dựng này khai báo phần phụ thuộc trên phiên bản 12.3 của tệp "app-magic" thư viện, bên trong "com.example.android" nhóm không gian tên. Tệp nhị phân từ xa khai báo phần phụ thuộc là cách viết tắt của:

Kotlin

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

Groovy

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

Tệp bản dựng cũng khai báo phần phụ thuộc trên mô-đun thư viện Android có tên "mylibrary"; tên này phải khớp với tên thư viện được xác định với include: trong tệp settings.gradle.kts. Khi bạn tạo ứng dụng, hệ thống xây dựng biên dịch mô-đun thư viện và đóng gói nội dung kết quả biên dịch trong .

Tệp bản dựng cũng khai báo phần phụ thuộc trên trình bổ trợ Android cho Gradle (com.application.android). Nếu bạn có nhiều mô-đun sử dụng cùng một mô-đun trình bổ trợ, bạn chỉ có thể có một phiên bản trình bổ trợ duy nhất trên đường dẫn lớp bản dựng trên tất cả các mô-đun. Thay vì chỉ định phiên bản trong mỗi mô-đun tập lệnh bản dựng, bạn nên đưa phần phụ thuộc trình bổ trợ vào tập lệnh bản dựng gốc với phiên bản và chỉ ra rằng không áp dụng phiên bản đó. Việc thêm apply false cho biết Gradle cần lưu ý phiên bản trình bổ trợ nhưng không sử dụng trong bản dựng gốc. Thông thường, tập lệnh bản dựng gốc trống, ngoại trừ khối plugins này.

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
}

Nếu có dự án một mô-đun, bạn có thể chỉ định rõ phiên bản trong tập lệnh bản dựng cấp mô-đun và để trống tập lệnh bản dựng cấp dự án:

Kotlin

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

Groovy

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