Cách cài file AAB lên điện thoại: Dùng bundletool chuyển AAB sang APK để test

Bạn vừa build xong file app-release.aab, chép sang điện thoại, bấm vào và Android báo không mở được file. Đây không phải lỗi. File AAB không phải là định dạng cài đặt, nó là gói nguyên liệu để Google Play sinh ra các file APK phù hợp với từng thiết bị. Muốn chạy thử trên máy thật, bạn phải tự đóng vai Google Play, và công cụ để làm việc đó tên là bundletool.

Bài viết này hướng dẫn toàn bộ quy trình từ tải bundletool, sinh file APK, cài lên máy, cho tới cách tạo một file APK duy nhất gửi cho khách hàng xem thử. Kèm theo là những lỗi hay gặp nhất và lý do đằng sau chúng.

1. bundletool là gì và vì sao bạn cần nó?

bundletool là công cụ dòng lệnh mã nguồn mở do chính Google phát hành, chạy trên Java. Đây cũng chính là công cụ mà hạ tầng Google Play dùng bên trong để xử lý file AAB bạn nộp lên. Nói cách khác, khi chạy bundletool trên máy mình, bạn đang mô phỏng lại chính xác những gì Google Play làm khi có người bấm nút cài app.

bundletool nhận vào một file .aab và sinh ra một file .apks. Đây là điểm gây bối rối cho người mới: đuôi file là .apks có chữ s ở cuối, và bản chất nó là một file nén chứa nhiều file APK bên trong, gồm base APK cộng với các configuration APK chia theo kiến trúc CPU, theo mật độ điểm ảnh và theo ngôn ngữ.

Định dạng	Bản chất	Cài trực tiếp được không
.aab	Gói nguyên liệu nộp lên Google Play	Không
.apks	Tập hợp nhiều APK chia nhỏ, do bundletool sinh ra	Không cài bằng tay, phải qua lệnh install-apks
.apk (universal)	Một file duy nhất gộp mọi tài nguyên	Cài trực tiếp được

2. Chuẩn bị môi trường trước khi chạy lệnh

Ba thứ bạn cần có sẵn:

• Java Runtime: bundletool là file .jar nên máy phải có Java. Kiểm tra bằng java -version. Nếu đã cài Android Studio thì thường đã có sẵn JDK đi kèm.
• bundletool: tải file bundletool-all-x.y.z.jar từ trang phát hành chính thức trên GitHub của Google, để vào một thư mục dễ gõ đường dẫn.
• ADB (Android Debug Bridge): nằm trong thư mục platform-tools của Android SDK. Cần thiết nếu bạn muốn cài thẳng lên máy đang cắm cáp.

Trên điện thoại, bật Tùy chọn nhà phát triển bằng cách bấm 7 lần vào mục Số hiệu bản dựng trong phần Giới thiệu điện thoại, sau đó bật Gỡ lỗi USB. Cắm cáp và chạy adb devices để xác nhận máy đã được nhận.

3. Ba chế độ build của bundletool và chọn chế độ nào

Chế độ	Sinh ra gì	Dùng khi nào
Mặc định (không thêm tham số)	File .apks chứa toàn bộ tổ hợp split APK cho mọi cấu hình thiết bị	Muốn kiểm tra chính xác những gì Google Play sẽ phân phối
--connected-device	File .apks chỉ chứa đúng phần APK khớp với chiếc máy đang cắm cáp	Test nhanh trên một thiết bị cụ thể, file nhẹ nhất
--mode=universal	Một file APK duy nhất gộp mọi kiến trúc và mọi tài nguyên	Gửi file cho khách hàng, cho tester không rành kỹ thuật, hoặc upload lên kênh phân phối khác

Điểm cần lưu ý về chế độ universal: file sinh ra sẽ nặng hơn đáng kể so với dung lượng người dùng thật sự tải từ Google Play, vì nó chứa tài nguyên cho mọi cấu hình. Nếu bạn đo dung lượng ở file universal rồi kết luận app quá nặng thì đó là kết luận sai. Con số chính xác nằm ở tab App bundle explorer trên Play Console.

4. Cài file AAB lên máy đang cắm cáp: đường ngắn nhất

