เปิดใช้ multidex สำหรับแอปที่มีเมธอดกว่า 64,000 วิธี

หากแอปมี minSdk ของ API ระดับ 20 หรือต่ำกว่า และแอปและไลบรารีที่อ้างอิงมีเมธอดมากกว่า 65,536 รายการ คุณจะเห็นข้อผิดพลาดเกี่ยวกับบิลด์ต่อไปนี้ซึ่งบ่งบอกว่าแอปของคุณมีจำนวนเมธอดถึงขีดจำกัดของสถาปัตยกรรมบิลด์ Android

trouble writing output:
Too many field references: 131000; max is 65536.
You may try using --multi-dex option.

ระบบบิลด์เวอร์ชันเก่าจะรายงานข้อผิดพลาดที่ต่างออกไป ซึ่งบ่งบอกถึงปัญหาเดียวกัน

Conversion to Dalvik format failed:
Unable to execute dex: method ID not in [0, 0xffff]: 65536

เงื่อนไขข้อผิดพลาดเหล่านี้จะแสดงตัวเลขทั่วไป 65536 ตัวเลขนี้แสดงจํานวนการอ้างอิงทั้งหมดที่โค้ดสามารถเรียกใช้ได้ภายในไฟล์ไบต์โค้ด Dalvik Executable (DEX) ไฟล์เดียว หน้านี้จะอธิบายวิธีข้ามข้อจำกัดนี้ด้วยการเปิดใช้การกำหนดค่าแอปที่เรียกว่า multidex ซึ่งจะช่วยให้แอปของคุณสร้างและอ่านไฟล์ DEX ได้หลายไฟล์

เกี่ยวกับขีดจํากัดข้อมูลอ้างอิง 64 KB

ไฟล์แอป Android (APK) มีไฟล์ไบต์โค้ดที่เรียกใช้งานได้ในรูปแบบไฟล์ Dalvik Executable (DEX) ซึ่งมีโค้ดที่คอมไพล์แล้วซึ่งใช้เรียกใช้แอป ข้อกำหนดของ Dalvik Executable จำกัดจำนวนเมธอดทั้งหมดที่อ้างอิงได้ภายในไฟล์ DEX ไฟล์เดียวไว้ที่ 65,536 เมธอด ซึ่งรวมถึงเมธอดเฟรมเวิร์ก Android, เมธอดไลบรารี และเธอดในโค้ดของคุณเอง

ในบริบทของวิทยาการคอมพิวเตอร์ คําว่า กิโล หรือ K หมายถึง 1024 (หรือ 2^10) เนื่องจาก 65,536 เท่ากับ 64x1024 ขีดจํากัดนี้จึงเรียกว่า _ขีดจํากัดข้อมูลอ้างอิง 64K_

การรองรับ Multidex ก่อน Android 5.0

แพลตฟอร์มเวอร์ชันก่อน Android 5.0 (API ระดับ 21) ใช้รันไทม์ Dalvik ในการเรียกใช้โค้ดแอป โดยค่าเริ่มต้น Dalvik จะจำกัดแอปให้มีclasses.dexไฟล์ไบต์โค้ดไฟล์เดียวต่อ APK หากต้องการหลีกเลี่ยงข้อจำกัดนี้ ให้เพิ่มไลบรารี MultiDex ลงในไฟล์ build.gradle หรือ build.gradle.kts ระดับโมดูล ดังนี้

Groovy

dependencies {
    def multidex_version = "2.0.1"
    implementation "androidx.multidex:multidex:$multidex_version"
}

Kotlin

dependencies {
    val multidex_version = "2.0.1"
    implementation("androidx.multidex:multidex:$multidex_version")
}

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

ดูรายละเอียดเพิ่มเติมได้ที่ส่วนเกี่ยวกับวิธีกำหนดค่าแอปสำหรับ MultiDex

การรองรับ Multidex สำหรับ Android 5.0 ขึ้นไป

Android 5.0 (API ระดับ 21) ขึ้นไปใช้รันไทม์ที่เรียกว่า ART ซึ่งรองรับการโหลดไฟล์ DEX หลายไฟล์จากไฟล์ APK โดยกำเนิด ART จะทำการคอมไพล์ล่วงหน้าเมื่อติดตั้งแอป โดยสแกนหาไฟล์ classesN.dex และคอมไพล์เป็นไฟล์ OAT ไฟล์เดียวเพื่อให้อุปกรณ์ Android เรียกใช้ได้ ดังนั้น หาก minSdkVersion เป็น 21 ขึ้นไป ระบบจะเปิดใช้ MultiDex โดยค่าเริ่มต้นและคุณไม่จําเป็นต้องใช้คลัง MultiDex

