Trang này được dịch bởi Cloud Translation API.

Xây dựng nhiều APK

Thận trọng: Kể từ tháng 8 năm 2021, tất cả ứng dụng mới đều phải được phát hành dưới dạng Gói ứng dụng. Nếu bạn phát hành ứng dụng lên Google Play, hãy tạo và tải một Android App Bundle lên. Khi bạn làm như vậy, Google Play sẽ tự động tạo và phân phát tệp APK được tối ưu hoá cho cấu hình thiết bị của mỗi người dùng, nhờ đó, họ chỉ tải mã và tài nguyên mà họ cần để chạy ứng dụng của bạn. Việc phát hành nhiều tệp APK sẽ hữu ích nếu bạn phát hành trên một cửa hàng không hỗ trợ định dạng AAB. Trong trường hợp đó, bạn phải tự xây dựng, ký và quản lý từng APK.

Mặc dù bạn nên xây dựng một APK duy nhất để hỗ trợ tất cả các thiết bị mục tiêu bất cứ khi nào có thể, nhưng điều đó có thể dẫn đến kích thước APK rất lớn do tệp đó cần hỗ trợ nhiều mật độ màn hình hoặc Giao diện nhị phân của ứng dụng (ABI). Có một cách để giảm kích thước APK là tạo nhiều APK chứa các tệp có mật độ màn hình hoặc ABI cụ thể.

Gradle có thể tạo nhiều APK riêng biệt chỉ chứa mã và tài nguyên cụ thể cho từng mật độ hoặc ABI. Trang này mô tả cách định cấu hình bản dựng để tạo nhiều APK. Nếu cần tạo các phiên bản ứng dụng khác nhau không dựa trên mật độ màn hình hoặc ABI, hãy sử dụng các biến thể bản dựng.

Định cấu hình bản dựng cho nhiều APK

Để định cấu hình bản dựng cho nhiều APK, hãy thêm khối splits vào tệp build.gradle cấp mô-đun. Trong khối splits, hãy cung cấp khối density chỉ định cách bạn muốn Gradle tạo APK theo mật độ hoặc khối abi chỉ định cách bạn muốn Gradle tạo APK theo ABI. Bạn có thể cung cấp cả khối mật độ và ABI. Hệ thống bản dựng sẽ tạo một APK cho mỗi tổ hợp mật độ và ABI.

Định cấu hình nhiều APK cho mật độ màn hình

Để tạo các APK riêng cho nhiều mật độ màn hình khác nhau, hãy thêm một khối density bên trong khối splits. Trong khối density, hãy cung cấp một danh sách các mật độ màn hình mong muốn và kích thước màn hình tương thích. Chỉ sử dụng danh sách kích thước màn hình tương thích nếu bạn cần các phần tử <compatible-screens> cụ thể trong tệp kê khai của mỗi APK.

Các tùy chọn DSL Gradle sau đây được dùng để định cấu hình nhiều APK cho các mật độ màn hình:

enable cho Groovy, isEnable cho tập lệnh Kotlin

Nếu bạn đặt phần tử này thành true, Gradle sẽ tạo nhiều APK dựa trên mật độ màn hình mà bạn xác định. Giá trị mặc định là false.

exclude

Chỉ định danh sách mật độ được phân tách bằng dấu phẩy mà bạn không muốn Gradle tạo các APK riêng biệt. Sử dụng exclude nếu bạn muốn tạo APK cho hầu hết các mật độ, nhưng cần loại trừ một vài mật độ mà ứng dụng của bạn không hỗ trợ.

reset()

Xoá danh sách mật độ màn hình mặc định. Chỉ sử dụng khi kết hợp với phần tử include để chỉ định mật độ mà bạn muốn thêm.

Đoạn mã sau đây sẽ đặt danh sách mật độ thành chỉ ldpi và xxhdpi bằng cách gọi reset() để xoá danh sách, rồi sử dụng include:

reset()                  // Clears the default list from all densities
                         // to no densities.
include "ldpi", "xxhdpi" // Specifies the two densities to generate APKs
                         // for.

include

Chỉ định danh sách mật độ được phân tách bằng dấu phẩy mà bạn muốn Gradle tạo APK. Chỉ sử dụng kết hợp với reset() để chỉ định danh sách mật độ chính xác.

compatibleScreens

Chỉ định danh sách kích thước màn hình tương thích được phân tách bằng dấu phẩy. Thao tác này sẽ chèn một nút <compatible-screens> phù hợp trong tệp kê khai cho từng APK.

