Build Number — คืออะไร ค่าพารามิเตอร์และการเพิ่ม

Build Number คืออะไร

Build Number คือตัวระบุจำนวนเต็มเฉพาะที่กำหนดให้กับแต่ละบิลด์ของแอปพลิเคชันมือถือ ร้านค้าแอปใช้มันเพื่อกำหนดความใหม่ของเวอร์ชัน — ยิ่งตัวเลขมากเท่าไหร่ บิลด์ยิ่งใหม่เท่านั้น

ใน Android พารามิเตอร์นี้เรียกว่า versionCode ใน iOS — CFBundleVersion พารามิเตอร์ทั้งสองจำเป็นสำหรับการเผยแพร่และต้องเพิ่มขึ้นอย่างซ้ำซากจำเจทุกครั้งที่มีบิลด์ใหม่

ตาม Google Play Console Help (2025) versionCode จะถูกตรวจสอบทุกครั้งที่อัปโหลด APK: หากอัปโหลดบิลด์ที่มี versionCode น้อยกว่าหรือเท่ากับเวอร์ชันที่เผยแพร่แล้ว Google Play จะปฏิเสธไฟล์พร้อมข้อผิดพลาด

ใช้ Build Number สำหรับการติดตามบิลด์ภายใน — เชื่อมโยงหมายเลขกับ commit hash ในระบบควบคุมเวอร์ชันของคุณเพื่อระบุรีลีสที่มีปัญหาได้อย่างรวดเร็ว

ทำไมต้องใช้ Build Number

Build Number แก้ปัญหาการระบุเวอร์ชันแอปพลิเคชันที่สร้างขึ้นแต่ละเวอร์ชันอย่างชัดเจน หากไม่มีมัน จะไม่สามารถระบุได้ว่าบิลด์ใดใหม่กว่าหาก Version Name ไม่เปลี่ยนแปลง

ร้านค้าแอปเช่น Google Play และ App Store ใช้ Build Number เพื่อแก้ไขความขัดแย้งระหว่างการอัปเดต เมื่อผู้ใช้ติดตั้งเวอร์ชันใหม่ทับเวอร์ชันเก่า ระบบจะเปรียบเทียบ Build Number และเสนออัปเดตเฉพาะเมื่อค่ามากกว่าเท่านั้น

กลไกนี้มีความสำคัญอย่างยิ่งต่อการส่งมอบอัปเดตที่ถูกต้อง: หากไม่มี Build Number ที่เพิ่มขึ้นอย่างซ้ำซากจำเจ ผู้ใช้อาจติดอยู่ที่เวอร์ชันเก่าของแอปพลิเคชัน

รูปแบบ Build Number

Build Number สามารถเป็นหมายเลขลำดับอย่างง่าย (1, 2, 3...) หรือหมายเลขประกอบที่เข้ารหัสข้อมูลเพิ่มเติม หมายเลขประกอบมักรวมวันที่บิลด์หรือหมายเลขบิลด์ของระบบ CI/CD

สำหรับ Android versionCode เป็นจำนวนเต็มชนิด int โดยมีค่าสูงสุด 2100000000 สำหรับ iOS CFBundleVersion เป็นสตริงของตัวเลขสามตัวคั่นด้วยจุด แต่ละตัวไม่เกิน 255

ตาม Apple Developer (2025) CFBundleVersion รองรับสูงสุด 3 องค์ประกอบ แต่ App Store ใช้เป็นหมายเลขลำดับเดียวสำหรับการเปรียบเทียบเวอร์ชัน

Build Number บน Android

บน Android Build Number ถูกกำหนดโดยพารามิเตอร์ versionCode ในไฟล์ build.gradle เป็นจำนวนเต็มที่ต้องไม่ซ้ำกันสำหรับแต่ละเวอร์ชันของแอปพลิเคชันที่เผยแพร่บน Google Play

พารามิเตอร์ถูกประกาศภายในบล็อก android.defaultConfig และต้องเพิ่มขึ้นทุกครั้งที่มีรีลีสใหม่ Google Play ไม่อนุญาตให้อัปโหลด APK ที่มี versionCode ซึ่งเคยใช้แล้วสำหรับเวอร์ชันอื่นของแอปพลิเคชันเดียวกัน

ตาม Google Play Developer API (2025) ค่าสูงสุดของ versionCode คือ 2100000000 แนะนำให้เริ่มที่ 1 และเพิ่มครั้งละ 1 สำหรับแต่ละบิลด์ใหม่เพื่อหลีกเลี่ยงการหมดขีดจำกัด