ดูข้อมูลเพิ่มเติมเกี่ยวกับรันไทม์ของ Android 5.0 ได้ที่ Android Runtime (ART) และ Dalvik

หมายเหตุ: เมื่อเรียกใช้แอปโดยใช้ Android Studio ระบบจะเพิ่มประสิทธิภาพบิลด์สำหรับอุปกรณ์เป้าหมายที่คุณนำไปใช้งาน ซึ่งรวมถึงการเปิดใช้ MultiDex เมื่ออุปกรณ์เป้าหมายใช้ Android 5.0 ขึ้นไป เนื่องจากการเพิ่มประสิทธิภาพนี้จะมีผลเฉพาะเมื่อคุณติดตั้งใช้งานแอปโดยใช้ Android Studio คุณจึงอาจยังต้องกําหนดค่าบิลด์รุ่นสําหรับ MultiDex เพื่อหลีกเลี่ยงขีดจํากัด 64 KB

หลีกเลี่ยงขีดจํากัด 64 KB

ก่อนกำหนดค่าแอปเพื่อเปิดใช้การอ้างอิงเมธอด 64,000 รายการขึ้นไป ให้ทำตามขั้นตอนเพื่อลดจํานวนการอ้างอิงทั้งหมดที่โค้ดแอปเรียกใช้ ซึ่งรวมถึงเมธอดที่กําหนดโดยโค้ดแอปหรือไลบรารีที่รวมไว้

กลยุทธ์ต่อไปนี้จะช่วยคุณหลีกเลี่ยงไม่ให้เกินขีดจํากัดการอ้างอิงของ DEX

ตรวจสอบการพึ่งพาโดยตรงและแบบสื่อกลางของแอป

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

นำโค้ดที่ไม่ได้ใช้งานออกด้วย R8

เปิดใช้การลดขนาดโค้ดเพื่อเรียกใช้ R8 สำหรับบิลด์ที่เผยแพร่ เปิดใช้การลดขนาดเพื่อช่วยตรวจสอบว่าคุณไม่ได้จัดส่งโค้ดที่ไม่ได้ใช้ไปกับ APK หากกําหนดค่าการลดขนาดโค้ดอย่างถูกต้อง ก็จะนําโค้ดและทรัพยากรที่ไม่ได้ใช้งานออกจากทรัพยากร Dependency ได้ด้วย

การใช้เทคนิคเหล่านี้จะช่วยคุณลดขนาดโดยรวมของ APK และหลีกเลี่ยงความจำเป็นในการใช้ MultiDex ในแอป

กำหนดค่าแอปสำหรับ MultiDex

หมายเหตุ: หากตั้งค่า minSdkVersion เป็น 21 ขึ้นไป ระบบจะเปิดใช้ MultiDex โดยค่าเริ่มต้นและคุณไม่จําเป็นต้องใช้คลัง MultiDex

หากตั้งค่า minSdkVersion เป็น 20 หรือต่ำกว่า คุณต้องใช้ไลบรารี MultiDex และทำการแก้ไขต่อไปนี้ในโปรเจ็กต์แอป

1. แก้ไขไฟล์ build.gradle ระดับโมดูลเพื่อเปิดใช้ MultiDex และเพิ่มไลบรารี MultiDex เป็น Dependency ดังที่แสดงที่นี่

   Groovy

   android {
       defaultConfig {
           ...
           minSdkVersion 15 
           targetSdkVersion 33
           multiDexEnabled true
       }
       ...
   }
   
   dependencies {
       implementation "androidx.multidex:multidex:2.0.1"
   }
   

   Kotlin

   android {
       defaultConfig {
           ...
           minSdk = 15 
           targetSdk = 33
           multiDexEnabled = true
       }
       ...
   }
   
   dependencies {
       implementation("androidx.multidex:multidex:2.0.1")
   }
   

