.xcconfig — คืออะไร ไวยากรณ์และตัวแปรใน Xcode

.xcconfig คืออะไร?

.xcconfig (ไฟล์กำหนดค่า Xcode) คือไฟล์ข้อความธรรมดาที่มี Build Settings ในรูปแบบ PARAMETER_NAME = value ไฟล์ .xcconfig ใช้สำหรับการจัดการรวมศูนย์ของการกำหนดค่าการคอมไพล์ Xcode: มันแทนที่การแก้ไขฟิลด์ด้วยตนเองในอินเทอร์เฟซ Build Settings .xcconfig แต่ละไฟล์เชื่อมโยงกับ Build Configuration (Debug, Release) หรือกับโปรเจกต์ทั้งหมด และสามารถแทนที่ build setting ใด ๆ ได้: SWIFT_VERSION, IPHONEOS_DEPLOYMENT_TARGET, PRODUCT_BUNDLE_IDENTIFIER, CODE_SIGN_STYLE, PROVISIONING_PROFILE_SPECIFIER

ก่อนที่ .xcconfig จะปรากฏ การตั้งค่าการคอมไพล์ถูกเก็บไว้เฉพาะใน project.pbxproj ซึ่งเป็นไฟล์ไบนารี/plist ที่อ่านยากใน diff และไม่สามารถใส่ความคิดเห็นได้ .xcconfig แก้ปัญหานี้ได้: นักพัฒนาสามารถใส่ความคิดเห็นพารามิเตอร์ จัดกลุ่มตามความหมาย สร้างไฟล์ที่กำหนดเวอร์ชันได้สำหรับสภาพแวดล้อมต่าง ๆ และสืบทอดพารามิเตอร์ระหว่างไฟล์ สิ่งนี้ทำให้ .xcconfig กลายเป็นมาตรฐานโดยพฤตินัยสำหรับการจัดการการกำหนดค่าในโปรเจกต์ iOS

ไฟล์ .xcconfig อยู่ภายในโปรเจกต์ โดยปกติในโฟลเดอร์ Configurations/ หรือ BuildConfig/ แต่ละไฟล์สอดคล้องกับ Build Configuration หนึ่ง: Debug.xcconfig, Release.xcconfig, Staging.xcconfig นอกจากนี้ ยังมีการสร้างไฟล์ Shared.xcconfig ทั่วไป ซึ่งรวมอยู่ในการกำหนดค่าทั้งหมดผ่าน #include สิ่งนี้ช่วยให้กำหนดพารามิเตอร์ทั่วไปครั้งเดียวและแทนที่พารามิเตอร์เฉพาะในไฟล์กำหนดค่า

ข้อดีเหนือ UI Build Settings

ความสามารถในการอ่าน diff: การเปลี่ยนแปลงใน .xcconfig จะมองเห็นใน Git diff เป็นบรรทัดปกติ ต่างจาก project.pbxproj ที่การเปลี่ยนลำดับฟิลด์แสดงการเปลี่ยนแปลง 50 บรรทัดสำหรับการแก้ไขพารามิเตอร์เดียว ความคิดเห็น: ใน .xcconfig คุณสามารถอธิบายได้ว่าทำไมแต่ละพารามิเตอร์จึงจำเป็น การสืบทอด: คุณสามารถสร้างการกำหนดค่าฐานด้วยการตั้งค่าร่วม และแทนที่เฉพาะพารามิเตอร์ที่จำเป็นสำหรับ Debug และ Release

ไวยากรณ์และโครงสร้างของ .xcconfig

ตัวแปรและการแทนที่

ไวยากรณ์ของ .xcconfig เรียบง่ายที่สุดเท่าที่จะเป็นไปได้: แต่ละบรรทัดคือพารามิเตอร์ ชื่อและค่าคั่นด้วยเครื่องหมายเท่ากับ ช่องว่างรอบ = จะถูกละเว้น ค่าสามารถมีตัวแปรในรูปแบบ $(VARIABLE_NAME) หรือ ${VARIABLE_NAME} ความคิดเห็นเริ่มต้นด้วย // หรือ # และใช้ไปจนถึงสิ้นสุดบรรทัด บรรทัดสามารถต่อในบรรทัดถัดไปโดยใช้แบ็กสแลช \ บรรทัดว่างจะถูกละเว้น

