Gym (Fastlane): มันคืออะไร, การสร้าง IPA และการอัตโนมัติในการพัฒนาแอป

Gym (Fastlane) คืออะไร?

Gym (Fastlane) — เป็นส่วนประกอบของระบบนิเวศ Fastlane ที่รับประกันการสร้างแอปพลิเคชัน iOS ในรูปแบบ IPA ผ่านคำสั่งเทอร์มินัลเดียว มันทำให้กระบวนการเรียก xcodebuild ที่ซับซ้อนด้วยแฟลกมากมายเป็นนามธรรม และมอบอินเทอร์เฟซที่เรียบง่ายแก่นักพัฒนาโดยมีค่าเริ่มต้นที่เหมาะสม.

ใน Xcode การสร้าง IPA ต้องเปิดโครงการ เลือกแผนภาพ ตั้งค่า Archive และ Export ระบุวิธีการเผยแพร่และรอให้เสร็จสิ้น. การอัตโนมัติการสร้าง ผ่าน Gym ช่วยขจัดขั้นตอนที่ทำด้วยตนเองและรับประกันว่าการสร้างแต่ละครั้งจะดำเนินการด้วยพารามิเตอร์เดียวกัน — ซึ่งมีความสำคัญอย่างยิ่งสำหรับความสามารถในการคาดการณ์ของ CI/CD pipeline.

ตามข้อมูล SwiftLee (2024), ทีมที่ใช้ Gym ในการสร้างใช้เวลาน้อยกว่า 40% ในการตั้งค่ากระบวนการเผยแพร่เมื่อเทียบกับการส่งออกด้วยตนเองผ่าน Xcode Organizer Gym ยังสร้างล็อกการสร้างแบบละเอียดพร้อมระบุแต่ละขั้นตอนของ xcodebuild ซึ่งช่วยให้การดีบักบิลด์ที่ล้มเหลวและการวิเคราะห์ข้อผิดพลาดการคอมไพล์ทำได้ง่ายขึ้น.

ใช้ Gym ในโครงการ iOS ใด ๆ ที่ต้องการการสร้าง IPA เป็นประจำสำหรับการทดสอบหรือเผยแพร่ — นี่เป็นวิธีเดียวที่จะรับประกันการตั้งค่าการสร้างที่เหมือนกันบนทุกเครื่องในทีม.

Gym สร้าง IPA อย่างไร: กระบวนการและพารามิเตอร์

กระบวนการสร้าง IPA ผ่าน Gym

การสร้าง IPA ผ่าน Gym ประกอบด้วยสามขั้นตอนตามลำดับ: การเก็บถาวรโครงการผ่าน xcodebuild, การส่งออกไฟล์ถาวรเป็นแพ็กเกจไบนารี และการแพ็คเกจในรูปแบบ IPA พร้อมลายเซ็น Gym จะกำหนดประเภทของโครงการ (target เดียวหรือ workspace) โดยอัตโนมัติและเลือกวิธีการสร้างที่ถูกต้อง.

ในขั้นตอนการเก็บถาวร Gym จะเริ่ม xcodebuild archive ด้วยพารามิเตอร์แผนภาพและการตั้งค่าที่ระบุในโครงการ หลังจากสร้างไฟล์ถาวร .xcarchive สำเร็จ Gym จะเริ่ม xcodebuild -exportArchive ด้วยวิธีการส่งออกที่เลือกไว้. การส่งออก IPA — เป็นกระบวนการแปลงไฟล์ถาวร .xcarchive เป็นไฟล์ติดตั้ง .ipa รวมถึงทรัพยากรและลายเซ็นที่จำเป็นทั้งหมด.

พารามิเตอร์การส่งออกการสร้าง

วิธีการส่งออกกำหนดประเภทของ Provisioning Profile ที่จะใช้สำหรับการลงนาม IPA Gym รองรับสี่วิธีการ: development สำหรับการดีบักบนอุปกรณ์ของนักพัฒนา, app-store สำหรับการเผยแพร่ใน App Store, ad-hoc สำหรับการทดสอบเบต้าบนจำนวนอุปกรณ์ที่จำกัด และ enterprise สำหรับการเผยแพร่องค์กร.

พารามิเตอร์เพิ่มเติมรวมถึงการระบุ export_options_plist สำหรับการปรับแต่งการส่งออกอย่างละเอียด การลบ Swift overlay เพื่อลดขนาด IPA และการจัดการ bitcode Gym ยังรองรับการสร้างสำหรับซิมิวเลเตอร์ผ่านแฟล็ก --skip_package_ipa ซึ่งมีประโยชน์สำหรับการตรวจสอบโค้ดอย่างรวดเร็วโดยไม่ต้องส่งออกที่สมบูรณ์.

# การสร้าง IPA พื้นฐานผ่าน Gym
fastlane gym --workspace "MyApp.xcworkspace" --scheme "MyApp"

# การสร้างพร้อมระบุวิธีการส่งออก
fastlane gym --export_method app-store

# การสร้างเฉพาะไฟล์เก็บถาวรโดยไม่ส่งออก IPA
fastlane gym --skip_package_ipa

