Xây dựng ứng dụng từ dòng lệnh

Bạn có thể thực thi tất cả tác vụ tạo bản dựng (build task) có sẵn cho dự án Android bằng cách sử dụng công cụ dòng lệnh trình bao bọc Gradle (Gradle wrapper). Công cụ này có sẵn dưới dạng tệp xử lý lệnh theo lô (batch file) cho Windows (gradlew.bat) và tập lệnh shell cho Linux và Mac (gradlew.sh). Bạn có thể truy cập tệp này qua thư mục gốc của mỗi dự án được tạo bằng Android Studio.

Để chạy một tác vụ bằng trình bao bọc này, hãy sử dụng một trong các lệnh sau đây trên cửa sổ dòng lệnh (trong Android Studio, chọn View (Xem) > Tool Windows (Cửa sổ công cụ) > Terminal (Dòng lệnh)):

• Trên Windows Command Shell:

  gradlew task-name

• Trên Mac, Linux hoặc Windows PowerShell:

  ./gradlew task-name

Để xem danh sách tất cả tác vụ tạo bản dựng có sẵn cho dự án, hãy thực thi lệnh tasks:

gradlew tasks

Phần còn lại của trang này sẽ mô tả các khái niệm cơ bản để tạo và chạy ứng dụng bằng trình bao bọc Gradle. Để tìm hiểu thêm về cách thiết lập bản dựng Android, hãy xem phần nội dung Định cấu hình bản dựng.

Nếu muốn sử dụng các công cụ Android Studio thay vì công cụ dòng lệnh, hãy xem phần nội dung Tạo và chạy ứng dụng.

Giới thiệu về các loại bản dựng

Theo mặc định, có hai loại bản dựng có sẵn cho mọi ứng dụng Android: một loại dùng để gỡ lỗi ứng dụng – bản gỡ lỗi – và một loại dùng để phát hành ứng dụng cho người dùng – bản phát hành. Kết quả đầu ra cho mỗi bản dựng phải được ký bằng một chứng chỉ trước khi triển khai ứng dụng trên một thiết bị. Bản gỡ lỗi được ký tự động bằng một khoá gỡ lỗi do các công cụ SDK cung cấp (khoá này không an toàn và bạn không thể phát hành bằng khoá này lên Cửa hàng Google Play). Bản phát hành phải được ký bằng khoá riêng tư của chính bạn.

Nếu muốn tạo ứng dụng cho bản phát hành, bạn cũng cần ký ứng dụng bằng khoá ký (signing key) thích hợp. Tuy nhiên, nếu chỉ mới bắt đầu, bạn có thể nhanh chóng chạy các ứng dụng của mình trên một trình mô phỏng hoặc thiết bị được kết nối bằng cách tạo một tệp APK gỡ lỗi.

Bạn cũng có thể định nghĩa loại bản dựng tuỳ chỉnh trong tệp build.gradle.kts và định cấu hình loại bản dựng này để được ký ở dạng bản gỡ lỗi bằng cách thêm vào debuggable true. Để tìm hiểu thêm thông tin, hãy xem phần nội dung Định cấu hình biến thể bản dựng.

Tạo và triển khai tệp APK

Mặc dù tạo gói ứng dụng là cách tốt nhất để đóng gói ứng dụng và tải lên Play Console, việc tạo một tệp APK sẽ phù hợp hơn khi bạn muốn nhanh chóng kiểm thử bản gỡ lỗi hoặc chia sẻ ứng dụng cho người khác dưới dạng một cấu phần triển khai phần mềm.

Tạo tệp APK gỡ lỗi

Để kiểm thử và gỡ lỗi ứng dụng tức thì, bạn có thể tạo tệp APK gỡ lỗi. Tệp APK gỡ lỗi được ký bằng một khoá gỡ lỗi do các công cụ SDK cung cấp và cho phép gỡ lỗi thông qua adb.

Để tạo một tệp APK gỡ lỗi, hãy mở công cụ dòng lệnh và chuyển đến thư mục gốc của dự án. Để khởi tạo bản gỡ lỗi, hãy gọi tác vụ assembleDebug:

