xcconfig 複数環境設定：2026 リモート iOS ビルド手順

本番の設定でArchiveしたはずなのに、リモート Macでは検証用APIへ接続するなら、公開できる差分はxcconfigへ分け、秘密情報は外部から注入し、最後に完成したArchiveを検収してください。Debug、検証、本番を別Targetへ複製するのではなく、共有基盤、Scheme、Build Configuration、最終成果物の順に確認する方法が安全です。

開発・検証・本番APIを並行して管理し、Xcode Build Settingsの手作業を減らしたい独立開発者向けです。
リモート Macへ移行する小規模チームや、スクリプトでiOS Archiveを繰り返す担当者にも適しています。

単一アプリでは、まず共有基盤と環境差分を分けます

典型的な失敗は、手元のReleaseビルドは正常なのに、リモート Macで作ったArchiveだけが検証用サーバーを参照するケースです。原因は、xcconfigファイルの有無ではなく、最終的にどのTarget、Scheme、Build Configurationがどの値を採用したかを確認していないことにあります。

xcconfigはXcodeのBuild Settingsを保存・組み合わせるためのテキスト形式の設定ファイルです。AppleのBuild Configurationファイルをプロジェクトへ追加する公式手順でも、プロジェクトの設定ファイルとして割り当てる流れが説明されています。

構成は次の3層に分けると、単一アプリでも管理しやすくなります。

• 共有基盤：Swiftのコンパイル設定、共通の検索パス、共通の識別子規則など
• 環境差分：APIの向き先、表示名、機能フラグ、環境名など
• 外部入力：API Key、署名に関する秘密情報、証明書のパスワード、アップロード用Tokenなど

共有基盤と環境差分はリポジトリで管理できます。一方、外部入力までxcconfigへ書き込むと、アクセス権を持つ人やログ保存先へ秘密値が広がります。xcconfigは秘密情報を保護する仕組みではないため、鍵の保管場所として扱わないでください。

DebugとReleaseだけの構成は、設定を増やしすぎない方が安定します

単一アプリでDebugとReleaseしかない場合、最初から環境ごとにTargetを増やす必要はありません。まず既存のBuild Configurationで共通値を抽出し、環境によって変わる値だけを個別のxcconfigへ置きます。

Xcodeの初期値をすべてコピーする方法は避けてください。設定ファイルに同じ値を大量に複製すると、Xcodeの既定値が変わった際に差分の所在が分からなくなります。AppleのBuild Settings Referenceで意味を確認し、プロジェクト固有の値だけを明示する方が追跡しやすくなります。

ローカルで確認する値

開発用のBuildでは、次のような値を確認します。

• 開発用APIの識別子と接続先
• Debug用の表示名や機能フラグ
• 開発用Bundle IDとEntitlements
• Info.plistへ展開される環境名

ただし、サーバーアドレスが公開可能でも、同じファイルにAPI Keyを置いてよいとは限りません。公開設定と認証情報は別の入力として管理してください。

Archiveで確認する値

Release Archiveでは、Schemeが選んだBuild Configurationと、実際に生成されたInfo.plistの値を確認します。ファイルがリポジトリに存在することは、設定が採用された証拠ではありません。Xcodeの設定画面に表示される最終計算値や、生成物に含まれるInfo.plistを確認してください。

開発・検証・本番は、Schemeとの対応を固定します

複数のAPI環境を持つ場合は、名前の似た設定を増やすより、対応関係を固定することが重要です。たとえば、開発用Schemeは開発用Configuration、検証用Schemeは検証用Configuration、本番用SchemeはRelease相当の本番用Configurationだけを選ぶようにします。

AppleのBuild Schemeをカスタマイズする説明を確認し、Run、Test、Profile、Archiveの各アクションがどのConfigurationを使うかを個別に点検してください。Runだけを確認してArchiveを確認しないと、手元では問題が見えないまま本番用成果物へ検証設定が入ります。

xcconfigで環境を分ける判断

• 開発者がローカルで動作確認するだけなら、開発用Configurationを選びます。
• QAや社内配布向けなら、検証用Configurationと検証用Schemeを組み合わせます。
• App Store提出用なら、本番用Configurationと本番用Archive設定だけを許可します。
• 本番Schemeが検証用xcconfigを継承していたら、Archiveを止めて継承元から直します。