การตั้งค่า Gym ผ่าน Gymfile

Gymfile — เป็นไฟล์การตั้งค่า Fastlane ที่เก็บพารามิเตอร์การสร้างทั้งหมดในรูปแบบ Ruby ที่มีโครงสร้าง ต่างจากการส่งแฟล็กผ่านบรรทัดคำสั่ง Gymfile ช่วยให้สามารถกำหนดการตั้งค่าในรีโพจิทอรีและรับประกันว่านักพัฒนาและ CI ทั้งหมดใช้การตั้งค่าการสร้างที่เหมือนกัน.

# Gymfile — การกำหนดค่าการสร้าง
workspace("MyApp.xcworkspace")
scheme("MyApp")
export_method(:app-store)
configuration("Release")
output_directory("./build")
output_name("MyApp.ipa")
include_symbols(true)
include_bitcode(false)

พารามิเตอร์ export_method ใน Gymfile สอดคล้องกับประเภทโปรไฟล์จาก Apple Developer Portal สำหรับการเผยแพร่ App Store ใช้ :app-store, สำหรับการทดสอบ — :development หรือ :ad-hoc. พารามิเตอร์ configuration กำหนดการตั้งค่าการสร้าง: Release สำหรับการเผยแพร่หรือ Debug สำหรับเวอร์ชันดีบัก.

พารามิเตอร์ include_bitcode ควบคุมการรวม bitcode ใน IPA Apple เคยต้องการ bitcode สำหรับแอป watchOS และ tvOS แต่สำหรับ iOS สามารถปิดการตั้งค่านี้เพื่อลดขนาดไฟล์ไบนารี. include_symbols รวมไฟล์สัญลักษณ์การดีบัก .dSYM ซึ่งจำเป็นสำหรับการแปลงสัญลักษณ์ของล็อก crash จาก App Store Connect หรือบริการติดตามของบุคคลที่สาม.

พารามิเตอร์เพิ่มเติมของ Gymfile รวมถึง export_options_plist สำหรับไฟล์ plist การส่งออกที่กำหนดเอง, silent สำหรับการซ่อนผลลัพธ์ส่วนเกินในล็อก และ build_path สำหรับการระบุไดเรกทอรีชั่วคราวของการสร้าง พารามิเตอร์เหล่านี้มีประโยชน์เมื่อบูรณาการ Gym ใน CI/CD pipeline ที่ซับซ้อนโดยมีข้อกำหนดพิเศษเกี่ยวกับอาร์ติแฟก.

คำสั่ง Gym สำหรับการสร้างแอป

อินเทอร์เฟซคำสั่ง Gym มีพารามิเตอร์พื้นฐานสำหรับสถานการณ์การสร้างทั่วไปและแฟล็กขั้นสูงสำหรับการปรับแต่งพฤติกรรมอย่างละเอียด พารามิเตอร์ส่วนใหญ่สามารถส่งผ่านบรรทัดคำสั่งหรือ Gymfile โดยที่อาร์กิวเมนต์บรรทัดคำสั่งจะมีความสำคัญเหนือไฟล์การตั้งค่า.

คำสั่ง fastlane gym โดยไม่มีพารามิเตอร์จะใช้การตั้งค่าจาก Gymfile หรือตรวจสอบโครงการในไดเรกทอรีปัจจุบันโดยอัตโนมัติ สำหรับโครงการที่มีหลาย target ต้องระบุ --scheme และ --workspace สำหรับการเลือกการตั้งค่าการสร้างเป้าหมายที่ถูกต้อง.

คำสั่งการสร้างทั่วไป

สำหรับการสร้างดีบักอย่างรวดเร็ว ใช้ fastlane gym --export_method development — มันสร้าง IPA ด้วยโปรไฟล์ Development สำหรับการติดตั้งบนอุปกรณ์ของนักพัฒนา. การสร้าง IPA สำหรับ App Store ต้องใช้แฟล็ก --export_method app-store และการใช้ใบรับรอง Distribution ซึ่งต้องตั้งค่าไว้ล่วงหน้าใน Match หรือ Keychain.

# การสร้างสำหรับ App Store ด้วยชื่อที่กำหนดเอง
fastlane gym --export_method app-store --output_name "Release_1.0.ipa"

# การสร้างพร้อมล้างข้อมูลก่อนเก็บถาวร
fastlane gym --clean --configuration Debug

# การสร้างสำหรับซิมูเลเตอร์โดยไม่ต้องใช้ IPA
fastlane gym --skip_package_ipa --destination "generic/platform=iOS Simulator"

แฟล๊ก --clean จะลบไฟล์ชั่วคราวของการสร้างครั้งก่อนก่อนเริ่มทำงาน ซึ่งป้องกันการใช้แคชที่ล้าสมัยและรับประกันบิลด์ที่สะอาด. แฟล๊ก --destination ช่วยให้สามารถระบุแพลตฟอร์มเป้าหมายสำหรับการสร้าง: iOS Simulator, iOS Device หรือ macOS Catalyst.

การบูรณาการ Gym ใน CI/CD pipeline