gradlew assembleDebug

Thao tác này sẽ tạo ra một tệp APK có tên là module_name-debug.apk trong project_name/module_name/build/outputs/apk/. Tệp này đã được ký bằng khoá gỡ lỗi và được điều chỉnh bằng zipalign. Nhờ vậy, bạn có thể cài đặt ngay tệp này trên một thiết bị.

Hoặc để tạo tệp APK này và cài đặt ngay trên một trình mô phỏng hoặc thiết bị được kết nối đang chạy, hãy gọi installDebug:

gradlew installDebug

Phần "Debug" trong tên của tác vụ ở trên chỉ là phiên bản viết tắt theo quy ước camel của tên biến thể bản dựng, vì vậy, bạn có thể thay thế phần này bằng bất kỳ loại bản dựng hoặc biến thể nào mà bạn muốn kết hợp hoặc cài đặt. Ví dụ: nếu bạn có phiên bản sản phẩm "demo" thì bạn có thể tạo phiên bản gỡ lỗi với tác vụ là assembleDemoDebug.

Để xem tất cả tác vụ tạo và cài đặt có sẵn cho từng biến thể (bao gồm tác vụ gỡ cài đặt), hãy chạy tác vụ tasks.

Ngoài ra, hãy xem phần nội dung về cách chạy ứng dụng trên trình mô phỏng và chạy ứng dụng trên một thiết bị.

Tạo gói phát hành hoặc tệp APK

Khi đã sẵn sàng phát hành và phân phối ứng dụng, bạn phải tạo một gói phát hành hoặc tệp APK được ký bằng khoá riêng tư của bạn. Để tìm hiểu thêm thông tin, hãy chuyển đến phần nội dung về cách ký ứng dụng bằng dòng lệnh.

Triển khai ứng dụng trên trình mô phỏng

Để sử dụng Trình mô phỏng Android, bạn phải tạo Thiết bị Android ảo (AVD) bằng Android Studio.

Khi đã có AVD, bạn hãy khởi động Trình mô phỏng Android và cài đặt ứng dụng như sau:

1. Trong công cụ dòng lệnh, hãy chuyển đến android_sdk/tools/ và khởi động trình mô phỏng bằng lệnh khai báo AVD:

   emulator -avd avd_name

   Nếu bạn không chắc chắn về tên AVD, hãy thực thi lệnh emulator -list-avds.

2. Bây giờ, bạn có thể cài đặt ứng dụng bằng một trong những thao tác cài đặt Gradle đã đề cập trong phần nội dung về cách tạo một tệp APK gỡ lỗi hoặc công cụ adb.

   Nếu tệp APK được tạo bằng cách sử dụng SDK dùng thử dành cho nhà phát triển (nếutargetSdkVersion là một chữ cái thay vì chữ số), bạn phải cung cấp tuỳ chọn -t cùng lệnh install để cài đặt tệp APK kiểm thử.

   adb install path/to/your_app.apk
   

   Toàn bộ tệp APK bạn xây dựng đều được lưu trong project_name/module_name/build/outputs/apk/.

Để tìm hiểu thêm thông tin, hãy xem phần nội dung Chạy ứng dụng trên Trình mô phỏng Android.

Triển khai ứng dụng trên một thiết bị thực tế

Trước khi chạy ứng dụng trên một thiết bị, bạn phải bật tính năng gỡ lỗi USB trên thiết bị. Bạn có thể tìm thấy tuỳ chọn này trong phần Settings (Cài đặt) > Developer options (Tuỳ chọn cho nhà phát triển).

Lưu ý: Trên Android 4.2 trở lên, Developer options (Tuỳ chọn cho nhà phát triển) sẽ bị ẩn theo mặc định. Để mở giao diện này, hãy chuyển đến phần Settings (Cài đặt) > About phone (Giới thiệu về điện thoại) rồi nhấn vào Build number (Số bản dựng) bảy lần. Quay lại màn hình trước để tìm Developer options (Tuỳ chọn cho nhà phát triển).

