xcconfig 多環境配置：2026 遠端 iOS 打包教學

xcconfig 多環境配置：2026 遠端 iOS 打包教學

📋 本文目錄

本地 Release 顯示正常，遠端 Archive 卻仍連到測試 API？
最快解法：把可公開的差異分層寫入 xcconfig 並提交版本控制，將密鑰與簽名憑據留在倉庫外，再用 Scheme、Build Configuration 和最終 Archive 三處交叉驗證。

這篇適合同時維護開發、測試與生產 API 環境，想減少 Xcode Build Settings 手動差異的獨立開發者。若你正把專案搬到遠端 Mac，或要讓腳本與 CI 非互動執行 Archive，本文也會處理絕對路徑、未提交檔案與測試設定誤入生產包等問題。

先拆開 Scheme、Configuration 與 Target

許多環境錯誤不是 xcconfig 語法錯，而是把不同層級的責任混在一起。

  • Scheme 決定一次執行、測試、Profile 或 Archive 要採用哪個 Build Configuration。
  • Build Configuration 是一組建構設定的名稱，例如 Debug、Release 或你自訂的測試配置。
  • Target 決定哪個 App、Widget、Notification Service 或其他擴充功能會被建構。
  • xcconfig 是保存與組合 Xcode Build Settings 的純文字檔，不是執行時環境管理器，也不是密鑰保管庫。
  • Info.plist 可以接收建構設定展開後的值，但這不代表所有執行時設定都應在建構階段寫死。

Apple 將 xcconfig 定義為保存及組合建構設定的檔案，並說明它可以依平台、架構與 Build Configuration 套用條件。你可以先參考 Apple 的 xcconfig 加入說明，再回到 Xcode 的最終計算值檢查設定是否真的生效。

共享基線與環境差異

建議把設定拆成三層，而不是替每個環境複製一份完整檔案：

  • 共享基線：產品名稱、通用編譯開關、共同的 Swift 設定，以及所有 Target 都需要的非敏感預設值。
  • 環境差異：開發、測試、生產的 API 網址、Bundle 標識後綴、功能開關或分析環境名稱。
  • 外部輸入：API Key、簽名密碼、私鑰相關資料、上傳 Token，以及只存在於建構主機的路徑。

這種分層的價值在於，你能看見「哪一層改了什麼」，而不是在兩個看似相同的設定檔中追查差異。Apple 的 Build Settings Reference 可用來核對設定名稱、適用範圍與 Xcode 目前支援的行為。

xcconfig 多環境配置：單一 App 的最小結構

只有 Debug 與 Release 的獨立開發者，不必先建立複雜的環境矩陣。先把 Xcode 目前真正需要的共同設定抽出來，再按環境加入少量差異。

可公開且適合納入版本控制的內容通常包括：

  • 非敏感的服務網址或環境名稱；
  • Bundle ID 的公開部分與產品顯示名稱；
  • 編譯旗標、Swift 版本相關設定及必要的搜尋路徑；
  • 由專案固定管理的 Info.plist 展開值。

不應直接提交的內容包括 API Key、簽名密碼、長期上傳 Token、私有憑證檔案位置，以及依賴某台電腦磁碟結構的絕對路徑。API 網址可以是 xcconfig 的環境差異，但 API Key 不應因為放進 xcconfig 就被視為安全；只要它進入 App 或 Archive，仍可能被取得。

先在本機執行一般 Build，確認開發環境可以啟動；接著單獨執行 Release Archive，確認生產網址、Bundle ID 與簽名設定沒有沿用 Debug。不要只看 xcconfig 文字內容，應在 Xcode 的 Build Settings 顯示「Resolved」或最終值，追查值來自專案、Target、配置檔還是命令列。

開發、測試與生產的映射邊界

自訂 Configuration 與 Scheme

當你有開發、測試與生產三套後端時，重點不是增加越多檔案，而是讓每個 Scheme 只有一個清楚的預設對應：

  • 開發 Scheme 只選開發 Configuration；
  • 測試 Scheme 只選測試 Configuration；
  • 發布 Scheme 的 Archive 動作固定選生產 Configuration。

請在 Xcode Scheme 自訂說明中核對 Run、Test、Profile 與 Archive 各動作的設定。尤其要檢查 Archive 動作；Run 顯示正確，不代表 Archive 使用同一套值。

API Key 與伺服器網址的處理

伺服器網址通常屬於「建構差異」，可以透過 xcconfig 展開到 Info.plist 或其他公開設定。但 API Key 要按用途拆開：

  • 只供建構腳本使用的 Key，從遠端環境變數或受控檔案注入；
  • 必須隨 App 發布的公開識別值，不要誤稱為秘密；
  • 真正的秘密不要直接進入 Info.plist、原始碼或 xcconfig；
  • 執行時需要輪換的設定，交由後端或安全的登入流程處理，而不是期待 xcconfig 提供保護。

提醒： xcconfig 負責傳遞建構設定，不會自動加密 API Key，也不會替你管理簽名憑據。將檔案放在「未提交」狀態，只是降低進入版本控制的機率，並不等於有權限隔離。

設定來源的覆蓋問題

同名設定可能在系統預設、專案、Configuration、Target、xcconfig 或命令列參數中出現。實際排查時，先記錄目前生效值，再向上追來源；不要只搜尋哪個檔案包含某個鍵名。

