Build Number — nó là gì, giá trị tham số và tăng dần

Build Number là gì

Build Number là một định danh số nguyên duy nhất được gán cho mỗi bản dựng của ứng dụng di động. Các cửa hàng ứng dụng sử dụng nó để xác định độ mới của phiên bản — số càng cao, bản dựng càng mới.

Trên Android, tham số này được gọi là versionCode, trên iOS — CFBundleVersion. Cả hai tham số đều bắt buộc phải có khi xuất bản và phải tăng đơn điệu theo mỗi bản dựng mới.

Theo Google Play Console Help (2025), versionCode được kiểm tra mỗi khi tải APK lên: nếu một bản dựng có versionCode nhỏ hơn hoặc bằng phiên bản đã xuất bản được tải lên, Google Play từ chối tệp với lỗi.

Sử dụng Build Number để theo dõi bản dựng nội bộ — liên kết số với commit hash trong hệ thống kiểm soát phiên bản để xác định nhanh các bản phát hành có vấn đề.

Tại sao cần Build Number

Build Number giải quyết vấn đề nhận dạng rõ ràng từng phiên bản ứng dụng đã được dựng. Nếu không có nó, không thể xác định bản dựng nào mới hơn nếu Version Name không thay đổi.

Các cửa hàng ứng dụng như Google Play và App Store sử dụng Build Number để giải quyết xung đột trong quá trình cập nhật. Khi người dùng cài đặt phiên bản mới trên phiên bản cũ, hệ thống so sánh Build Number và chỉ đề xuất cập nhật nếu giá trị cao hơn.

Cơ chế này cực kỳ quan trọng đối với việc phân phối cập nhật chính xác: nếu không có Build Number tăng đơn điệu, người dùng có thể bị kẹt ở phiên bản cũ của ứng dụng.

Các định dạng Build Number

Build Number có thể là một số tuần tự đơn giản (1, 2, 3...) hoặc một số tổng hợp mã hóa thông tin bổ sung. Các số tổng hợp thường bao gồm ngày dựng hoặc số bản dựng của hệ thống CI/CD.

Đối với Android, versionCode là một số nguyên kiểu int, với giá trị tối đa là 2100000000. Đối với iOS, CFBundleVersion là một chuỗi gồm ba số phân cách bằng dấu chấm, mỗi số không quá 255.

Theo Apple Developer (2025), CFBundleVersion hỗ trợ tối đa 3 thành phần, nhưng App Store sử dụng chúng như một số thứ tự duy nhất để so sánh phiên bản.

Build Number trên Android

Trên Android, Build Number được đặt bởi tham số versionCode trong tệp build.gradle. Đây là một số nguyên phải là duy nhất cho mỗi phiên bản ứng dụng được xuất bản trên Google Play.

Tham số này được khai báo bên trong khối android.defaultConfig và phải tăng theo mỗi bản phát hành mới. Google Play không cho phép tải lên APK với versionCode đã được sử dụng cho một phiên bản khác của cùng một ứng dụng.

Theo Google Play Developer API (2025), giá trị tối đa của versionCode là 2100000000. Nên bắt đầu từ 1 và tăng thêm 1 cho mỗi bản dựng mới để tránh cạn kiệt giới hạn.

Sử dụng versionCode tổng hợp mã hóa số phiên bản: Major * 1000000 + Minor * 1000 + Patch — điều này đơn giản hóa việc ánh xạ với phiên bản ngữ nghĩa.

Giới hạn của versionCode trong Android

versionCode có các giới hạn nghiêm ngặt: nó là một số nguyên có dấu 32 bit, do đó giá trị tối đa là 2100000000. Nếu cạn kiệt giới hạn, ứng dụng không thể được cập nhật trên Google Play.

Đối với Android App Bundle, versionCode cũng được chỉ định trong mô-đun cơ sở và mỗi mô-đun tính năng có thể có versionCode riêng. Google Play kết hợp chúng thành một hệ thống xác minh duy nhất.

Giới hạn này cần được cân nhắc khi chọn chiến lược định phiên bản — số tăng quá nhanh có thể dẫn đến vấn đề về lâu dài.

Build Number trên iOS

Trên iOS, Build Number được đặt bởi khóa CFBundleVersion trong tệp Info.plist. Không giống Android, tham số này là một chuỗi, nhưng cũng phải tăng theo mỗi bản dựng mới.

Định dạng CFBundleVersion là một đến ba số phân cách bằng dấu chấm. Mỗi số không thể vượt quá 255. App Store diễn giải chuỗi như một dãy số để so sánh: 1.0.1 được coi là mới hơn 1.0.0.

Theo Apple Developer Documentation (2025), App Store Connect yêu cầu tính duy nhất của CFBundleVersion cho mỗi bản dựng được tải lên. Nếu tải lên bản dựng với số đã được sử dụng, hệ thống sẽ từ chối.

Quản lý CFBundleVersion thông qua agvtool hoặc script dựng Xcode để đảm bảo sự tăng đơn điệu của số theo mỗi bản dựng.

Tích hợp với Xcode Build Settings