ตัวแปรใน .xcconfig สามารถอ้างอิงถึงตัวแปรอื่น ๆ ทำให้เกิด ค่าผสม ตัวอย่างเช่น: PRODUCT_NAME = MyApp, PRODUCT_BUNDLE_IDENTIFIER = com.example.$(PRODUCT_NAME) Xcode จะประเมินค่าในเวลาคอมไพล์ โดยแทนที่ค่าจริงของตัวแปร AGP ยังรองรับตัวแปรระบบ: ARCHS, SDK_NAME, CONFIGURATION, PLATFORM_NAME ซึ่งกำหนดโดยสภาพแวดล้อมการคอมไพล์

สำหรับการกำหนดค่าแบบมีเงื่อนไข จะใช้คำสั่งแพลตฟอร์มในวงเล็บเหลี่ยม: PARAMETER[sdk=iphoneos*] = value ตัวอย่างเช่น SUPPORTED_PLATFORMS[sdk=iphoneos*] = iphoneos กำหนดพารามิเตอร์สำหรับการคอมไพล์ iOS เท่านั้น ไวด์การ์ดรองรับ: * (อักขระใด ๆ), ? (อักขระเดียว) คำสั่งแบบมีเงื่อนไขช่วยให้มี .xcconfig ไฟล์เดียวสำหรับหลายแพลตฟอร์มและกำหนดค่าที่แตกต่างกันสำหรับ iOS และ macOS ในไฟล์เดียว

// Shared.xcconfig — การตั้งค่าโปรเจกต์ร่วม
SWIFT_VERSION = 5.0
IPHONEOS_DEPLOYMENT_TARGET = 16.0
SDKROOT = iphoneos
TARGETED_DEVICE_FAMILY = 1,2

// ตัวระบุ Bundle — สร้างจากคำนำหน้าและชื่อ
BUNDLE_ID_PREFIX = com.example
PRODUCT_NAME = MyApp
PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)

// การตั้งค่าแบบมีเงื่อนไขสำหรับ macOS
SUPPORTED_PLATFORMS[sdk=macosx*] = macosx
PRODUCT_BUNDLE_IDENTIFIER[sdk=macosx*] = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).mac

// การกำหนดเวอร์ชัน
MARKETING_VERSION = 2.4.1
CURRENT_PROJECT_VERSION = 37

การสืบทอดการกำหนดค่าผ่าน #include

#include คือคำสั่งพรีโพรเซสเซอร์ของ .xcconfig ที่รวมเนื้อหาของไฟล์ .xcconfig อื่น คำสั่งสามารถซ้อนกันได้: Shared.xcconfig สามารถ #include “Base.xcconfig”, Debug.xcconfig สามารถ #include “Shared.xcconfig” ห่วงโซ่การสืบทอดช่วยให้สร้างลำดับชั้นของการกำหนดค่า โดยแต่ละระดับจะแทนที่พารามิเตอร์ของระดับก่อนหน้า #include ทำงานบนหลักการเขียนครั้งสุดท้าย: หากพารามิเตอร์เดียวกันถูกกำหนดทั้งในไฟล์ที่รวมและไฟล์หลัก ค่าจากไฟล์หลักจะมีความสำคัญ

ลำดับชั้นที่ถูกต้องสำหรับโปรเจกต์ iOS ทั่วไป: Base.xcconfig (พารามิเตอร์ทั่วไปที่สุด) → Shared.xcconfig (การตั้งค่าโปรเจกต์) → Debug.xcconfig หรือ Release.xcconfig Base.xcconfig กำหนดมาตรฐาน (SWIFT_VERSION, DEPLOYMENT_TARGET), Shared.xcconfig — ลักษณะเฉพาะของโปรเจกต์ (PRODUCT_NAME, PREPROCESSOR_DEFINITIONS), Debug/Release — สภาพแวดล้อม (DEBUG_INFORMATION_FORMAT, OPTIMIZATION_CFLAGS) #include ไม่อนุญาตให้มีวงจร — Xcode จะแสดงข้อผิดพลาดหากตรวจพบการพึ่งพาแบบวงจร

ตัวอย่าง: Config/Base.xcconfig → Config/iOS/Shared.xcconfig → Config/iOS/Debug.xcconfig โครงสร้างนี้ช่วยให้นำ Base กลับมาใช้ใหม่สำหรับโปรเจกต์ iOS, macOS และ tvOS และ Shared สำหรับ iOS เท่านั้น หมายเหตุ: #include ใช้ชื่อไฟล์หรือพาธสัมพัทธ์จากตำแหน่งของ .xcconfig หลัก ไม่แนะนำให้ใช้พาธสัมบูรณ์ — มันจะทำให้การคอมไพล์เสียหายบนเครื่องอื่นและใน CI/CD