Chế độ cài đặt này giúp bạn quản lý cả mật độ màn hình và kích thước màn hình thuận tiện trong cùng phần build.gradle. Tuy nhiên, việc sử dụng <compatible-screens> có thể hạn chế loại thiết bị mà ứng dụng của bạn hoạt động tương thích. Để biết những cách hỗ trợ nhiều kích thước màn hình khác, hãy xem phần tổng quan về khả năng tương thích với màn hình.

Vì mỗi APK dựa trên mật độ màn hình đều bao gồm một thẻ <compatible-screens> với các hạn chế cụ thể về các loại màn hình mà APK đó hỗ trợ, ngay cả khi bạn phát hành nhiều APK, một số thiết bị mới sẽ không khớp với nhiều bộ lọc APK của bạn. Do đó, Gradle luôn tạo một APK chung chứa các tài nguyên cho tất cả mật độ màn hình và không chứa thẻ <compatible-screens>. Phát hành APK chung này cùng với các APK theo mật độ để cung cấp tính năng dự phòng cho các thiết bị không khớp với APK bằng thẻ <compatible-screens>.

Ví dụ sau đây sẽ tạo ra một APK riêng cho mỗi mật độ màn hình ngoại trừ ldpi, xxhdpi và xxxhdpi. Bạn có thể thực hiện việc này bằng cách sử dụng exclude để xoá 3 mật độ đó khỏi danh sách mặc định của tất cả mật độ.

Groovy

android {
  ...
  splits {

    // Configures multiple APKs based on screen density.
    density {

      // Configures multiple APKs based on screen density.
      enable true

      // Specifies a list of screen densities you don't want Gradle to create multiple APKs for.
      exclude "ldpi", "xxhdpi", "xxxhdpi"

      // Specifies a list of compatible screen size settings for the manifest.
      compatibleScreens 'small', 'normal', 'large', 'xlarge'
    }
  }
}

Kotlin

android {
    ...
    splits {

        // Configures multiple APKs based on screen density.
        density {

            // Configures multiple APKs based on screen density.
            isEnable = true

            // Specifies a list of screen densities you don't want Gradle to create multiple APKs for.
            exclude("ldpi", "xxhdpi", "xxxhdpi")

            // Specifies a list of compatible screen size settings for the manifest.
            compatibleScreens("small", "normal", "large", "xlarge")
        }
    }
}

Để biết thêm thông tin chi tiết về cách tuỳ chỉnh các biến thể bản dựng của ứng dụng cho các loại màn hình và thiết bị cụ thể, hãy xem phần Khai báo hỗ trợ màn hình bị hạn chế.

Định cấu hình nhiều APK cho ABI

Để tạo các APK riêng cho từng ABI, hãy thêm một khối abi bên trong khối splits của bạn. Trong khối abi, hãy cung cấp một danh sách các ABI mong muốn.

Các tuỳ chọn DSL Gradle sau đây được dùng để định cấu hình nhiều APK theo ABI:

enable đối với Groovy hoặc isEnable đối với tập lệnh Kotlin

Nếu bạn đặt phần tử này thành true, Gradle sẽ tạo nhiều APK dựa trên ABI mà bạn xác định. Giá trị mặc định là false.

exclude

Chỉ định một danh sách ABI được phân tách bằng dấu phẩy mà bạn không muốn Gradle tạo các APK riêng biệt. Sử dụng exclude nếu bạn muốn tạo APK cho hầu hết các ABI, nhưng cần loại trừ một vài ABI mà ứng dụng của bạn không hỗ trợ.

reset()

Xoá danh sách ABI mặc định. Chỉ sử dụng khi kết hợp với phần tử include để chỉ định ABI mà bạn muốn thêm.

Đoạn mã sau đây đặt danh sách ABI thành chỉ x86 và x86_64 bằng cách gọi reset() để xoá danh sách, rồi sử dụng include:

reset()                 // Clears the default list from all ABIs to no ABIs.
include "x86", "x86_64" // Specifies the two ABIs we want to generate APKs for.

include

Chỉ định danh sách ABI được phân tách bằng dấu phẩy mà bạn muốn Gradle tạo APK. Chỉ sử dụng kết hợp với reset() để chỉ định danh sách ABI chính xác.

universalApk đối với Groovy hoặc isUniversalApk đối với tập lệnh Kotlin

Nếu true, Gradle sẽ tạo một APK chung ngoài các APK theo ABI. Một APK chung chứa mã và tài nguyên cho tất cả ABI trong một APK duy nhất. Giá trị mặc định là false.

