Định cấu hình bản dựng

Hệ thống xây dựng Android biên soạn tài nguyên và mã nguồn của ứng dụng rồi đóng gói chúng vào tệp APK hoặc Android App Bundle mà bạn có thể kiểm thử, triển khai, ký và phân phối.

Android Studio sử dụng Gradle, một bộ công cụ xây dựng nâng cao để tự động hoá và quản lý quy trình xây dựng, đồng thời cho phép bạn xác định những cấu hình bản dựng tuỳ chỉnh một cách linh hoạt. Mỗi cấu hình bản dựng có thể xác định một tập hợp mã và tài nguyên riêng, đồng thời dùng lại những phần mà mọi phiên bản của ứng dụng đều sử dụng. Trình bổ trợ Android cho Gradle phối hợp với bộ công cụ xây dựng để cung cấp các quy trình và chế độ cài đặt có thể định cấu hình dành riêng cho việc xây dựng và kiểm thử các ứng dụng Android.

Gradle và trình bổ trợ Android cho Gradle chạy độc lập với Android Studio. Tức là bạn có thể xây dựng các ứng dụng Android ngay trong Android Studio, dòng lệnh trên máy của mình hoặc trên những máy không cài đặt Android Studio (chẳng hạn như máy chủ tích hợp liên tục).

Nếu không dùng Android Studio, bạn có thể tìm hiểu cách xây dựng và chạy ứng dụng qua dòng lệnh. Cho dù bạn xây dựng dự án qua dòng lệnh, trên một máy từ xa hay sử dụng Android Studio, đầu ra của bản dựng vẫn không đổi.

Lưu ý: Vì Gradle và trình bổ trợ Android chạy độc lập với Android Studio nên bạn cần cập nhật riêng các công cụ xây dựng. Hãy đọc các ghi chú phát hành để tìm hiểu cách cập nhật Gradle và trình bổ trợ Android cho Gradle.

Tính linh hoạt của hệ thống xây dựng Android cho phép bạn tạo các cấu hình xây dựng tuỳ chỉnh mà không cần chỉnh sửa các tệp nguồn cốt lõi của ứng dụng. Trang này sẽ giúp bạn tìm hiểu cách hoạt động của hệ thống xây dựng Android cũng như cách hệ thống này có thể hỗ trợ tuỳ chỉnh và tự động hoá nhiều cấu hình bản dựng. Nếu bạn muốn tìm hiểu thêm về phương pháp triển khai ứng dụng, hãy xem bài viết Tạo và chạy ứng dụng. Còn nếu bạn cần bắt đầu tạo các cấu hình bản dựng tuỳ chỉnh bằng Android Studio ngay tức thì, hãy xem phần Định cấu hình các biến thể bản dựng.

Quy trình xây dựng

Quy trình xây dựng chứa nhiều công cụ và quy trình giúp chuyển đổi dự án ́thành Gói ứng dụng Android (APK) hoặc Android App Bundle (AAB).

Trình bổ trợ Android cho Gradle sẽ thực hiện phần lớn quy trình xây dựng. Tuy nhiên, sẽ rất hữu ích nếu bạn nắm được một số khía cạnh nhất định để có thể điều chỉnh bản dựng cho phù hợp với những yêu cầu của riêng mình.

Các dự án khác nhau có thể có những mục tiêu bản dựng khác nhau. Ví dụ: bản dựng cho thư viện bên thứ ba tạo ra Android Archive (AAR) hoặc Java Archive (JAR) thư viện. Tuy nhiên, ứng dụng là loại dự án phổ biến nhất và bản dựng cho dự án ứng dụng sẽ tạo ra tệp APK hoặc AAB gỡ lỗi hoặc phát hành của ứng dụng. Bạn có thể triển khai, kiểm thử hoặc phát hành những tệp đó cho người dùng bên ngoài.

Trang này tập trung vào phần phát triển ứng dụng nhưng hầu hết các loại bản dựng đều áp dụng những khái niệm và giai đoạn xây dựng tương tự.

Bảng thuật ngữ về bản dựng Android