// --- Config/Base.xcconfig ---
SWIFT_VERSION = 5.0
ENABLE_MODULE_VERIFIER = YES
CLANG_ENABLE_MODULES = YES

// --- Config/iOS/Shared.xcconfig ---
#include "../Base.xcconfig"
IPHONEOS_DEPLOYMENT_TARGET = 16.0
PRODUCT_BUNDLE_IDENTIFIER = com.example.myapp

// --- Config/iOS/Debug.xcconfig ---
#include "Shared.xcconfig"
OPTIMIZATION_CFLAGS = -O0
DEBUG_INFORMATION_FORMAT = dwarf
SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG
ENABLE_TESTABILITY = YES

// --- Config/iOS/Release.xcconfig ---
#include "Shared.xcconfig"
OPTIMIZATION_CFLAGS = -Osize
DEBUG_INFORMATION_FORMAT = dwarf-with-dsym
SWIFT_COMPILATION_MODE = wholemodule

การเชื่อมต่อ .xcconfig ในโปรเจกต์ Xcode

การกำหนดค่าระดับโปรเจกต์และระดับเป้าหมาย

การเชื่อมต่อ .xcconfig กับโปรเจกต์ทำได้ใน Project Info → Configurations สำหรับแต่ละ Build Configuration (Debug, Release, AdHoc) ให้เลือก .xcconfig ที่เกี่ยวข้องจากเมนูแบบเลื่อนลง “Based on Configuration File” หากการกำหนดค่าไม่ได้เชื่อมโยงกับไฟล์ Xcode จะใช้ค่าจาก project.pbxproj หลังจากเลือก .xcconfig พารามิเตอร์ทั้งหมดจากไฟล์จะทำงานสำหรับการกำหนดค่านั้น

สิ่งสำคัญคือต้องแยกความแตกต่างระหว่างการกำหนดค่าระดับ โปรเจกต์ และระดับ เป้าหมาย .xcconfig ระดับโปรเจกต์จะกำหนดพารามิเตอร์เริ่มต้นสำหรับทุกเป้าหมาย .xcconfig ระดับเป้าหมายจะแทนที่พารามิเตอร์เหล่านั้นสำหรับเป้าหมายเฉพาะ หากไม่ได้ตั้งค่าพารามิเตอร์ใน .xcconfig ระดับเป้าหมาย จะใช้ค่าจากระดับโปรเจกต์ หากไม่ได้ตั้งค่าที่นั่นเช่นกัน จะใช้ค่าจาก project.pbxproj กฎปฏิบัติ: วางพารามิเตอร์ทั่วไป (การคอมไพล์, เวอร์ชัน) ในระดับโปรเจกต์ และลักษณะเฉพาะของเป้าหมาย (ตัวระบุ bundle, provisioning) ในระดับเป้าหมาย

ในกรณีที่เกิดข้อขัดแย้งระหว่าง .xcconfig และ UI Build Settings ค่าจาก UI จะมีความสำคัญ (มันแทนที่ .xcconfig) สิ่งนี้อาจทำให้เกิดความสับสน: นักพัฒนาเปลี่ยนแปลง Build Setting ใน UI โดยไม่รู้ว่า .xcconfig ระบุค่าที่แตกต่างกัน ขอแนะนำให้ เปลี่ยนไปใช้ .xcconfig อย่างสมบูรณ์ และไม่แตะต้อง UI Build Settings หากต้องการตรวจสอบว่าพารามิเตอร์ใดถูกนำไปใช้ ให้ใช้ xcrun xcodebuild -showBuildSettings — คำสั่งจะแสดงค่าสุดท้ายของพารามิเตอร์ทั้งหมดหลังจากแก้ไขทุกระดับ

ตัวอย่าง: สภาพแวดล้อม Dev, Staging, Production

พิจารณาการกำหนดค่าสามระดับ: Dev (การพัฒนาท้องถิ่น), Staging (เซิร์ฟเวอร์ทดสอบ), Production (การเผยแพร่) สำหรับแต่ละสภาพแวดล้อมจะสร้าง .xcconfig แยกต่างหาก ซึ่งกำหนดค่า API_URL, การบันทึก และใบรับรองที่แตกต่างกัน Dev ใช้ localhost, Staging ใช้ staging.api.example.com, Production ใช้ api.example.com ทั้งสามสืบทอด Shared.xcconfig ทั่วไปผ่าน #include