Sau khi thiết lập và kết nối thiết bị qua USB, bạn có thể cài đặt ứng dụng bằng cách sử dụng tác vụ cài đặt Gradle được đề cập trong phần nội dung về cáchtạo một tệp APK gỡ lỗi hoặc công cụ adb:

adb -d install path/to/your_app.apk

Toàn bộ tệp APK bạn xây dựng đều được lưu trong project_name/module_name/build/outputs/apk/.

Để tìm hiểu thêm thông tin, hãy xem phần nội dung Chạy ứng dụng trên thiết bị phần cứng.

Tạo gói ứng dụng

Android App Bundle chứa tất cả tài nguyên và mã đã biên dịch của ứng dụng, nhưng lại làm chậm quá trình tạo tệp APK và đăng nhập vào Google Play. Không giống APK, bạn không thể triển khai gói ứng dụng trực tiếp trên thiết bị. Vì vậy, nếu muốn nhanh chóng kiểm thử hoặc chia sẻ tệp APK với người khác, bạn nên tạo tệp APK.

Cách dễ nhất để tạo gói ứng dụng là sử dụng Android Studio. Tuy nhiên, nếu cần tạo gói ứng dụng bằng dòng lệnh, bạn có thể thực hiện bằng cách sử dụng Gradle hoặc bundletool, như mô tả trong các phần bên dưới.

Tạo gói ứng dụng bằng Gradle

Nếu bạn muốn tạo một gói ứng dụng bằng dòng lệnh, hãy chạy tác vụ Gradle bundleVariant trên mô-đun cơ sở của ứng dụng đó. Ví dụ: lệnh sau đây tạo một gói ứng dụng cho phiên bản gỡ lỗi của mô-đun cơ sở:

./gradlew :base:bundleDebug

Nếu muốn tạo một gói đã ký tên để tải lên Play Console, trước tiên, bạn cần định cấu hình tệp build.gradle.kts của mô-đun cơ sở với thông tin chữ ký của ứng dụng. Để tìm hiểu thêm, hãy chuyển đến phần nội dung về cách Định cấu hình Gradle để ký ứng dụng. Chẳng hạn, bạn có thể tạo phiên bản phát hành của ứng dụng và Gradle sẽ tự động tạo một gói ứng dụng và ký gói ứng dụng đó bằng thông tin chữ ký bạn cung cấp trong tệp build.gradle.kts.

Ngược lại, nếu bạn muốn ký một gói ứng dụng bằng một bước riêng biệt, bạn có thể sử dụng jarsigner để ký gói ứng dụng bằng dòng lệnh. Lệnh để tạo gói ứng dụng là:

jarsigner -keystore pathToKeystore app-release.aab keyAlias

Tạo gói ứng dụng bằng bundletool

bundletool là công cụ dòng lệnh được Android Studio, trình bổ trợ Android cho Gradle và Google Play dùng để chuyển đổi mã và tài nguyên đã biên dịch của ứng dụng thành các gói ứng dụng, đồng thời tạo ra các tệp APK có thể triển khai qua các gói đó.

Như vậy, việc kiểm thử các gói ứng dụng bằng bundletool và tái tạo trong phạm vi cục bộ về cách Google Play tạo các tệp APK mang lại nhiều giá trị hữu ích. Tuy nhiên, thông thường, bạn không cần gọi bundletool để tạo gói ứng dụng, thay vào đó, bạn nên sử dụng các tác vụ Android Studio hoặc Gradle như đã mô tả trong các phần trước.

Mặc dù vậy, nếu bạn không muốn sử dụng các tác vụ Android Studio hoặc Gradle để tạo các gói, chẳng hạn như bạn muốn sử dụng chuỗi công cụ tạo bản dựng tuỳ chỉnh, bạn có thể sử dụng bundletool bằng dòng lệnh để tạo một gói ứng dụng qua mã và tài nguyên được biên dịch sẵn. Nếu bạn chưa làm điều đó, hãy tải bundletool xuống qua kho lưu trữ GitHub.