Gradle và trình bổ trợ Android giúp bạn định cấu hình những phần dưới đây của bản dựng:

Loại bản dựng

Các loại bản dựng xác định một số thuộc tính mà Gradle sử dụng khi xây dựng và đóng gói ứng dụng. Những loại bản dựng này thường được định cấu hình cho từng giai đoạn trong vòng đời phát triển của ứng dụng.

Ví dụ: bản dựng gỡ lỗi kích hoạt các chế độ gỡ lỗi và ký ứng dụng bằng khoá gỡ lỗi trong khi bản dựng phát hành có thể rút gọn, làm rối mã nguồn và ký ứng dụng bằng khoá phát hành để phân phối.

Bạn cần phải xác định ít nhất một loại bản dựng để xây dựng ứng dụng. Theo mặc định, Android Studio sẽ tạo các loại bản dựng gỡ lỗi và phát hành. Để bắt đầu tuỳ chỉnh các chế độ đóng gói cho ứng dụng, hãy tìm hiểu cách định cấu hình loại bản dựng.

Phiên bản sản phẩm
Phiên bản sản phẩm biểu thị những phiên bản của ứng dụng mà bạn có thể phát hành cho người dùng, chẳng hạn như phiên bản miễn phí và phiên bản có tính phí. Bạn có thể tuỳ chỉnh từng phiên bản sản phẩm để vừa sử dụng mã và tài nguyên riêng, vừa chia sẻ và sử dụng lại các phần được dùng trên mọi phiên bản của ứng dụng. Việc xây dựng phiên bản sản phẩm là không bắt buộc và bạn cần phải tự mình tạo những phiên bản như vậy. Để bắt đầu tạo các phiên bản ứng dụng, hãy tìm hiểu cách định cấu hình phiên bản sản phẩm.
Biến thể bản dựng
Biến thể bản dựng là một sản phẩm vừa là bản dựng vừa là phiên bản sản phẩm, đồng thời là cấu hình mà Gradle sử dụng để xây dựng ứng dụng. Bằng cách sử dụng biến thể bản dựng, bạn có thể xây dựng phiên bản gỡ lỗi cho phiên bản sản phẩm trong quá trình phát triển cũng như phiên bản phát hành đã ký của phiên bản sản phẩm cho việc phân phối. Tuy không trực tiếp định cấu hình biến thể bản dựng, bạn vẫn có thể định cấu hình các loại bản dựng và phiên bản sản phẩm cấu thành nên những biến thể bản dựng đó. Việc tạo thêm các loại bản dựng hoặc phiên bản sản phẩm cũng tạo ra những biến thể bản dựng bổ sung. Để tìm hiểu cách tạo và quản lý các biến thể bản dựng, hãy tham khảo phần tổng quan về Định cấu hình các biến thể bản dựng.
Các mục trong tệp kê khai
Bạn có thể chỉ định giá trị cho một số thuộc tính của tệp kê khai trong cấu hình biến thể bản dựng. Các giá trị xây dựng này sẽ ghi đè các giá trị hiện có trong tệp kê khai. Việc này rất hữu ích nếu bạn muốn tạo nhiều biến thể của ứng dụng bằng tên ứng dụng, phiên bản SDK tối thiểu hoặc phiên bản SDK mục tiêu riêng. Khi có nhiều tệp kê khai, công cụ sáp nhập tệp kê khai sẽ sáp nhập các chế độ cài đặt tệp kê khai.
Phần phụ thuộc
Hệ thống xây dựng quản lý các phần phụ thuộc của dự án qua hệ thống tệp cục bộ và kho lưu trữ từ xa. Nhờ đó, bạn không cần phải tìm kiếm, tải và sao chép thủ công những gói tệp nhị phân của các phần phụ thuộc vào thư mục dự án. Để tìm hiểu thêm, hãy tham khảo phần Thêm phần phụ thuộc của bản dựng.
Ký
Hệ thống xây dựng cho phép bạn chỉ định các chế độ ký trong cấu hình bản dựng. Đồng thời, hệ thống này cũng có thể tự động ký ứng dụng trong quy trình xây dựng. Hệ thống xây dựng ký phiên bản gỡ lỗi bằng một khoá và chứng chỉ mặc định, sử dụng thông tin đăng nhập đã biết để tránh hiện lời nhắc nhập mật khẩu tại thời điểm xây dựng. Hệ thống xây dựng không ký phiên bản phát hành trừ phi bạn xác định rõ cấu hình ký cho bản dựng đó. Nếu không có khoá phát hành, bạn có thể tạo một khoá như mô tả trong phần Ký ứng dụng. Ứng dụng bắt buộc phải có bản dựng bản phát hành đã ký để được phân phối qua hầu hết các cửa hàng ứng dụng.
Rút gọn mã và tài nguyên
Hệ thống xây dựng cho phép bạn chỉ định cho mỗi biến thể xây dựng một tệp quy tắc ProGuard riêng. Khi bạn xây dựng ứng dụng, hệ thống xây dựng sẽ áp dụng một bộ quy tắc phù hợp để rút gọn mã và tài nguyên bằng các công cụ rút gọn tích hợp sẵn, chẳng hạn như R8. Việc thu hẹp mã và tài nguyên có thể giúp giảm kích thước tệp APK hoặc AAB.
Hỗ trợ nhiều tệp APK
Hệ thống xây dựng cho phép bạn tự động xây dựng nhiều tệp APK, trong đó mỗi tệp APK chỉ chứa mã và tài nguyên cần thiết cho một mật độ màn hình hoặc Giao diện nhị phân của ứng dụng (ABI) cụ thể. Để biết thêm thông tin, hãy xem nội dung Tạo nhiều tệp APK. Tuy nhiên, việc phát hành một tệp AAB duy nhất là phương pháp được đề xuất sử dụng vì phương pháp này cung cấp chức năng phân tách theo ngôn ngữ cũng như mật độ màn hình và ABI, đồng thời tránh việc phải tải nhiều cấu phần phần mềm lên Google Play. Toàn bộ ứng dụng mới được gửi sau tháng 8 năm 2021 đều bắt buộc phải sử dụng tệp AAB.