พารามิเตอร์หลักที่แตกต่างกันระหว่างสภาพแวดล้อมคือ PRODUCT_BUNDLE_IDENTIFIER สำหรับ Dev: com.example.myapp.dev, สำหรับ Staging: com.example.myapp.staging, สำหรับ Production: com.example.myapp ID bundle ที่แตกต่างกันช่วยให้ติดตั้งทั้งสามเวอร์ชันบนอุปกรณ์เครื่องเดียวพร้อมกันได้ CODE_SIGN_IDENTITY (Apple Development สำหรับ Dev, Apple Distribution สำหรับ Production) และ PROVISIONING_PROFILE_SPECIFIER ก็แตกต่างกันเช่นกัน

ในการส่งผ่านค่าไปยังโค้ด จะใช้ INFOPLIST_PREFIX_HEADER หรือ OTHER_SWIFT_FLAGS กับพรีโพรเซสเซอร์ -D Swift ไม่มีพรีโพรเซสเซอร์ ดังนั้นจึงใช้ Active Compilation Conditions: SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEV ในโค้ด: #if DEV; #elseif STAGING; #else; #endif สำหรับ Objective-C จะใช้ GCC_PREPROCESSOR_DEFINITIONS สิ่งนี้ช่วยให้คอมไพล์โค้ดที่แตกต่างกันสำหรับสภาพแวดล้อมที่แตกต่างกันโดยไม่ต้องเปลี่ยนไฟล์ต้นฉบับ

// --- Config/Dev.xcconfig ---
#include "Shared.xcconfig"

PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).dev
CODE_SIGN_IDENTITY = Apple Development
PROVISIONING_PROFILE_SPECIFIER = Dev Profile

SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG DEV
OTHER_SWIFT_FLAGS = -D DEV

// URL API ผ่าน Info.plist — ค่าถูกแทนที่
API_BASE_URL = http://localhost:3000/api

// --- Config/Staging.xcconfig ---
#include "Shared.xcconfig"

PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).staging
CODE_SIGN_IDENTITY = Apple Development
PROVISIONING_PROFILE_SPECIFIER = Staging Profile

SWIFT_ACTIVE_COMPILATION_CONDITIONS = STAGING
OTHER_SWIFT_FLAGS = -D STAGING
API_BASE_URL = https://staging.api.example.com/v2

// --- Config/Production.xcconfig ---
#include "Shared.xcconfig"

PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)
CODE_SIGN_IDENTITY = Apple Distribution
PROVISIONING_PROFILE_SPECIFIER = AppStore Distribution

SWIFT_ACTIVE_COMPILATION_CONDITIONS = RELEASE
API_BASE_URL = https://api.example.com/v3

.xcconfig และ Info.plist: การส่งผ่านค่า

ค่าจาก .xcconfig สามารถส่งต่อไปยัง Info.plist ผ่านตัวแปร $(PARAMETER_NAME) หากพารามิเตอร์ถูกกำหนดใน .xcconfig (เช่น API_BASE_URL) ก็สามารถใช้ใน Info.plist: <key>ApiBaseUrl</key><string>$(API_BASE_URL)</string> ในเวลาคอมไพล์ Xcode จะแทนที่ $(API_BASE_URL) ด้วยค่าจาก .xcconfig สิ่งนี้ช่วยให้กำหนดค่าแอปพลิเคชันได้โดยไม่ต้องเปลี่ยนโค้ด — เพียงแค่เปลี่ยนสคีมา

พารามิเตอร์ .xcconfig ที่ใช้ใน Info.plist ต้องเป็น สาธารณะ — มันจะไปอยู่ในไบนารีและมองเห็นได้ในแอปพลิเคชันที่ถูกดีคอมไพล์ อย่าใช้ .xcconfig สำหรับค่าลับ (โทเค็น, รหัสผ่าน) — ให้ใช้บริการเช่น Firebase Remote Config ที่ทำงานบนเซิร์ฟเวอร์ .xcconfig สำหรับ Info.plist เหมาะสำหรับ: URL ของเซิร์ฟเวอร์, ชื่อเอนทิตี, ตัวระบุตัวติดตาม, feature flags

การเข้าถึงค่า Info.plist ในโค้ด: Bundle.main.object(forInfoDictionaryKey: “ApiBaseUrl”) สำหรับ Objective-C/Swift หากค่าถูกตั้งผ่าน .xcconfig มันจะถูกแทนที่และพร้อมใช้งานใน Bundle main.infoDictionary วิธีการนี้ดีกว่า BuildConfigField (เช่นใน Android) เพราะ Info.plist เป็นกลไกมาตรฐานของ iOS และค่าของมันพร้อมใช้งานสำหรับคอมโพเนนต์ระบบทั้งหมด รวมถึง extensions, widgets และ Siri Intents