Xin lưu ý rằng tuỳ chọn này chỉ có trong khối splits.abi. Khi tạo nhiều APK dựa trên mật độ màn hình, Gradle luôn tạo một APK chung chứa mã và tài nguyên cho mọi mật độ màn hình.

Ví dụ sau đây sẽ tạo ra một APK riêng cho mỗi ABI: x86 và x86_64. Bạn có thể thực hiện việc này bằng cách sử dụng reset() để bắt đầu với danh sách ABI trống, theo sau là include kèm theo danh sách các ABI, trong đó mỗi ABI sẽ nhận được một APK.

Groovy

android {
  ...
  splits {

    // Configures multiple APKs based on ABI.
    abi {

      // Enables building multiple APKs per ABI.
      enable true

      // By default all ABIs are included, so use reset() and include to specify that you only
      // want APKs for x86 and x86_64.

      // Resets the list of ABIs for Gradle to create APKs for to none.
      reset()

      // Specifies a list of ABIs for Gradle to create APKs for.
      include "x86", "x86_64"

      // Specifies that you don't want to also generate a universal APK that includes all ABIs.
      universalApk false
    }
  }
}

Kotlin

android {
  ...
  splits {

    // Configures multiple APKs based on ABI.
    abi {

      // Enables building multiple APKs per ABI.
      isEnable = true

      // By default all ABIs are included, so use reset() and include to specify that you only
      // want APKs for x86 and x86_64.

      // Resets the list of ABIs for Gradle to create APKs for to none.
      reset()

      // Specifies a list of ABIs for Gradle to create APKs for.
      include("x86", "x86_64")

      // Specifies that you don't want to also generate a universal APK that includes all ABIs.
      isUniversalApk = false
    }
  }
}

Để biết danh sách các ABI được hỗ trợ, hãy xem bài viết Các ABI được hỗ trợ.

Dự án không có mã gốc/C++

Đối với các dự án không có mã gốc/C++, bảng Biến thể bản dựng có 2 cột: Mô-đun và Biến thể bản dựng đang hoạt động, như trong hình 1.

Bảng điều khiển Biến thể bản dựng
Hình 1. Bảng Build Variants (Biến thể bản dựng) có 2 cột cho các dự án không có mã gốc/C++.

Giá trị Biến thể bản dựng đang hoạt động cho mô-đun xác định biến thể bản dựng được triển khai và hiển thị trong trình chỉnh sửa. Để chuyển đổi giữa các biến thể, hãy nhấp vào ô Active Build Variant (Biến thể bản dựng đang hoạt động) của một mô-đun và chọn biến thể mong muốn trong trường danh sách.

Dự án có mã gốc/C++

Đối với các dự án có mã gốc/C++, bảng Biến thể bản dựng có ba cột: Mô-đun, Biến thể bản dựng đang hoạt động và ABI đang hoạt động, như minh hoạ trong hình 2.

Hình 2. Bảng Build Variants (Biến thể bản dựng) sẽ thêm cột Active ABI (ABI đang hoạt động) cho các dự án có mã gốc/C++.

Giá trị Biến thể bản dựng đang hoạt động cho mô-đun xác định biến thể bản dựng được triển khai và hiển thị trong trình chỉnh sửa. Đối với các mô-đun gốc, giá trị Active ABI (ABI đang hoạt động) xác định ABI mà trình chỉnh sửa sử dụng, nhưng không ảnh hưởng đến nội dung được triển khai.

Cách thay đổi loại bản dựng hoặc ABI:

Nhấp vào ô cho cột Active Build Variant (Biến thể bản dựng đang hoạt động) hoặc Active ABI (ABI đang hoạt động).
Chọn biến thể hoặc ABI mà bạn muốn từ trường danh sách. Quá trình đồng bộ mới sẽ tự động chạy.

Khi một ứng dụng hoặc mô-đun thư viện có thay đổi thì thay đổi đó sẽ áp dụng cho tất cả các hàng phụ thuộc.

Định cấu hình phiên bản

Theo mặc định, khi Gradle tạo nhiều APK, mỗi APK sẽ có cùng một thông tin phiên bản, như được chỉ định trong tệp build.gradle hoặc build.gradle.kts ở cấp mô-đun. Vì Cửa hàng Google Play không cho phép nhiều APK cho cùng một ứng dụng và tất cả đều có cùng một thông tin phiên bản, nên bạn cần đảm bảo rằng mỗi APK có một versionCode riêng trước khi tải lên Cửa hàng Play.

