เพิ่มการพึ่งพิงบิวด์

ระบบบิลด์ Gradle ใน Android Studio ช่วยให้คุณรวมไบนารีภายนอกหรือ โมดูลไลบรารีอื่นๆ ไว้ในบิลด์เป็นทรัพยากร Dependency ได้ โดยขึ้นอยู่กับว่า อยู่ในเครื่องของคุณหรือในที่เก็บข้อมูลระยะไกล และระบบจะรวม การอ้างอิงแบบทรานซิทีฟที่ประกาศไว้โดยอัตโนมัติด้วย หน้านี้ อธิบายวิธีใช้ทรัพยากร Dependency กับโปรเจ็กต์ Android รวมถึงรายละเอียด เกี่ยวกับลักษณะการทำงานและการกำหนดค่าที่เฉพาะเจาะจงสำหรับ Android Gradle Plugin (AGP) ดูคำแนะนำเชิงแนวคิดเกี่ยวกับทรัพยากร Dependency ของ Gradle ได้ที่คำแนะนำ Gradle สำหรับการจัดการทรัพยากร Dependency แต่โปรดทราบว่าโปรเจ็กต์ Android ต้องใช้เฉพาะการกำหนดค่าทรัพยากร Dependency ที่กำหนดไว้ในหน้านี้เท่านั้น

เพิ่มทรัพยากร Dependency ของไลบรารีหรือปลั๊กอิน

วิธีที่ดีที่สุดในการเพิ่มและจัดการทรัพยากร Dependency ของบิลด์คือการใช้แคตตาล็อกเวอร์ชัน ซึ่งเป็นวิธีที่โปรเจ็กต์ใหม่ใช้โดยค่าเริ่มต้น ส่วนนี้ครอบคลุมการกำหนดค่าประเภทที่พบบ่อยที่สุด ที่ใช้สำหรับโปรเจ็กต์ Android โปรดดูตัวเลือกเพิ่มเติมในเอกสารประกอบของ Gradle ดูตัวอย่างแอปที่ใช้แคตตาล็อกเวอร์ชันได้ที่ Now in Android หากคุณตั้งค่าการขึ้นต่อกันของบิลด์ไว้แล้ว โดยไม่มีแคตตาล็อกเวอร์ชันและมีโปรเจ็กต์แบบหลายโมดูล เราขอแนะนำให้ย้ายข้อมูล

ดูคำแนะนำเกี่ยวกับการเพิ่มและจัดการทรัพยากร Dependency เนทีฟ (ไม่พบบ่อย) ได้ที่ ทรัพยากร Dependency เนทีฟ

ในตัวอย่างต่อไปนี้ ระบบจะเพิ่มทรัพยากร Dependency แบบไบนารีระยะไกล (ไลบรารี Jetpack Macrobenchmark) ทรัพยากร Dependency ของโมดูลไลบรารีในเครื่อง (myLibrary) และทรัพยากร Dependency ของปลั๊กอิน (ปลั๊กอิน Android Gradle) ลงในโปรเจ็กต์ ขั้นตอนทั่วไปในการเพิ่มการอ้างอิงเหล่านี้ลงในโปรเจ็กต์มีดังนี้

1. เพิ่มนามแฝงสำหรับเวอร์ชันของทรัพยากร Dependency ที่ต้องการในส่วน [versions]ของไฟล์แคตตาล็อกเวอร์ชันที่ชื่อ libs.versions.toml (ในไดเรกทอรี gradle ในมุมมองโปรเจ็กต์หรือสคริปต์ Gradle ในมุมมอง Android)

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

   นามแฝงอาจมีขีดกลางหรือขีดล่างได้ โดยชื่อแทนเหล่านี้จะสร้างค่าที่ซ้อนกัน ซึ่งคุณอ้างอิงได้ในสคริปต์บิลด์ การอ้างอิงจะเริ่มต้นด้วยชื่อแคตตาล็อก ซึ่งเป็นส่วน libs ของ libs.versions.toml เมื่อใช้แคตตาล็อกเวอร์ชันเดียว เราขอแนะนำให้คงค่าเริ่มต้นของ "libs" ไว้

2. เพิ่มนามแฝงสำหรับทรัพยากร Dependency ในส่วน [libraries] (สำหรับไบนารีระยะไกลหรือโมดูลไลบรารีในเครื่อง) หรือ [plugins] (สำหรับปลั๊กอิน) ของไฟล์ 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" }
   

   ไลบรารีบางรายการมีอยู่ใน Bill of Materials (BOM) ที่เผยแพร่แล้ว ซึ่งจัดกลุ่มตระกูลของไลบรารีและเวอร์ชันของไลบรารีเหล่านั้น คุณสามารถรวม BOM ไว้ใน แคตตาล็อกเวอร์ชันและไฟล์บิลด์ แล้วให้ BOM จัดการเวอร์ชันเหล่านั้นให้ คุณได้ ดูรายละเอียดได้ที่การใช้ Bill of Materials