2. ทําอย่างใดอย่างหนึ่งต่อไปนี้ โดยขึ้นอยู่กับว่าคุณลบล้างคลาส Application หรือไม่

   • หากไม่ลบล้างคลาส Application ให้แก้ไขไฟล์ Manifest เพื่อตั้งค่า android:name ในแท็ก <application> ดังนี้

     <?xml version="1.0" encoding="utf-8"?>
     <manifest xmlns:android="http://schemas.android.com/apk/res/android"
         package="com.example.myapp">
         <application
                 android:name="androidx.multidex.MultiDexApplication" >
             ...
         </application>
     </manifest>
     

   • หากลบล้างApplication class ให้เปลี่ยนเป็นMultiDexApplication ดังนี้

     Kotlin

     class MyApplication : MultiDexApplication() {...}
     

     Java

     public class MyApplication extends MultiDexApplication { ... }
     

   • หากคุณลบล้างคลาส Application แต่เปลี่ยนคลาสพื้นฐานไม่ได้ ให้ลบล้างเมธอด attachBaseContext() และเรียกใช้ MultiDex.install(this) เพื่อเปิดใช้ MultiDex แทน

     Kotlin

     class MyApplication : SomeOtherApplication() {
     
         override fun attachBaseContext(base: Context) {
             super.attachBaseContext(base)
             MultiDex.install(this)
         }
     }
     

     Java

     public class MyApplication extends SomeOtherApplication {
       @Override
       protected void attachBaseContext(Context base) {
          super.attachBaseContext(base);
          MultiDex.install(this);
       }
     }
     

     ข้อควรระวัง: อย่าเรียกใช้ MultiDex.install() หรือโค้ดอื่นๆ ผ่านรีเฟล็กชันหรือ JNI ก่อนที่ MultiDex.install() จะเสร็จสมบูรณ์ การติดตาม Multidex จะไม่ติดตามการเรียกเหล่านั้น ซึ่งจะทำให้เกิดClassNotFoundExceptionหรือข้อผิดพลาดในการยืนยันเนื่องจากมีการแบ่งพาร์ติชันคลาสที่ไม่ถูกต้องระหว่างไฟล์ DEX

เมื่อคุณสร้างแอป เครื่องมือสร้างของ Android จะสร้างไฟล์ DEX หลัก (classes.dex) และไฟล์ DEX ที่รองรับ (classes2.dex, classes3.dex และอื่นๆ) ตามที่จำเป็น จากนั้นระบบการสร้างจะแพ็กเกจไฟล์ DEX ทั้งหมดไว้ใน APK

ขณะรันไทม์ MultiDex API จะใช้ตัวโหลดคลาสพิเศษเพื่อค้นหาเมธอดของคุณในไฟล์ DEX ทั้งหมดที่มีอยู่แทนที่จะค้นหาเฉพาะในไฟล์ classes.dex หลัก

ข้อจำกัดของคลัง MultiDex

ไลบรารี MultiDex มีข้อจำกัดบางประการที่ทราบ เมื่อรวมไลบรารีไว้ในการกำหนดค่าการสร้างแอป ให้พิจารณาสิ่งต่อไปนี้

• การติดตั้งไฟล์ DEX ในระหว่างการเริ่มต้นลงในพาร์ติชันข้อมูลของอุปกรณ์มีความซับซ้อนและอาจทำให้เกิดข้อผิดพลาด "แอปพลิเคชันไม่ตอบสนอง" (ANR) หากไฟล์ DEX รองมีขนาดใหญ่ หากต้องการหลีกเลี่ยงปัญหานี้ ให้เปิดใช้การลดขนาดโค้ดเพื่อลดขนาดไฟล์ DEX และนำโค้ดส่วนที่ไม่ได้ใช้ออก
• เมื่อใช้งานในเวอร์ชันก่อน Android 5.0 (API ระดับ 21) การใช้ MultiDex จะไม่เพียงพอต่อการแก้ปัญหาขีดจำกัดของ linearalloc (ปัญหา 37008143) ขีดจํากัดนี้เพิ่มขึ้นใน Android 4.0 (API ระดับ 14) แต่ก็ยังแก้ปัญหาได้ไม่สมบูรณ์

  ในเวอร์ชันที่ต่ำกว่า Android 4.0 คุณอาจถึงขีดจำกัดของ linearalloc ก่อนถึงขีดจำกัดของดัชนี DEX ดังนั้น หากคุณกําหนดเป้าหมาย API ระดับต่ำกว่า 14 ให้ทดสอบอย่างละเอียดในแพลตฟอร์มเวอร์ชันเหล่านั้น เนื่องจากแอปอาจมีปัญหาเมื่อเริ่มต้นหรือเมื่อโหลดคลาสบางกลุ่ม

  การลดขนาดโค้ดอาจช่วยลดหรือขจัดปัญหาเหล่านี้ได้