Bạn có thể định cấu hình tệp build.gradle cấp mô-đun để ghi đè versionCode cho từng APK. Bằng cách tạo liên kết sẽ chỉ định một giá trị số duy nhất cho mỗi Giao diện nhị phân ứng dụng (ABI) và mật độ mà bạn định cấu hình nhiều APK, bạn có thể ghi đè mã phiên bản đầu ra bằng một giá trị kết hợp mã phiên bản được xác định trong khối defaultConfig hoặc productFlavors có giá trị số được chỉ định cho mật độ hoặc ABI.

Trong ví dụ sau, APK cho ABI x86 sẽ nhận được versionCode là 2004 và ABI x86_64 sẽ nhận được versionCode là 3004.

Việc chỉ định mã phiên bản theo gia số lớn, chẳng hạn như 1000, cho phép bạn chỉ định mã phiên bản duy nhất sau này nếu bạn cần cập nhật ứng dụng. Ví dụ: nếu defaultConfig.versionCode lặp lại đến 5 trong lần cập nhật tiếp theo, Gradle sẽ chỉ định versionCode là 2005 cho APK x86 và 3005 cho APK x86_64.

Mẹo: Nếu bản dựng của bạn chứa một APK chung, hãy chỉ định APK đó cho versionCode thấp hơn so với bất kỳ APK nào khác. Do Cửa hàng Google Play cài đặt phiên bản ứng dụng vừa tương thích với thiết bị mục tiêu vừa có versionCode cao nhất, nên việc chỉ định versionCode thấp hơn cho APK chung sẽ đảm bảo Cửa hàng Google Play có thể cài đặt một trong các APK của bạn trước khi quay lại APK chung. Mã mẫu sau đây xử lý vấn đề này bằng cách không ghi đè versionCode mặc định của một APK chung.

Groovy

android {
  ...
  defaultConfig {
    ...
    versionCode 4
  }
  splits {
    ...
  }
}

// Map for the version code that gives each ABI a value.
ext.abiCodes = ['armeabi-v7a':1, x86:2, x86_64:3]

// For per-density APKs, create a similar map:
// ext.densityCodes = ['mdpi': 1, 'hdpi': 2, 'xhdpi': 3]

import com.android.build.OutputFile

// For each APK output variant, override versionCode with a combination of
// ext.abiCodes * 1000 + variant.versionCode. In this example, variant.versionCode
// is equal to defaultConfig.versionCode. If you configure product flavors that
// define their own versionCode, variant.versionCode uses that value instead.
android.applicationVariants.all { variant ->

  // Assigns a different version code for each output APK
  // other than the universal APK.
  variant.outputs.each { output ->

    // Stores the value of ext.abiCodes that is associated with the ABI for this variant.
    def baseAbiVersionCode =
            // Determines the ABI for this variant and returns the mapped value.
            project.ext.abiCodes.get(output.getFilter(OutputFile.ABI))

    // Because abiCodes.get() returns null for ABIs that are not mapped by ext.abiCodes,
    // the following code doesn't override the version code for universal APKs.
    // However, because you want universal APKs to have the lowest version code,
    // this outcome is desirable.
    if (baseAbiVersionCode != null) {

      // Assigns the new version code to versionCodeOverride, which changes the
      // version code for only the output APK, not for the variant itself. Skipping
      // this step causes Gradle to use the value of variant.versionCode for the APK.
      output.versionCodeOverride =
              baseAbiVersionCode * 1000 + variant.versionCode
    }
  }
}

Kotlin

android {
  ...
  defaultConfig {
    ...
    versionCode = 4
  }
  splits {
    ...
  }
}

// Map for the version code that gives each ABI a value.
val abiCodes = mapOf("armeabi-v7a" to 1, "x86" to 2, "x86_64" to 3)

// For per-density APKs, create a similar map:
// val densityCodes = mapOf("mdpi" to 1, "hdpi" to 2, "xhdpi" to 3)

import com.android.build.api.variant.FilterConfiguration.FilterType.*

// For each APK output variant, override versionCode with a combination of
// abiCodes * 1000 + variant.versionCode. In this example, variant.versionCode
// is equal to defaultConfig.versionCode. If you configure product flavors that
// define their own versionCode, variant.versionCode uses that value instead.
androidComponents {
    onVariants { variant ->

        // Assigns a different version code for each output APK
        // other than the universal APK.
        variant.outputs.forEach { output ->
            val name = output.filters.find { it.filterType == ABI }?.identifier

            // Stores the value of abiCodes that is associated with the ABI for this variant.
            val baseAbiCode = abiCodes[name]
            // Because abiCodes.get() returns null for ABIs that are not mapped by ext.abiCodes,
            // the following code doesn't override the version code for universal APKs.
            // However, because you want universal APKs to have the lowest version code,
            // this outcome is desirable.
            if (baseAbiCode != null) {
                // Assigns the new version code to output.versionCode, which changes the version code
                // for only the output APK, not for the variant itself.
                output.versionCode.set(baseAbiCode * 1000 + (output.versionCode.get() ?: 0))
            }
        }
    }
}