ใช้ versionCode แบบประกอบที่เข้ารหัสหมายเลขเวอร์ชัน: Major * 1000000 + Minor * 1000 + Patch — ซึ่งช่วยให้การจับคู่กับเวอร์ชันความหมายง่ายขึ้น

ข้อจำกัดของ versionCode ใน Android

versionCode มีข้อจำกัดที่เข้มงวด: มันเป็นจำนวนเต็มมีเครื่องหมาย 32 บิต ดังนั้นค่าสูงสุดคือ 2100000000 หากขีดจำกัดหมด จะไม่สามารถอัปเดตแอปพลิเคชันบน Google Play ได้

สำหรับ Android App Bundle versionCode ยังถูกระบุในโมดูลฐาน และแต่ละโมดูลคุณสมบัติสามารถมี versionCode ของตัวเอง Google Play รวมเข้าด้วยกันเป็นระบบตรวจสอบเดียว

ข้อจำกัดนี้สำคัญที่ต้องพิจารณาเมื่อเลือกกลยุทธ์การกำหนดเวอร์ชัน — การเพิ่มจำนวนที่เร็วเกินไปอาจนำไปสู่ปัญหาในระยะยาว

Build Number บน iOS

บน iOS Build Number ถูกกำหนดโดยคีย์ CFBundleVersion ในไฟล์ Info.plist ซึ่งแตกต่างจาก Android พารามิเตอร์นี้เป็นสตริง แต่ก็ต้องเพิ่มขึ้นทุกครั้งที่มีบิลด์ใหม่

รูปแบบของ CFBundleVersion คือหนึ่งถึงสามตัวเลขคั่นด้วยจุด แต่ละตัวเลขต้องไม่เกิน 255 App Store ตีความสตริงเป็นลำดับตัวเลขสำหรับเปรียบเทียบ: 1.0.1 ถือว่าใหม่กว่า 1.0.0

ตาม Apple Developer Documentation (2025) App Store Connect ต้องการความไม่ซ้ำกันของ CFBundleVersion สำหรับแต่ละบิลด์ที่อัปโหลด หากอัปโหลดบิลด์ที่มีหมายเลขที่ใช้แล้ว ระบบจะปฏิเสธ

จัดการ CFBundleVersion ผ่าน agvtool หรือสคริปต์บิลด์ Xcode เพื่อให้แน่ใจว่าหมายเลขเพิ่มขึ้นอย่างซ้ำซากจำเจในทุกบิลด์

การรวมเข้ากับ Xcode Build Settings

Xcode อนุญาตให้จัดการ CFBundleVersion ผ่าน Build Settings ฟิลด์ “Current Project Version” กำหนดค่าพื้นฐาน และสคริปต์ Build Phase สามารถเพิ่มได้โดยอัตโนมัติ

สำหรับ CI/CD ให้ใช้ปลั๊กอิน fastlane increment_build_number ซึ่งอ่านเวอร์ชันปัจจุบันจาก Info.plist และเพิ่มตามค่าที่ระบุ ซึ่งรับประกันความไม่ซ้ำกันของแต่ละบิลด์

แนวทางนี้ทำให้การจัดการ Build Number เป็นอัตโนมัติอย่างสมบูรณ์และขจัดข้อผิดพลาดของมนุษย์ระหว่างการเตรียมรีลีส

การเพิ่ม Build Number อัตโนมัติ

การเพิ่มอัตโนมัติของ Build Number เป็นแนวปฏิบัติมาตรฐานในไปป์ไลน์ CI/CD สมัยใหม่ การเพิ่มหมายเลขบิลด์ด้วยตนเองนำไปสู่ข้อผิดพลาดและความขัดแย้งระหว่างการเผยแพร่

GitHub Actions, GitLab CI และ Jenkins มีตัวแปรในตัวพร้อมหมายเลขบิลด์ ตัวแปรเหล่านี้ใช้ในสคริปต์ Gradle หรือ Xcode สำหรับการแทนที่ Build Number โดยอัตโนมัติ

ตาม GitLab CI Documentation (2025) ตัวแปร CI_PIPELINE_IID รับประกันหมายเลขที่ไม่ซ้ำกันสำหรับแต่ละไปป์ไลน์ ทำให้เหมาะสำหรับใช้เป็น Build Number

กำหนดค่าการเพิ่มอัตโนมัติในระดับ CI/CD — ซึ่งช่วยขจัดความจำเป็นในการเปลี่ยน Build Number ด้วยตนเองทุกครั้งที่คอมมิตไปยังสาขารีลีส

เครื่องมืออัตโนมัติยอดนิยม

GitHub Actions รองรับตัวแปรในตัว run_number ซึ่งเพิ่มขึ้นโดยอัตโนมัติทุกครั้งที่รันไปป์ไลน์ ค่าสามารถส่งต่อไปยัง Gradle ผ่าน versionCode