ประกาศคลาสที่จำเป็นในไฟล์ DEX หลัก

เมื่อสร้างไฟล์ DEX แต่ละไฟล์สําหรับแอปแบบ MultiDex เครื่องมือสร้างจะทําการตัดสินใจที่ซับซ้อนเพื่อพิจารณาว่าต้องใช้คลาสใดในไฟล์ DEX หลักเพื่อให้แอปเริ่มทํางานได้สําเร็จ หากไม่ได้ระบุคลาสที่จําเป็นในระหว่างการเริ่มต้นในไฟล์ DEX หลัก แอปจะขัดข้องพร้อมข้อผิดพลาด java.lang.NoClassDefFoundError

เครื่องมือสร้างจะจดจำเส้นทางโค้ดสําหรับโค้ดที่เข้าถึงจากโค้ดแอปโดยตรง อย่างไรก็ตาม ปัญหานี้อาจเกิดขึ้นเมื่อเส้นทางโค้ดมองเห็นได้น้อยลง เช่น เมื่อไลบรารีที่คุณใช้มีความซับซ้อน ตัวอย่างเช่น หากโค้ดใช้การตรวจสอบตนเองหรือการเรียกใช้เมธอด Java จากโค้ดเนทีฟ ระบบอาจไม่รู้จักคลาสเหล่านั้นว่าจำเป็นในไฟล์ DEX หลัก

หากได้รับ java.lang.NoClassDefFoundError คุณต้องระบุคลาสเพิ่มเติมที่จำเป็นในไฟล์ DEX หลักด้วยตนเองโดยประกาศคลาสเหล่านั้นด้วยพร็อพเพอร์ตี้ multiDexKeepProguard ในประเภทบิลด์ หากมีคลาสที่ตรงกันในไฟล์ multiDexKeepProguard ระบบจะเพิ่มคลาสนั้นลงในไฟล์ DEX หลัก

พร็อพเพอร์ตี้ multiDexKeepProguard

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

ไฟล์ที่คุณระบุใน multiDexKeepProguard ควรมีตัวเลือก -keep ในไวยากรณ์ ProGuard ที่ถูกต้อง เช่น -keep com.example.MyClass.class คุณสามารถสร้างไฟล์ชื่อ multidex-config.pro ที่ดูดังนี้

-keep class com.example.MyClass
-keep class com.example.MyClassToo

หากต้องการระบุคลาสทั้งหมดในแพ็กเกจ ไฟล์จะมีลักษณะดังนี้

-keep class com.example.** { *; } // All classes in the com.example package

จากนั้นคุณสามารถประกาศไฟล์นั้นสําหรับประเภทบิลด์ ดังนี้

Groovy

android {
    buildTypes {
        release {
            multiDexKeepProguard file('multidex-config.pro')
            ...
        }
    }
}

Kotlin

android {
    buildTypes {
        getByName("release") {
            multiDexKeepProguard = file("multidex-config.pro")
            ...
        }
    }
}

เพิ่มประสิทธิภาพ multidex ในบิลด์สำหรับการพัฒนา

การกําหนดค่า MultiDex จะเพิ่มเวลาการประมวลผลการบิลด์อย่างมาก เนื่องจากระบบบิลด์ต้องตัดสินใจอย่างซับซ้อนว่าคลาสใดต้องรวมอยู่ในไฟล์ DEX หลักและคลาสใดสามารถรวมอยู่ในไฟล์ DEX รอง ซึ่งหมายความว่าบิลด์แบบเพิ่มโดยใช้ MultiDex มักจะใช้เวลานานขึ้นและอาจทำให้กระบวนการพัฒนาช้าลง

หากต้องการลดเวลาในการสร้างที่เพิ่มขึ้น ให้ใช้การแยกไฟล์ Dex ล่วงหน้าเพื่อนำเอาเอาต์พุต MultiDex มาใช้ซ้ำระหว่างการสร้าง การจัดทําไฟล์ DeX ล่วงหน้าใช้รูปแบบ ART ที่มีให้ใช้งานใน Android 5.0 (API ระดับ 21) ขึ้นไปเท่านั้น หากคุณใช้ Android Studio IDE จะใช้การแยกไฟล์ก่อนการคอมไพล์โดยอัตโนมัติเมื่อคุณติดตั้งใช้งานแอปในอุปกรณ์ที่ใช้ Android 5.0 (API ระดับ 21) ขึ้นไป อย่างไรก็ตาม หากคุณเรียกใช้บิลด์ Gradle จากบรรทัดคำสั่ง คุณต้องตั้งค่า minSdkVersion เป็น 21 ขึ้นไปเพื่อเปิดใช้การแปลงไฟล์เป็นรูปแบบ Dex ล่วงหน้า