Để biết thêm ví dụ về các lược đồ mã phiên bản thay thế, hãy xem phần Chỉ định mã phiên bản.

Xây dựng nhiều APK

Sau khi bạn định cấu hình tệp build.gradle hoặc build.gradle.kts cấp mô-đun để tạo nhiều APK, hãy nhấp vào Build > Build APK (Tạo > Tạo APK) để tạo tất cả APK cho mô-đun hiện được chọn trong ngăn Project (Dự án). Gradle sẽ tạo các APK cho mỗi mật độ hoặc ABI trong thư mục build/outputs/apk/ của dự án.

Gradle sẽ xây dựng một APK cho mỗi mật độ hoặc ABI mà bạn định cấu hình nhiều APK. Nếu bạn cho phép nhiều APK cho cả mật độ và ABI, Gradle sẽ tạo một APK cho mỗi tổ hợp mật độ và ABI.

Ví dụ: đoạn mã build.gradle sau đây cho phép tạo nhiều APK cho mật độ mdpi và hdpi, cũng như các ABI x86 và x86_64:

Groovy

...
  splits {
    density {
      enable true
      reset()
      include "mdpi", "hdpi"
    }
    abi {
      enable true
      reset()
      include "x86", "x86_64"
    }
  }

Kotlin

...
  splits {
    density {
      isEnable = true
      reset()
      include("mdpi", "hdpi")
    }
    abi {
      isEnable = true
      reset()
      include("x86", "x86_64")
    }
  }

Kết quả từ cấu hình mẫu bao gồm 4 APK sau:

app-hdpiX86-release.apk: Chứa mã và tài nguyên cho mật độ hdpi và ABI x86.
app-hdpiX86_64-release.apk: Chứa mã và tài nguyên cho mật độ hdpi và ABI x86_64.
app-mdpiX86-release.apk: Chứa mã và tài nguyên cho mật độ mdpi và ABI x86.
app-mdpiX86_64-release.apk: Chứa mã và tài nguyên cho mật độ mdpi và ABI x86_64.

Khi xây dựng nhiều APK dựa trên mật độ màn hình, Gradle luôn tạo một APK chung, bao gồm mã và tài nguyên cho tất cả các mật độ, ngoài các APK theo mật độ.

Khi xây dựng nhiều APK dựa trên ABI, Gradle chỉ tạo một APK chứa mã và tài nguyên cho tất cả ABI nếu bạn chỉ định universalApk true trong khối splits.abi trong tệp build.gradle (đối với Groovy) hoặc isUniversalApk = true trong khối splits.abi trong tệp build.gradle.kts (đối với tập lệnh Kotlin).

Định dạng tên tệp APK

Khi tạo nhiều APK, Gradle sẽ tạo tên tệp APK theo lược đồ sau:

modulename-screendensityABI-buildvariant.apk

Thành phần của lược đồ này bao gồm:

modulename

Chỉ định tên mô-đun đang được xây dựng.

screendensity

Nếu bạn bật nhiều APK cho mật độ màn hình, hãy chỉ định mật độ màn hình cho APK, chẳng hạn như mdpi.

ABI

Nếu bạn bật nhiều APK cho ABI, hãy chỉ định ABI cho APK, chẳng hạn như x86.

Nếu bạn bật nhiều APK cho cả mật độ màn hình và ABI, Gradle sẽ liên kết tên mật độ với tên ABI, ví dụ: mdpiX86. Nếu bạn bật universalApk cho mỗi APK ABI, Gradle sẽ sử dụng universal làm phần ABI của tên tệp APK chung.

buildvariant

Chỉ định biến thể bản dựng đang được tạo, chẳng hạn như debug.

Ví dụ: khi tạo APK mật độ màn hình mdpi cho phiên bản gỡ lỗi của myApp, tên tệp APK là myApp-mdpi-debug.apk. Phiên bản phát hành của myApp được định cấu hình để tạo nhiều APK cho cả mật độ màn hình mdpi và ABI x86 có tên tệp APK là myApp-mdpiX86-release.apk.