同名のBuild Settingが複数箇所にある場合、設定値の出所を確認せずにファイルを編集してはいけません。システム既定値、プロジェクト、Configuration、xcconfig、Target、コマンドライン引数など、複数の層が最終値に影響します。優先関係はAppleのBuild Settings説明とXcode上のResolved値を突き合わせて確認してください。

複数Targetでは、共有設定と配布対象を切り分けます

Widget、Notification Service Extension、Share Extensionを含む場合、主アプリのArchive成功だけでは検収完了になりません。各Targetに別のBundle ID、Entitlements、App Group、Deployment Targetが必要になることがあるためです。

AppleのXcodeで複数Targetを構築する説明に沿って、プロジェクトレベルの共通値とTarget固有値を分けて確認します。主アプリの設定をそのままExtensionへ継承させると、Bundle IDやApp Groupが意図せず同じ値になる場合があります。

Targetごとの検収表

署名資産も同じ設定ファイルへ混ぜないでください。Provisioning Profileは、必要に応じてApp Store用Provisioning Profileを作成するAppleの手順に従って別途管理します。

リモート Macでは、設定の注入元と再現性を先に検査します

リモート Macへ移す前に、リポジトリを新しい作業ディレクトリへ展開し、公開設定だけでどこまで復元できるかを確認します。絶対パス、個人のホームディレクトリ、未追跡ファイルを前提にしたxcconfigは、別環境で止まりやすい構成です。

作業は次の順で進めます。

• リポジトリをクリーンな作業領域へ取得します。
• 共有xcconfigと環境別xcconfigの割り当てをXcodeで確認します。
• API KeyやTokenを、管理された環境変数または保護されたファイルから注入します。
• 非対話式のBuildを実行し、個人のキーチェーン選択や画面操作に依存しないことを確認します。
• 各Targetの最終Build SettingsとInfo.plist展開結果を保存します。
• Release Archiveを作成し、再起動後にも同じ手順で復元できるか確認します。

この流れでは、構築用パラメーター、アプリ実行時の設定、署名資産、アップロード資格情報を別々に扱います。API Keyをxcconfigへ書かないことと、アプリが実行時に必要とする公開設定を適切に埋め込むことは、同じ問題ではありません。

リモート Macを初めて用意する場合は、MacDateのMac環境案内で接続方式や利用形態を確認し、実際のArchive検収項目は別の手順書として固定してください。長期運用では、Mac miniのレンタル構成を比較するガイドも、常時稼働させるか一時的に借りるかを考える材料になります。

Release Archiveを基準に、誤設定を機械的に止めます

最終判断は、Xcode上のScheme名ではなく、生成されたArchiveの中身で行います。AppleのApp Archive作成手順とArchiveを検証する手順を参照し、提出前に次の項目を記録してください。

• 実際に使用されたConfiguration
• 本番用Bundle IDと各Extensionの識別子
• Info.plistに展開されたAPI環境
• EntitlementsとApp Group
• 必要なシンボル情報
• Archive検証の結果
• 検証用URLや開発用フラグが存在しないこと

検証用URL、DEBUG相当のフラグ、仮の表示名を検出したら、Archiveを提出不可にする仕組みを用意します。人がSchemeを選び直す運用より、禁止値を見つけたら失敗させる方が、リモート MacやCIでは再現性を保ちやすくなります。

判断に迷う場合は、次の分岐で進めます。

• 公開設定だけで新環境を復元できるなら、xcconfigの分割を維持します。
• 秘密値がリポジトリに必要になったなら、外部注入へ戻し、保管場所を見直します。
• 本番Schemeが複数の環境設定を継承しているなら、共有基盤を整理してからArchiveします。
• 主アプリだけ成功し、Extensionの値を確認していないなら、配布対象ごとの検収へ戻ります。
• クリーンチェックアウト後に手作業が残るなら、遠隔環境を本番運用へ進めず、復元手順を修正します。

手元のMacだけで続ける方法は、短期の開発や物理デバイスを直接接続する作業には向いています。ただし、常時オンラインにできない、ディスク容量やXcodeの状態を自分で維持する必要がある、別環境での再現確認が後回しになるという欠点があります。

そのため、今のMacを一台の作業端末として使い続けながら、クリーンチェックアウトとRelease Archiveを反復する用途では、MacDateのリモート Macを検証用・打ち合わせ用の環境として借りる選択肢があります。特に、ローカル設定に依存した構成を見直し、実際に新しい環境で復元できるかを確かめたい場合は、先に短期間の検収を行い、安定した長期負荷や物理デバイス接続が必要なら自前のMacを残す、という分け方が現実的です。