Jenkins ใช้ตัวแปร BUILD_NUMBER ซึ่งพร้อมใช้งานในทุกขั้นตอนบิลด์ สำหรับโปรเจกต์ Xcode Jenkins จะรัน agvtool ด้วยหมายเลขนี้

เลือก เครื่องมือที่รวมเข้ากับสแต็กของคุณเพื่อลดการกำหนดค่าเพิ่มเติม

Build Number และ Version Name

Build Number และ Version Name ทำงานเป็นคู่: อย่างแรกสำหรับเครื่องจักร อย่างที่สองสำหรับมนุษย์ Build Number รับประกันความไม่ซ้ำกันทางเทคนิค Version Name ให้ความหมายที่ผู้ใช้เข้าใจได้

ใน Android พารามิเตอร์ทั้งสองนี้เป็นอิสระต่อกัน: versionCode สามารถเพิ่มได้โดยไม่ต้องเปลี่ยน versionName (เช่น เพื่อแก้ไขข้อผิดพลาดบิลด์) ใน iOS CFBundleVersion ก็ไม่ได้ผูกติดกับ CFBundleShortVersionString เช่นกัน

ตาม Stack Overflow Developer Survey (2024) 82% ของทีมใช้การเพิ่ม Build Number อัตโนมัติ แต่มีเพียง 45% ที่ทำให้การอัปเดต Version Name เป็นอัตโนมัติ — ซึ่งเป็นหนึ่งในสาเหตุทั่วไปของข้อผิดพลาดรีลีส

เพิ่ม Build Number ทุกครั้งที่มีบิลด์เสมอ แม้ว่า Version Name จะไม่เปลี่ยนแปลง — ซึ่งรับประกันการทำงานที่ถูกต้องของกลไกอัปเดตในร้านค้าแอป

แนวทางปฏิบัติที่ดีที่สุดสำหรับ Build Number

เริ่ม versionCode ที่ 1 และเพิ่มครั้งละ 1 สำหรับแต่ละบิลด์ สำหรับ iOS ให้ใช้แนวทางเดียวกันกับ CFBundleVersion หลีกเลี่ยงหมายเลขประกอบหากไม่จำเป็นอย่างยิ่ง — หมายเลขลำดับอย่างง่ายติดตามได้ง่ายกว่า

เชื่อมโยง Build Number กับหมายเลขบิลด์ของระบบ CI/CD — ซึ่งช่วยให้การติดตามจากข้อผิดพลาดไปยังคอมมิตเฉพาะง่ายขึ้น Git tag พร้อมหมายเลขบิลด์และเวอร์ชันเป็นแนวทางปฏิบัติที่ดีที่สุดสำหรับการจัดการรีลีส

ตัวอย่างการกำหนดค่า Build Number

ตัวอย่างโค้ด แสดงวิธีการกำหนดค่าการเพิ่ม Build Number อัตโนมัติบนทั้งสองแพลตฟอร์ม

versionCode ใน Gradle พร้อมตัวแปร CI

ใน Android versionCode สามารถกำหนดผ่านตัวแปรสภาพแวดล้อม CI/CD หากไม่ได้ตั้งค่าตัวแปร จะใช้ค่าดีฟอลต์

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

versionCode ได้รับค่าจากตัวแปร CI/CD ซึ่งรับประกันความไม่ซ้ำกันของหมายเลขสำหรับแต่ละบิลด์ในไปป์ไลน์

การเพิ่ม CFBundleVersion ผ่าน agvtool

ใน iOS ใช้ agvtool ซึ่งรวมอยู่ใน Xcode Command Line Tools สำหรับการเพิ่ม Build Number อัตโนมัติ

# เพิ่มหมายเลขบิลด์ขึ้น 1
xcrun agvtool next-version -all

# กำหนดหมายเลขบิลด์เฉพาะ
xcrun agvtool new-version -all "3.0.1"

แฟล็ก -all อัปเดตเวอร์ชันในทุกเป้าหมายของโปรเจกต์ ซึ่งรับประกันการซิงค์ค่าระหว่างแอปพลิเคชันหลักและส่วนขยาย

Fastlane สำหรับอัตโนมัติ

Fastlane เป็นเครื่องมือยอดนิยมสำหรับทำให้บิลด์แอปพลิเคชันมือถือเป็นอัตโนมัติ ปลั๊กอิน increment_build_number จะเพิ่ม Build Number โดยอัตโนมัติ

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

Fastlane รวมเข้ากับระบบ CI/CD ใดๆ และรองรับทั้งโปรเจกต์ Android และ iOS