การบูรณาการ Gym กับ CI/CD — แนวปฏิบัติมาตรฐานสำหรับทีมพัฒนา iOS ที่มุ่งสู่การจัดส่งอย่างต่อเนื่อง Gym ถูกเริ่มทำงานใน pipeline GitHub Actions, GitLab CI, Bitrise หรือ Jenkins หลังจากขั้นตอนการทดสอบและก่อนส่งไปยัง TestFlight หรือ App Store.

pipeline iOS CI/CD ทั่วไปรวมถึง: การโคลนรีโพจิทอรี, การติดตั้ง dependencies ผ่าน CocoaPods หรือ SPM, การตั้งค่าใบรับรองผ่าน Match, การสร้าง IPA ผ่าน Gym และการอัปโหลดผ่าน Pilot หรือ Deliver. GitLab CI เป็น ระบบการบูรณาการอย่างต่อเนื่องจาก GitLab ที่ช่วยให้สามารถเริ่มสร้างได้ทุกครั้งที่มีการ push ไปยังรีโพจิทอรี.

# ตัวอย่างขั้นตอนการสร้างใน GitLab CI
fastlane gym --scheme "MyApp" \
      --export_method app-store \
      --output_directory "$CI_PROJECT_DIR/build"
      
# บันทึก IPA เป็นอาร์ติแฟกต์ของการสร้าง
cp "build/MyApp.ipa" "$CI_PROJECT_DIR/artifacts/"

เพื่อให้ Gym ทำงานได้อย่างถูกต้องใน CI จำเป็นต้องตั้งค่า xcodebuild การเข้าถึง Keychain ที่มีใบรับรอง ทำได้ผ่านคำสั่ง security unlock-keychain ก่อนเริ่ม Gym ถ้าใช้ Match ใบรับรองจะถูกติดตั้งโดยอัตโนมัติและไม่ต้องตั้งค่า Keychain แยกต่างหาก — Match จะสร้างชุดคีย์ชั่วคราวสำหรับการสร้างเอง.

หลังจากสร้าง IPA สำเร็จ ไฟล์นี้สามารถถูกส่งต่อไปยังขั้นตอนถัดไปของ pipeline: อัปโหลดไปยัง TestFlight ผ่าน Pilot หรือส่งไปยัง App Store Connect ผ่าน Deliver ตั้งค่า ตัวแปรสภาพแวดล้อม ของระบบ CI สำหรับเก็บข้อมูลประจำตัว Apple Developer รวมถึง FASTLANE_APPLE_API_KEY และ MATCH_PASSWORD เพื่อให้ทุกขั้นตอนของ pipeline ทำงานโดยไม่ต้องป้อนข้อมูลแบบโต้ตอบ.

ข้อผิดพลาดการสร้าง Gym ทั่วไป

เมื่อใช้ Gym นักพัฒนามักพบข้อผิดพลาดที่เกี่ยวข้องกับการตั้งค่า xcodebuild ที่ไม่ถูกต้อง การขาดใบรับรอง หรือความไม่เข้ากันของเวอร์ชัน Xcode. การวินิจฉัยข้อผิดพลาด Gym เริ่มต้นด้วยการวิเคราะห์ล็อกการสร้างที่สมบูรณ์ ซึ่งแสดงผลในคอนโซลหลังจากแต่ละคำสั่งเสร็จสิ้น.

ข้อผิดพลาด «error: No matching provisioning profiles found» บ่งชี้ถึงการไม่มี Provisioning Profile ที่เหมาะสมสำหรับวิธีการส่งออกที่เลือก วิธีแก้: ตรวจสอบว่า Match หรือ Keychain มีโปรไฟล์ที่ถูกต้องสำหรับ export_method ที่ระบุ. Provisioning Profile ต้องตรงกับตัวระบุแอปและประเภทใบรับรอง (Development หรือ Distribution) เพื่อการลงนาม IPA ที่สำเร็จ.

ข้อผิดพลาด «error: Signing for requires a development team» เกิดขึ้นเมื่อไม่ได้ระบุทีมพัฒนาในโครงการ วิธีแก้: เพิ่ม DEVELOPMENT_TEAM ในการตั้งค่าการสร้างของโครงการหรือระบุ team_id ใน Gymfile ผ่านพารามิเตอร์ export_team_id ซึ่งมีความสำคัญโดยเฉพาะสำหรับโครงการที่ทำงานกับหลายบัญชี Apple Developer.

เมื่อเกิดข้อผิดพลาด «error: Multiple commands produce...» เกิดความขัดแย้งของไฟล์ผลลัพธ์ระหว่าง target ต่าง ๆ ใน workspace วิธีแก้: ตั้งค่าเส้นทางผลลัพธ์ที่ไม่ซ้ำกันสำหรับแต่ละ target ใน Build Settings ของโครงการ Xcode หรือใช้ระบบ build ใหม่ ซึ่งเปิดใช้งานโดยค่าเริ่มต้นใน Xcode 14 ขึ้นไป Gym รองรับทั้งสองตัวเลือกผ่านแฟล็ก --use_legacy_build_system.