Đây là quy trình hai lệnh, phù hợp với 90 phần trăm nhu cầu hàng ngày.

Bước 1, sinh file .apks chỉ dành cho thiết bị đang kết nối:

java -jar bundletool-all-1.15.6.jar build-apks \
  --bundle=app-release.aab \
  --output=app-release.apks \
  --connected-device \
  --ks=my-upload-key.jks \
  --ks-key-alias=my-alias \
  --ks-pass=pass:MatKhauKeystore \
  --key-pass=pass:MatKhauAlias

Bước 2, cài lên máy:

java -jar bundletool-all-1.15.6.jar install-apks --apks=app-release.apks

Nếu máy tính đang nhận nhiều thiết bị cùng lúc, thêm tham số --device-id=SERIAL, lấy chuỗi SERIAL từ kết quả của lệnh adb devices.

5. Tạo file APK duy nhất để gửi cho khách hàng

Khi cần đưa bản chạy thử cho người không có máy tính hoặc không rành thao tác dòng lệnh, hãy dựng bản universal:

java -jar bundletool-all-1.15.6.jar build-apks \
  --bundle=app-release.aab \
  --output=app-universal.apks \
  --mode=universal \
  --ks=my-upload-key.jks \
  --ks-key-alias=my-alias \
  --ks-pass=pass:MatKhauKeystore \
  --key-pass=pass:MatKhauAlias

File kết quả vẫn có đuôi .apks. Bên trong nó là một file APK duy nhất tên universal.apk. Đổi đuôi file thành .zip, giải nén, và bạn lấy được file APK cài trực tiếp được. Trên macOS hoặc Linux có thể làm gọn bằng một lệnh:

unzip -p app-universal.apks universal.apk > app-universal.apk

Nhắc lại một cảnh báo quan trọng: file APK này ký bằng keystore của bạn, khác với khóa ký mà Google dùng cho bản trên cửa hàng. Nếu tester đã cài bản từ Google Play, họ phải gỡ hẳn bản cũ trước khi cài bản này, nếu không sẽ gặp lỗi xung đột chữ ký. Chi tiết cơ chế hai lớp khóa được giải thích trong bài Google Play chặn APK và lộ trình bắt buộc AAB.

6. Cài file .apks bằng tay khi không dùng được install-apks

Có những lúc lệnh install-apks không chạy được, chẳng hạn khi bạn đang ở trên một máy không có bundletool nhưng có adb. Cách thủ công:

1. Đổi đuôi file app-release.apks thành .zip rồi giải nén.
2. Vào thư mục splits, bạn sẽ thấy các file kiểu base-master.apk, base-arm64_v8a.apk, base-xxhdpi.apk, base-vi.apk.
3. Cài đồng thời tất cả các file cần thiết bằng lệnh install-multiple, vì split APK bắt buộc phải được cài chung một phiên:

adb install-multiple base-master.apk base-arm64_v8a.apk base-xxhdpi.apk base-vi.apk

Nếu chỉ cài riêng base-master.apk, app sẽ cài được nhưng crash ngay khi mở vì thiếu thư viện native và thiếu tài nguyên giao diện.

7. Trích xuất thông tin từ file AAB mà không cần cài

bundletool còn vài lệnh phụ rất hữu ích khi kiểm tra một bản build trước lúc nộp lên Play Console.

Xem dung lượng tải về ước tính cho từng cấu hình thiết bị:

java -jar bundletool-all-1.15.6.jar get-size total --apks=app-release.apks --dimensions=SDK,ABI,SCREEN_DENSITY,LANGUAGE

Xem file AndroidManifest đã hợp nhất bên trong bundle:

java -jar bundletool-all-1.15.6.jar dump manifest --bundle=app-release.aab

Lệnh dump manifest đặc biệt đáng giá khi bạn nghi ngờ một thư viện bên thứ ba đang lén thêm quyền vào app. Nhiều trường hợp app bị từ chối duyệt vì quyền thừa thực chất bắt nguồn từ một SDK quảng cáo hay analytics tự chèn quyền, xem thêm bài khắc phục app bị từ chối do vi phạm chính sách quyền nhạy cảm.

8. Bảng lỗi thường gặp khi chạy bundletool