測試地址進入生產包，常見原因有三種：

  • 生產 Configuration 沒有明確覆蓋共享基線中的測試值；
  • Archive Scheme 仍指向測試 Configuration；
  • 命令列參數或遠端注入檔在最後階段覆蓋了預期值。

因此，生產配置應有一個明確的停止條件：只要最終計算值、Info.plist 展開結果或 Archive 內的環境標記仍包含測試識別字，就讓建構失敗，而不是交給發布者靠記憶判斷。

多 Target 的繼承與隔離

包含 Widget、Notification Service、Share Extension 或多平台 Target 時，共享基線只能放真正共同的設定。Bundle ID、Entitlements、App Group 與部署目標，通常需要按 Target 分別核對。

主 App 成功不代表整個產品合格

你應逐一檢查每個隨包交付的 Target：

  • Bundle ID 是否屬於正確的環境；
  • App Group 是否與主 App 的配置一致；
  • Entitlements 是否意外從另一個 Target 繼承；
  • 部署目標是否符合該擴充功能的實際要求；
  • Info.plist 中的服務網址是否已展開為預期值。

Apple 的 Xcode 多 Target 建構說明可用來核對 Target 的建構關係。不要因為主 App 已經成功 Archive，就跳過擴充功能的最終建構值。

遠端 Mac 的注入與可重現性

把專案搬到遠端 Mac 後，真正要驗證的是「乾淨檢出能否恢復」，不是遠端主機上曾經成功過一次。

你可以依照以下流程執行：

  1. 整理版本控制內容：提交共享 xcconfig、環境差異檔與 Scheme；移除密鑰、私有憑證及個人絕對路徑。
  2. 建立外部輸入：在遠端環境以受控檔案、環境變數或密鑰管理方式提供必要 Key，不把密碼直接寫入 xcconfig。
  3. 執行乾淨檢出：使用新的工作目錄還原專案，確認公開設定能自行載入，不能依賴本機未提交檔案。
  4. 非互動建構：透過腳本固定 Scheme、Configuration 與必要參數，避免 SSH 或 CI 工作階段等待人工選擇。
  5. 檢查最終值：在 Build Settings、Info.plist 展開結果及建構日誌中核對網址、Bundle ID、Target 與環境標記。
  6. 完成 Release Archive：不要用一般 Build 取代發布驗收，直接建立可檢查的 Archive。
  7. 重啟後再測：重啟遠端 Mac 或重新建立工作階段，再執行一次檢出與建構，確認設定不是暫存在使用者工作階段中。

若你正準備建立遠端環境，可先閱讀 遠端 Mac 的方案與交付選擇，再把上述流程當成驗收條件，而不是把「能連線」當成「能打包」。

iOS Archive 的發布驗收

Archive 是發布負責人應該信任的實際產物。Apple 的 建立 App Archive 說明與 驗證 App Archive 說明可用來核對建立及驗證步驟。

完成 Archive 後，至少保存以下檢查結果：

  • 實際採用的 Configuration 名稱；
  • 最終 Bundle ID 與版本資訊；
  • 服務網址及環境標記；
  • 每個 Target 的 Entitlements 與 App Group；
  • 必要的符號檔或其他發布產物；
  • 簽名身份、Provisioning Profile 與上傳所需資料是否匹配。

簽名資產與 xcconfig 是兩條不同的維護線。Provisioning Profile 應按 Apple 的 App Store Provisioning Profile 建立流程管理，不要把 Profile 密碼或私鑰內容塞入建構設定檔。

依條件選擇維護方式

  • 若只有一個 App、兩套配置，且沒有遠端建構需求：選共享基線加 Debug / Release 差異；先完成本地 Build 與 Archive。
  • 若同時有開發、測試、生產 API：增加明確的 Build Configuration 與 Scheme 映射；每次 Archive 都檢查最終網址。
  • 若有 Widget 或 Extension：保留專案級共享設定，但把 Bundle ID、Entitlements 與 App Group 放回各 Target 驗證。
  • 若要在遠端 Mac 或 CI 執行：把密鑰、簽名憑據與絕對路徑移出倉庫，採用可重建的外部注入。
  • 若生產包曾經出現測試值：停止發布，先加入自動檢測與失敗條件；不要只要求團隊「下次小心」。
  • 若長期重負載、需要實體 USB 或本地螢幕互動：優先評估自有 Mac；遠端 Mac 更適合臨時打包、持續建構與新環境驗證。

如果你需要完整處理遠端 Mac 的初始化與驗收，可再參考 MacDate 的遠端 Mac 服務入口，並先用乾淨檢出完成一次 Release Archive。這樣你得到的是可驗證的交付環境，而不是只確認遠端桌面能開啟。

對獨立開發者而言，現有電腦通常有三個限制：無法長時間保持在線、設定容易依賴本機狀態，而且每次更換環境都要重新確認 Xcode 與簽名資產。若你不需要購買一台 Mac 專門充當打包機，但又要反覆驗證遠端 Archive 能否恢復配置，租用 MacDate 的遠端 Mac 會比臨時改造個人電腦更容易控制；不過，長期固定重負載或需要實體介面的專案，仍應把自購 Mac 納入成本比較。

最後，先把公開建構差異提交到 xcconfig，再從遠端環境注入敏感值，並以最終 Archive 驗收環境邊界。這三個動作能把「本機看起來正常」轉成「新環境可以重建且不會誤發測試版本」。

延伸閱讀