หากต้องการเก็บการตั้งค่าสำหรับบิลด์ที่ใช้งานจริง คุณสามารถสร้างแอป 2 เวอร์ชันโดยใช้ Flavor ของผลิตภัณฑ์ โดยเวอร์ชันหนึ่งมี Flavor การพัฒนาและอีกเวอร์ชันมี Flavor ของรุ่น โดยมีค่าสำหรับ minSdkVersion แตกต่างกัน ดังที่แสดง

Groovy

android {
    defaultConfig {
        ...
        multiDexEnabled true
        // The default minimum API level you want to support.
        minSdkVersion 15
    }
    productFlavors {
        // Includes settings you want to keep only while developing your app.
        dev {
            // Enables pre-dexing for command-line builds. When using
            // Android Studio 2.3 or higher, the IDE enables pre-dexing
            // when deploying your app to a device running Android 5.0
            // (API level 21) or higher, regardless of minSdkVersion.
            minSdkVersion 21
        }
        prod {
            // If you've configured the defaultConfig block for the production version of
            // your app, you can leave this block empty and Gradle uses configurations in
            // the defaultConfig block instead. You still need to include this flavor.
            // Otherwise, all variants use the "dev" flavor configurations.
        }
    }
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'),
                                                 'proguard-rules.pro'
        }
    }
}
dependencies {
    implementation "androidx.multidex:multidex:2.0.1"
}

Kotlin

android {
    defaultConfig {
        ...
        multiDexEnabled = true
        // The default minimum API level you want to support.
        minSdk = 15
    }
    productFlavors {
        // Includes settings you want to keep only while developing your app.
        create("dev") {
            // Enables pre-dexing for command-line builds. When using
            // Android Studio 2.3 or higher, the IDE enables pre-dexing
            // when deploying your app to a device running Android 5.0
            // (API level 21) or higher, regardless of minSdkVersion.
            minSdk = 21
        }
        create("prod") {
            // If you've configured the defaultConfig block for the production version of
            // your app, you can leave this block empty and Gradle uses configurations in
            // the defaultConfig block instead. You still need to include this flavor.
            // Otherwise, all variants use the "dev" flavor configurations.
        }
    }
    buildTypes {
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android.txt"),
                                                 "proguard-rules.pro")
        }
    }
}

dependencies {
    implementation("androidx.multidex:multidex:2.0.1")
}

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

เคล็ดลับ: หากมีตัวแปรการสร้างที่แตกต่างกันสำหรับความต้องการ MultiDex ที่ต่างกัน คุณสามารถระบุไฟล์ Manifest ที่แตกต่างกันสำหรับแต่ละตัวแปรเพื่อให้มีเพียงไฟล์สำหรับ API ระดับ 20 และต่ำกว่าเท่านั้นที่จะเปลี่ยนชื่อแท็ก <application> นอกจากนี้ คุณยังสร้างคลาสย่อย Application ที่แตกต่างกันสำหรับตัวแปรแต่ละรายการได้ เพื่อให้เฉพาะคลาสย่อยสำหรับ API ระดับ 20 และต่ำกว่าเท่านั้นที่ขยายคลาส MultiDexApplication หรือเรียก MultiDex.install(this)

ทดสอบแอป Multidex

เมื่อเขียนการทดสอบเครื่องมือวัดผลสําหรับแอป MultiDex คุณไม่จําเป็นต้องกําหนดค่าเพิ่มเติมหากใช้เครื่องมือวัดผล MonitoringInstrumentation หรือ AndroidJUnitRunner หากคุณใช้ Instrumentation อื่น คุณต้องลบล้างเมธอด onCreate() โดยใช้โค้ดต่อไปนี้

Kotlin

fun onCreate(arguments: Bundle) {
  MultiDex.install(targetContext)
  super.onCreate(arguments)
  ...
}

Java

public void onCreate(Bundle arguments) {
  MultiDex.install(getTargetContext());
  super.onCreate(arguments);
  ...
}

หมายเหตุ: อย่าใช้ MultiDexTestRunner ซึ่งเลิกใช้งานแล้ว ให้ใช้ AndroidJUnitRunner แทน