Phiên bản Java trong các bản dựng Android

Mã nguồn được viết bằng Java, Kotlin hay cả hai, bạn phải chọn ngôn ngữ JDK hoặc Java cho bản dựng của bạn. Xem Phiên bản Java trong bản dựng Android để biết thông tin chi tiết.

Tệp cấu hình bản dựng

Khi tạo cấu hình bản dựng tuỳ chỉnh, bạn phải thay đổi một hoặc tệp cấu hình bản dựng khác. Các tệp văn bản thuần tuý sử dụng Ngôn ngữ đặc thù theo miền (DSL) để mô tả và thao tác với logic bản dựng bằng cách sử dụng Tập lệnh Kotlin, vốn là một hương vị của ngôn ngữ Kotlin. Bạn cũng có thể sử dụng Groovy, là một ngôn ngữ động cho Máy ảo Java (JVM), để định cấu hình bản dựng của bạn.

Bạn không cần phải biết tập lệnh Kotlin hoặc Groovy để bắt đầu định cấu hình vì trình bổ trợ Android cho Gradle giới thiệu hầu hết các phần tử DSL bạn cần. Để tìm hiểu thêm về DSL của trình bổ trợ Android cho Gradle, hãy đọc Tài liệu tham khảo về DSL. Tập lệnh Kotlin cũng dựa trên cơ bản DSL Gradle Kotlin.

Khi bắt đầu một dự án mới, Android Studio sẽ tự động tạo một số các tệp này cho bạn và điền sẵn dựa trên các giá trị mặc định hợp lý. Dự án cấu trúc tệp có bố cục như sau: 

└── MyApp/  # Project
    ├── gradle/
    │   └── wrapper/
    │       └── gradle-wrapper.properties
    ├── build.gradle(.kts)
    ├── settings.gradle(.kts)
    └── app/  # Module
    │   ├── build.gradle(.kts)
    │   ├── build/
    │   ├── libs/
    │   └── src/
    │        └── main/  # Source set
    │            ├── java/
    │            │   └── com.example.myapp
    │            ├── res/
    │            │   ├── drawable/
    │            │   ├── values/
    │            │   └── ...
    │            └── AndroidManifest.xml