3. เพิ่มการอ้างอิงไปยังนามแฝงของการอ้างอิงในสคริปต์บิลด์ของโมดูลที่ต้องมีการอ้างอิง แปลงขีดล่างและขีดกลางของชื่อแทนเป็นจุดเมื่ออ้างอิงจากสคริปต์บิลด์ สคริปต์บิลด์ระดับโมดูล จะมีลักษณะดังนี้

   Kotlin

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }

   ดึงดูด

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

   การอ้างอิงปลั๊กอินจะมี plugins ต่อท้ายชื่อแคตตาล็อก และการอ้างอิงเวอร์ชันจะมี versions ต่อท้ายชื่อแคตตาล็อก (การอ้างอิงเวอร์ชันไม่ค่อยพบเห็น ดูตัวอย่างการอ้างอิงเวอร์ชันได้ที่การอ้างอิงที่มีหมายเลขเวอร์ชันเดียวกัน) การอ้างอิงไลบรารีไม่มีlibraries ตัวระบุ ดังนั้นคุณจึงใช้ versions หรือ plugins ที่จุดเริ่มต้นของ นามแฝงไลบรารีไม่ได้

กำหนดค่าทรัพยากร Dependency

ภายในบล็อก dependencies คุณสามารถประกาศทรัพยากร Dependency ของไลบรารีโดยใช้การกำหนดค่าทรัพยากร Dependencyหลายแบบ (เช่น implementation ที่แสดง ก่อนหน้านี้) การกำหนดค่าทรัพยากร Dependency แต่ละรายการจะให้คำสั่งที่แตกต่างกันแก่ Gradle เกี่ยวกับวิธีใช้ทรัพยากร Dependency ตารางต่อไปนี้อธิบายการกำหนดค่าแต่ละรายการที่คุณใช้สำหรับ Dependency ในโปรเจ็กต์ 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')
}

กำหนดค่าทรัพยากร Dependency สำหรับตัวแปรบิลด์ที่เฉพาะเจาะจง

การกำหนดค่าก่อนหน้าทั้งหมดจะใช้การขึ้นต่อกันกับตัวแปรบิลด์ทั้งหมด หากต้องการประกาศทรัพยากร Dependency สำหรับชุดซอร์สของตัวแปรบิลด์ที่เฉพาะเจาะจงเท่านั้น หรือสำหรับชุดซอร์สสำหรับการทดสอบ คุณต้องใช้อักษรตัวพิมพ์ใหญ่ในชื่อการกำหนดค่า และนำหน้าด้วยชื่อของตัวแปรบิลด์หรือชุดซอร์สสำหรับการทดสอบ

เช่น หากต้องการเพิ่มทรัพยากร Dependency ไบนารีระยะไกลเฉพาะในเวอร์ชันผลิตภัณฑ์ "ฟรี" โดยใช้การกำหนดค่า implementation ให้ใช้การกำหนดค่าต่อไปนี้

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

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

อย่างไรก็ตาม หากต้องการเพิ่มทรัพยากร Dependency สำหรับตัวแปรที่รวมเวอร์ชันผลิตภัณฑ์และประเภทบิลด์ คุณต้องเริ่มต้นชื่อการกำหนดค่าดังนี้

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

หากต้องการเพิ่มทรัพยากร Dependency 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'.

ลำดับการขึ้นต่อกัน

ลำดับที่คุณแสดงรายการทรัพยากรที่ขึ้นต่อกันจะบ่งบอกถึงลำดับความสำคัญของแต่ละรายการ เช่น ไลบรารีแรกมีลำดับความสำคัญสูงกว่าไลบรารีที่ 2 และไลบรารีที่ 2 มีลำดับความสำคัญสูงกว่าไลบรารีที่ 3 ลำดับนี้มีความสำคัญในกรณีที่ผสานรวมทรัพยากรหรือผสานรวมองค์ประกอบของไฟล์ Manifest เข้ากับแอปจากไลบรารี

เช่น หากโปรเจ็กต์ประกาศสิ่งต่อไปนี้

• การขึ้นต่อกันของ LIB_A และ LIB_B (ตามลำดับ)
• และ LIB_A ขึ้นอยู่กับ LIB_C และ LIB_D (ตามลำดับ)
• และ LIB_B ยังขึ้นอยู่กับ LIB_C ด้วย

จากนั้นลำดับทรัพยากร Dependency แบบราบจะเป็นดังนี้

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีผสานไฟล์ Manifest จากแหล่งที่มาหรือการอ้างอิงของโปรเจ็กต์ต่างๆ ได้ที่ ผสานไฟล์ Manifest หลายไฟล์