Xcode cho phép quản lý CFBundleVersion thông qua Build Settings. Trường “Current Project Version” đặt giá trị cơ sở và các script Build Phase có thể tự động tăng nó.

Đối với CI/CD, hãy sử dụng plugin fastlane increment_build_number, đọc phiên bản hiện tại từ Info.plist và tăng nó lên giá trị chỉ định. Điều này đảm bảo tính duy nhất của mỗi bản dựng.

Cách tiếp cận này tự động hóa hoàn toàn việc quản lý Build Number và loại bỏ lỗi con người trong quá trình chuẩn bị phát hành.

Tăng tự động Build Number

Việc tăng tự động Build Number là một thực hành tiêu chuẩn trong các đường ống CI/CD hiện đại. Việc tăng số bản dựng thủ công dẫn đến lỗi và xung đột khi xuất bản.

GitHub Actions, GitLab CI và Jenkins cung cấp các biến tích hợp sẵn với số bản dựng. Các biến này được sử dụng trong script Gradle hoặc Xcode để tự động thay thế Build Number.

Theo GitLab CI Documentation (2025), biến CI_PIPELINE_IID đảm bảo một số duy nhất cho mỗi đường ống, lý tưởng để sử dụng làm Build Number.

Cấu hình tăng tự động ở cấp CI/CD — điều này loại bỏ nhu cầu thay đổi Build Number thủ công cho mỗi lần commit vào nhánh phát hành.

Công cụ tự động hóa phổ biến

GitHub Actions hỗ trợ biến tích hợp sẵn run_number, tự động tăng cho mỗi lần chạy đường ống. Giá trị có thể được truyền cho Gradle qua versionCode.

Jenkins sử dụng biến BUILD_NUMBER, có sẵn ở tất cả các giai đoạn dựng. Đối với các dự án Xcode, Jenkins chạy agvtool với số này.

Chọn công cụ được tích hợp vào ngăn xếp của bạn để giảm thiểu cấu hình bổ sung.

Build Number và Version Name

Build Number và Version Name hoạt động như một cặp: cái đầu dành cho máy móc, cái thứ hai dành cho con người. Build Number đảm bảo tính duy nhất kỹ thuật, Version Name cung cấp ngữ nghĩa thân thiện với người dùng.

Trên Android, hai tham số này độc lập: versionCode có thể tăng mà không cần thay đổi versionName (ví dụ, để sửa lỗi dựng). Trên iOS, CFBundleVersion cũng không bị ràng buộc với CFBundleShortVersionString.

Theo Stack Overflow Developer Survey (2024), 82% nhóm sử dụng tăng tự động Build Number, nhưng chỉ 45% tự động hóa cập nhật Version Name — đây là một trong những nguyên nhân phổ biến gây lỗi phát hành.

Luôn tăng Build Number theo mỗi bản dựng, ngay cả khi Version Name không thay đổi — điều này đảm bảo hoạt động chính xác của cơ chế cập nhật trong các cửa hàng ứng dụng.

Các phương pháp tốt nhất cho Build Number

Bắt đầu versionCode từ 1 và tăng thêm 1 cho mỗi bản dựng. Đối với iOS, sử dụng cách tiếp cận tương tự với CFBundleVersion. Tránh các số tổng hợp trừ khi thật sự cần thiết — một số tuần tự đơn giản dễ theo dõi hơn.

Liên kết Build Number với số bản dựng của hệ thống CI/CD — điều này đơn giản hóa việc truy vết từ lỗi đến một commit cụ thể. Git tag với số bản dựng và phiên bản là phương pháp tốt nhất để quản lý phát hành.

Ví dụ cấu hình Build Number

Ví dụ mã cho thấy cách cấu hình tăng tự động Build Number trên cả hai nền tảng.

versionCode trong Gradle với biến CI

Trên Android, versionCode có thể được đặt qua một biến môi trường CI/CD. Nếu biến không được đặt, giá trị mặc định sẽ được sử dụng.

android {
    defaultConfig {
        versionCode System.getenv("CI_PIPELINE_ID")?.toInteger() ?: 1
        versionName "1.2.0"
    }
}

versionCode nhận giá trị từ biến CI/CD, đảm bảo tính duy nhất của số cho mỗi bản dựng trong đường ống.

Tăng CFBundleVersion qua agvtool

Trên iOS, agvtool được tích hợp trong Xcode Command Line Tools được sử dụng để tăng tự động Build Number.

# Tăng số bản dựng lên 1
xcrun agvtool next-version -all

# Đặt số bản dựng cụ thể
xcrun agvtool new-version -all "3.0.1"

Cờ -all cập nhật phiên bản trong tất cả các mục tiêu của dự án, đảm bảo đồng bộ giá trị giữa ứng dụng chính và các tiện ích mở rộng.

Fastlane cho tự động hóa

Fastlane là một công cụ phổ biến để tự động hóa xây dựng ứng dụng di động. Plugin increment_build_number tự động tăng Build Number.

increment_build_number(
    build_number: ENV["BUILD_NUMBER"] ||
                 latest_testflight_build_number + 1
)

Fastlane tích hợp với bất kỳ hệ thống CI/CD nào và hỗ trợ cả dự án Android và iOS.