Một số tệp cấu hình bản dựng Gradle thuộc cấu trúc dự án chuẩn cho một ứng dụng Android. Trước khi bắt đầu định cấu hình bản dựng, bạn cần nắm được phạm vi và mục đích của các tệp này cũng như những phần tử DSL cơ bản mà chúng xác định nên.

Tệp Trình bao bọc Gradle

Trình bao bọc Gradle (gradlew) là một ứng dụng nhỏ đi kèm với mã nguồn tải xuống và khởi chạy chính Gradle. Điều này giúp quá trình thực thi bản dựng nhất quán hơn. Nhà phát triển tải nguồn ứng dụng và chạy gradlew. Thao tác này sẽ tải Gradle bắt buộc xuống phân phối và chạy Gradle để xây dựng ứng dụng của bạn.

Tệp gradle/wrapper/gradle-wrapper.properties chứa thuộc tính distributionUrl mô tả phiên bản của Gradle được dùng để chạy bản dựng của bạn.

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Tệp cài đặt Gradle

Tệp settings.gradle.kts (đối với Kotlin DSL) hoặc Tệp settings.gradle (đối với Groovy DSL) nằm trong thư mục gốc thư mục dự án. Tệp cài đặt này xác định kho lưu trữ cấp dự án cài đặt và thông báo cho Gradle những mô-đun nên đưa vào khi tạo . Các dự án có nhiều mô-đun cần chỉ định từng mô-đun sẽ được đưa vào bản dựng hoàn chỉnh.

Đối với hầu hết dự án, theo mặc định, tệp này sẽ có dạng như sau:

Kotlin

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. The code below
      * defines the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
      google()
      mavenCentral()
  }
}
rootProject.name = "My Application"
include(":app")

Groovy

pluginManagement {

    /**
      * The pluginManagement.repositories block configures the
      * repositories Gradle uses to search or download the Gradle plugins and
      * their transitive dependencies. Gradle pre-configures support for remote
      * repositories such as JCenter, Maven Central, and Ivy. You can also use
      * local repositories or define your own remote repositories. The code below
      * defines the Gradle Plugin Portal, Google's Maven repository,
      * and the Maven Central Repository as the repositories Gradle should use to look for its
      * dependencies.
      */

    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
dependencyResolutionManagement {

    /**
      * The dependencyResolutionManagement.repositories
      * block is where you configure the repositories and dependencies used by
      * all modules in your project, such as libraries that you are using to
      * create your application. However, you should configure module-specific
      * dependencies in each module-level build.gradle file. For new projects,
      * Android Studio includes Google's Maven repository and the Maven Central
      * Repository by default, but it does not configure any dependencies (unless
      * you select a template that requires some).
      */

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
rootProject.name = "My Application"
include ':app'

Tệp bản dựng cấp cao nhất

Tệp build.gradle.kts cấp cao nhất (dành cho Kotlin DSL) hoặc Tệp build.gradle (đối với Groovy DSL) nằm trong thư mục gốc thư mục dự án. Định nghĩa này thường xác định các phiên bản phổ biến của trình bổ trợ được sử dụng theo mô-đun trong dự án của bạn.

Mã mẫu sau đây mô tả các chế độ cài đặt mặc định và các phần tử DSL trong tập lệnh bản dựng cấp cao nhất sau khi tạo dự án mới:

Kotlin

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id("com.android.application") version "8.6.0" apply false
    id("com.android.library") version "8.6.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.23" apply false
}

Groovy

plugins {

    /**
     * Use `apply false` in the top-level build.gradle file to add a Gradle
     * plugin as a build dependency but not apply it to the current (root)
     * project. Don't use `apply false` in sub-projects. For more information,
     * see Applying external plugins with same version to subprojects.
     */

    id 'com.android.application' version '8.6.0' apply false
    id 'com.android.library' version '8.6.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.23' apply false
}