ข้อมูลทรัพยากร Dependency สำหรับ Play Console

เมื่อสร้างแอป AGP จะรวมข้อมูลเมตาที่อธิบายทรัพยากร Dependency ของไลบรารี ที่คอมไพล์ลงในแอปของคุณ เมื่ออัปโหลดแอป Play Console จะตรวจสอบข้อมูลเมตานี้เพื่อแจ้งเตือนปัญหาที่ทราบเกี่ยวกับ SDK และ ทรัพยากร Dependency ที่แอปใช้ และในบางกรณีจะให้ความคิดเห็นที่นำไปใช้ได้จริงเพื่อ แก้ไขปัญหาเหล่านั้น

ระบบจะบีบอัดข้อมูล เข้ารหัสด้วยคีย์การลงนามของ Google Play และจัดเก็บไว้ใน บล็อกการลงนามของแอปเวอร์ชันที่เผยแพร่ เราขอแนะนำให้เก็บไฟล์การอ้างอิงนี้ไว้เพื่อประสบการณ์การใช้งานที่ปลอดภัยและดีของผู้ใช้ คุณเลือกไม่ใช้ได้โดยใส่บล็อก ต่อไปนี้ dependenciesInfo ในไฟล์ build.gradle.kts ของโมดูล

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับนโยบายและปัญหาที่อาจเกิดขึ้นกับทรัพยากร Dependency ได้ที่ หน้าการสนับสนุนของเราเกี่ยวกับ การใช้ SDK ของบุคคลที่สามในแอป

ข้อมูลเชิงลึกเกี่ยวกับ SDK

Android Studio จะแสดงคำเตือนของเครื่องมือวิเคราะห์ซอร์สโค้ดในไฟล์แคตตาล็อกเวอร์ชันและกล่องโต้ตอบโครงสร้างโปรเจ็กต์สำหรับ SDK สาธารณะในดัชนี SDK ของ Google Play เมื่อมีปัญหาต่อไปนี้

• ผู้เขียน SDK ได้ทำเครื่องหมาย SDK ว่าล้าสมัย
• SDK ละเมิดนโยบายของ Play
• SDK มีช่องโหว่ด้านความปลอดภัยที่ทราบ
• ผู้เขียนได้เลิกใช้งาน SDK เหล่านี้แล้ว

คำเตือนเป็นสัญญาณที่บ่งบอกว่าคุณควรอัปเดตทรัพยากร Dependency เหล่านั้น เนื่องจาก การใช้เวอร์ชันที่ล้าสมัยอาจทำให้คุณเผยแพร่ไปยัง Google Play Console ในอนาคตไม่ได้

เพิ่มการพึ่งพาบิลด์โดยไม่ใช้แคตตาล็อกเวอร์ชัน

เราขอแนะนำให้ใช้แคตตาล็อกเวอร์ชันเพื่อเพิ่มและจัดการการอ้างอิง แต่โปรเจ็กต์ที่เรียบง่ายอาจไม่จำเป็นต้องใช้ ตัวอย่างไฟล์บิลด์ที่ไม่ได้ใช้แคตตาล็อกเวอร์ชันมีดังนี้

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

ไฟล์บิลด์นี้ประกาศทรัพยากร Dependency ในไลบรารี "app-magic" เวอร์ชัน 12.3 ภายในกลุ่มเนมสเปซ "com.example.android" การประกาศทรัพยากร Dependency ของไบนารีระยะไกล เป็นรูปแบบย่อของรายการต่อไปนี้

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

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

ไฟล์บิลด์ยังประกาศการขึ้นต่อโมดูลไลบรารี Android ชื่อ "mylibrary" ด้วย ซึ่งชื่อนี้ต้องตรงกับชื่อไลบรารีที่กำหนดด้วย include: ในไฟล์ settings.gradle.kts เมื่อคุณสร้างแอป ระบบบิลด์จะคอมไพล์โมดูลไลบรารีและแพ็กเนื้อหาที่คอมไพล์แล้วที่ได้ในแอป

ไฟล์บิลด์ยังประกาศทรัพยากร Dependency ในปลั๊กอิน Android Gradle (com.application.android) ด้วย หากมีหลายโมดูลที่ใช้ปลั๊กอินเดียวกัน คุณจะมีปลั๊กอินได้เพียงเวอร์ชันเดียวในคลาสพาธบิลด์ ในทุกโมดูล แทนที่จะระบุเวอร์ชันในสคริปต์บิลด์ของแต่ละโมดูล คุณควรรวมทรัพยากร Dependency ของปลั๊กอินไว้ในสคริปต์บิลด์รูทพร้อมกับเวอร์ชัน และระบุว่าไม่ต้องใช้ การเพิ่ม 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'
}