Thông báo lỗi	Nguyên nhân	Cách sửa
Unable to access jarfile bundletool.jar	Sai đường dẫn hoặc sai tên phiên bản trong tên file	Gõ đúng tên đầy đủ của file jar, hoặc chuyển terminal về đúng thư mục chứa file
Keystore was tampered with, or password was incorrect	Sai mật khẩu keystore hoặc sai mật khẩu alias	Kiểm tra lại hai tham số ks-pass và key-pass, chú ý chúng có thể khác nhau
No key with alias found in the keystore	Gõ sai tên alias	Liệt kê alias có trong keystore bằng lệnh keytool -list -v -keystore ten-file.jks
INSTALL_FAILED_UPDATE_INCOMPATIBLE	Máy đang có bản cùng package name ký bằng khóa khác	Gỡ hẳn bản cũ rồi cài lại, hoặc dùng đúng keystore đã ký bản cũ
INSTALL_FAILED_VERSION_DOWNGRADE	versionCode của bản đang cài thấp hơn bản đã có trên máy	Tăng versionCode hoặc gỡ bản cũ trước
App cài được nhưng crash ngay khi mở	Thiếu split APK, thường là thiếu phần ABI	Dùng install-apks hoặc adb install-multiple với đầy đủ các file split
No connected devices found	Máy chưa bật gỡ lỗi USB hoặc chưa chấp nhận vân tay máy tính	Bật lại gỡ lỗi USB, rút cắm cáp và bấm đồng ý trên hộp thoại hiện trên điện thoại

9. Ba cách thay thế bundletool cho người không thích dòng lệnh

• Android Studio Run trực tiếp: khi bấm nút Run với biến thể release, Android Studio tự dùng bundletool phía sau để đẩy bản build lên máy đang kết nối. Cách nhanh nhất nếu bạn chỉ cần chạy thử.
• Internal App Sharing: tải thẳng file AAB lên Play Console, nhận một đường link. Người nhận bấm link là Play Store cài đặt hộ. Đây là cách duy nhất cho bạn thấy đúng bản APK mà Google sinh ra, đã ký bằng app signing key thật.
• Internal Testing: phù hợp khi cần nhiều người thử cùng lúc và cần kiểm tra luồng thanh toán trong app, vì Google Play Billing chỉ hoạt động đầy đủ khi app được cài qua Play Store.

10. Khi nào KHÔNG nên dùng bundletool

Công cụ nào cũng có ranh giới sử dụng. Bốn tình huống bạn nên chọn cách khác:

• Cần nghiệm thu luồng In-App Purchase hoặc Subscription: bản cài bằng bundletool không đi qua Play Store nên phần lớn API thanh toán trả về lỗi. Bắt buộc dùng Internal Testing.
• Cần kiểm tra Play Integrity API hoặc In-App Update: hai API này chỉ trả về kết quả đúng khi app được phân phối qua Google Play. Xem bài tích hợp In-App Update cho Android.
• Cần đo đúng dung lượng tải về: file universal luôn nặng hơn thực tế, hãy đọc số liệu ở App bundle explorer.
• Cần gửi bản thử cho hàng chục người dùng phổ thông: hướng dẫn từng người bật cài đặt từ nguồn không xác định là trải nghiệm tệ và dễ vấp cảnh báo Unsafe App Blocked của Play Protect.

Kết luận

bundletool là mắt xích còn thiếu giữa file AAB nộp lên cửa hàng và chiếc điện thoại trên bàn làm việc của bạn. Nắm hai lệnh build-apks và install-apks là đủ cho công việc hàng ngày, còn chế độ universal dành riêng cho lúc cần gửi một file duy nhất ra ngoài. Điều quan trọng nhất cần nhớ là bản build bằng bundletool ký bằng khóa của bạn, nên nó không tương thích với bản người dùng tải từ Google Play và không dùng được để nghiệm thu các API phụ thuộc cửa hàng.

Nếu dự án của bạn đang chuẩn bị bước vào đợt thử nghiệm kín bắt buộc, dịch vụ 12 Tester thật của Uwmee Software lo trọn khâu vận hành 14 ngày và rà soát hồ sơ trước khi nộp Production. Bài nên đọc tiếp: cách tạo file AAB và Keystore ký app.