Phần này mô tả cách đóng gói tài nguyên và mã đã biên dịch của ứng dụng cũng như cách sử dụng bundletool bằng dòng lệnh để chuyển đổi mã và tài nguyên này thành Android App Bundle.

Tạo tệp kê khai và tài nguyên ở định dạng proto

bundletool yêu cầu bạn cung cấp một số thông tin nhất định về dự án ứng dụng, chẳng hạn như tệp kê khai và tài nguyên của ứng dụng, ở định dạng Vùng đệm giao thức của Google – còn được gọi là "protobuf" và sử dụng đuôi tệp là *.pb. Protobuf cung cấp một cơ chế trung lập về ngôn ngữ, trung lập về nền tảng và có thể mở rộng, giúp chuyển đổi tuần tự dữ liệu có cấu trúc — tương tự như XML, nhưng nhỏ gọn hơn, nhanh hơn và đơn giản hơn.

Tải AAPT2 xuống

Bạn có thể tạo tệp kê khai và bảng tài nguyên của ứng dụng ở định dạng protobuf bằng cách sử dụng phiên bản AAPT2 mới nhất trên kho lưu trữ Google Maven.

Để tải AAPT2 xuống qua kho lưu trữ Maven của Google, hãy tiến hành các bước sau:

1. Chuyển đến com.android.tools.build > aapt2 trong phần chỉ mục kho lưu trữ.
2. Sao chép tên của phiên bản AAPT2 mới nhất.

3. Chèn tên phiên bản bạn vừa sao chép vào URL sau và chỉ định hệ điều hành đích: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/aapt2-version/aapt2-aapt2-version-[windows | linux | osx].jar

   Ví dụ: để tải phiên bản 3.2.0-alpha18-4804415 cho Windows, bạn hãy sử dụng: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar

4. Di chuyển đến URL trong trình duyệt—AAPT2 sẽ bắt đầu tải xuống trong chốc lát.

5. Mở gói tệp JAR bạn vừa tải xuống.

Biên dịch và liên kết với tài nguyên của ứng dụng

Sử dụng AAPT2 để biên dịch tài nguyên trong ứng dụng bằng lệnh sau:

aapt2 compile \
project_root/module_root/src/main/res/drawable/Image1.png \
project_root/module_root/src/main/res/drawable/Image2.png \
-o compiled_resources/

Trong giai đoạn liên kết, là giai đoạn AAPT2 liên kết các tài nguyên đã biên dịch khác nhau thành một APK duy nhất, hãy hướng dẫn AAPT2 chuyển đổi tệp kê khai của ứng dụng và các tài nguyên đã biên dịch thành định dạng protobuf thông qua cờ --proto-format như bên dưới:

aapt2 link --proto-format -o output.apk \
-I android_sdk/platforms/android_version/android.jar \
--manifest project_root/module_root/src/main/AndroidManifest.xml \
-R compiled_resources/*.flat \
--auto-add-overlay

Sau đó, bạn có thể trích xuất nội dung từ kết quả đầu ra của tệp APK, chẳng hạn như AndroidManifest.xml, resources.pb và các tệp tài nguyên khác của ứng dụng — hiện tại đang ở định dạng protobuf. Bạn cần các tệp này trong quá trình chuẩn bị các yêu cầu đầu vào cho bundletool để tạo gói ứng dụng, như mô tả trong phần sau.

Đóng gói tài nguyên và mã được biên dịch sẵn

Trước khi sử dụng bundletool để tạo gói ứng dụng, trước tiên bạn phải cung cấp các tệp ZIP, mỗi tệp chứa mã và tài nguyên đã biên dịch cho một mô-đun ứng dụng có sẵn. Nội dung và cách sắp xếp tệp ZIP trong từng mô-đun rất giống với định dạng Android App Bundle. Ví dụ: bạn nên tạo tệp base.zip cho mô-đun cơ sở của ứng dụng và sắp xếp nội dung của mô-đun này như sau:

Sau khi chuẩn bị tệp ZIP cho từng mô-đun của ứng dụng, bạn có thể chuyển các tệp đó đến bundletool để tạo gói ứng dụng, như được mô tả trong phần sau.

Tạo gói ứng dụng bằng bundletool

Để tạo gói ứng dụng, bạn hãy sử dụng lệnh bundletool build-bundle như trình bày dưới đây:

bundletool build-bundle --modules=base.zip --output=mybundle.aab

Bảng sau đây mô tả chi tiết về các cờ cho lệnh build-bundle:

Tuỳ chỉnh cách tạo tệp APK theo chiều xuôi (downstream)

Gói ứng dụng sẽ bao gồm một tệp BundleConfig.pb dùng để cung cấp siêu dữ liệu theo yêu cầu của cửa hàng ứng dụng, chẳng hạn như Google Play, khi tạo tệp APK từ gói đó. Mặc dù bundletool sẽ tạo tệp này cho bạn, nhưng bạn có thể định cấu hình một số thành phần của siêu dữ liệu trong tệp BundleConfig.json và chuyển tệp này vào lệnh bundletool build-bundle — sau đó bundletool sẽ chuyển đổi và sẽ hợp nhất tệp này với phiên bản protobuf chứa trong mỗi gói ứng dụng.

Ví dụ: bạn có thể kiểm soát để bật hoặc tắt các danh mục trong tệp APK cấu hình. Sau đây là ví dụ về tệp BundleConfig.json dùng để vô hiệu hoá các APK cấu hình, trong đó mỗi APK hướng đến một ngôn ngữ khác nhau (tức là tài nguyên cho tất cả ngôn ngữ được chứa trong APK cơ sở hoặc chức năng tương ứng):

{
  "optimizations": {
    "splitsConfig": {
      "splitDimension": [{
        "value": "LANGUAGE",
        "negate": true
      }]
    }
  }
}

Trong tệp BundleConfig.json, bạn cũng có thể chỉ định loại tệp nào không cần nén khi đóng gói APK thông qua các mẫu glob như sau:

{
  "compression": {
    "uncompressedGlob": ["res/raw/**", "assets/**.uncompressed"]
  }
}

Lưu ý rằng theo mặc định, bundletool không nén thư viện gốc (trên Android 6.0 trở lên) và bảng tài nguyên (resources.arsc) của ứng dụng. Để xem mô tả đầy đủ về những nội dung bạn có thể định cấu hình trong BundleConfig.json, hãy kiểm tra tệp config.protobundletool, được viết bằng cú pháp Proto3.

Triển khai ứng dụng bằng một gói ứng dụng

Nếu bạn đã tạo và ký gói ứng dụng, hãy sử dụng bundletool để tạo APK và triển khai các APK đó trên một thiết bị.

Ký ứng dụng bằng dòng lệnh

Bạn không cần Android Studio để ký ứng dụng. Thay vào đó, bạn có thể ký ứng dụng bằng dòng lệnh, sử dụng apksigner cho APK hoặc jarsigner cho gói ứng dụng hoặc định cấu hình Gradle để ký ứng dụng trong quá trình xây dựng. Dù với cách nào, trước hết bạn cần tạo khoá riêng tư thông qua keytool, như minh hoạ bên dưới:

keytool -genkey -v -keystore my-release-key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias my-alias

Ví dụ trên sẽ nhắc bạn mật khẩu cho kho khoá và khoá, cũng như các trường "Distinguished Name" (Tên phân biệt) cho khoá của bạn. Đoạn lệnh này sau đó sẽ tạo kho khoá dưới dạng một tệp có tên là my-release-key.jks, lưu tệp đó trong thư mục hiện tại (bạn có thể chuyển tệp này đến bất cứ đâu). Kho khoá này chứa một khoá duy nhất có hiệu lực trong 10.000 ngày.

Bây giờ, bạn có thể tự ký APK hoặc gói ứng dụng hoặc định cấu hình Gradle để ký ứng dụng trong quá trình tạo bản dựng, như mô tả trong các phần bên dưới.

Ký ứng dụng theo cách thủ công bằng dòng lệnh

Nếu muốn ký một gói ứng dụng bằng dòng lệnh, bạn có thể sử dụng jarsigner. Nếu muốn ký APK, bạn cần sử dụng zipalign và apksigner như mô tả bên dưới.

1. Mở công cụ dòng lệnh trong Android Studio, chọn View (Xem) > Tool Windows (Cửa sổ công cụ) > Terminal (Dòng lệnh) – rồi chuyển đến thư mục chứa APK chưa được ký.

2. Căn chỉnh APK chưa được ký bằng zipalign:

   zipalign -v -p 4 my-app-unsigned.apk my-app-unsigned-aligned.apk
   

   zipalign đảm bảo rằng tất cả dữ liệu chưa nén đều được bắt đầu bằng một byte đặc thù phù hợp với phần đầu tệp. Điều này sẽ giúp giảm dung lượng RAM mà ứng dụng sử dụng.

3. Ký APK bằng khoá riêng tư của bạn thông qua apksigner:

   apksigner sign --ks my-release-key.jks --out my-app-release.apk my-app-unsigned-aligned.apk
   

   Ví dụ này sẽ xuất ra APK đã ký tại my-app-release.apk sau khi ký APK này bằng khoá riêng tư và chứng chỉ được lưu trữ trong một tệp KeyStore duy nhất: my-release-key.jks.

   Công cụ apksigner hỗ trợ các tuỳ chọn ký tên khác, bao gồm cả việc ký tệp APK bằng khoá riêng tư và tệp chứng chỉ riêng biệt, cũng như ký APK bằng nhiều trình ký. Để biết thêm chi tiết, hãy tham khảo apksigner.

   Lưu ý: Để sử dụng công cụ apksigner, bạn phải cài đặt Công cụ tạo SDK Android phiên bản 24.0.3 trở lên. Bạn có thể cập nhật gói này thông qua Trình quản lý SDK.

4. Xác minh APK đã được ký hay chưa:

   apksigner verify my-app-release.apk
   

Định cấu hình Gradle để ký ứng dụng

Mở tệp build.gradle.kts cấp mô-đun và thêm khối signingConfigs {} chứa các mục nhập cho storeFile, storePassword, keyAlias và keyPassword. Sau đó chuyển đối tượng đó đến thuộc tính signingConfig trong loại bản dựng. Ví dụ:

android {
    ...
    defaultConfig { ... }
    signingConfigs {
        create("release") {
            // You need to specify either an absolute path or include the
            // keystore file in the same directory as the build.gradle file.
            storeFile = file("my-release-key.jks")
            storePassword = "password"
            keyAlias = "my-alias"
            keyPassword = "password"
        }
    }
    buildTypes {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            ...
        }
    }
}

android {
    ...
    defaultConfig { ... }
    signingConfigs {
        release {
            // You need to specify either an absolute path or include the
            // keystore file in the same directory as the build.gradle file.
            storeFile file("my-release-key.jks")
            storePassword "password"
            keyAlias "my-alias"
            keyPassword "password"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            ...
        }
    }
}

Bây giờ, khi tạo ứng dụng bằng cách gọi đến một tác vụ Gradle, Gradle sẽ giúp bạn ký ứng dụng (và chạy zipalign).

Ngoài ra, vì bạn đã định cấu hình bản phát hành bằng ký khoá, tác vụ "install" (cài đặt) sẽ có sẵn cho loại bản dựng đó. Vì vậy, bạn có thể tạo, căn chỉnh, ký ứng dụng và cài đặt APK phát hành trên một trình mô phỏng hoặc thiết bị bằng tác vụ installRelease.

Một ứng dụng được ký bằng khoá riêng tư đã sẵn sàng để phân phối, nhưng trước hết bạn nên tìm hiểu thêm về cách phát hành ứng dụng và xem lại danh sách kiểm tra trước khi phát hành trên Google Play.