Xcodeのビルド失敗をどう調べる？Macビルドマシンガイド 2026

Xcodeのビルド失敗は、まずログと結果バンドルでエラーの発生段階を特定し、プロジェクト設定、依存関係、ツールチェーン、Macビルドマシンの順に切り分けてください。すぐにXcodeを再インストールしたり、Macを交換したりするのではなく、同じコミットを隔離した環境で再現できるかを確かめてから、原因に応じて対応します。

今週は、失敗したコミット、実行したビルドコマンド、使用したXcode、エラー箇所をひとまとまりで記録し、単発の失敗と繰り返す障害を分けるところから始めましょう。

この手順は、iOS／macOS CIを運用するプラットフォームエンジニア向けです。
チームのMacビルドマシンを管理するIT担当者は、ノード障害とプロジェクトの問題を切り分けられます。
技術責任者は、ログの保存方法と障害の引き継ぎ先をチームでそろえる際に役立ててください。

失敗した範囲をログから固定する

最初に、失敗が同じコミット、同じワークフロー、同じビルドノードで起きているかを確認します。ビルドのどの段階で止まったかも記録してください。依存関係の取得前後、コンパイル、署名、テストでは、確認すべき設定や担当者が異なります。

CIのビルドログでは、どこから確認すればよいですか？

エラー表示の最後の行だけで判断せず、その前後にある最初の失敗メッセージと、直前に実行された処理を確認します。ログの入口は、CIのジョブ出力とXcodeのレポートを分けて探してください。ジョブが起動する前に止まった場合は、コンパイラのエラーがなくてもノードやワークフロー側の手掛かりがあります。

一回だけの失敗なら、直近の環境変更や外部依存先の一時的な状態も調査対象です。同じコミットで同じ段階の失敗が再現するなら、単なる一過性として処理せず、後続の切り分けに進みます。失敗したジョブの実行記録は、後で再現条件をそろえるために残してください。

プロジェクト設定と依存関係を照合する

ローカルでは通るのにCIで失敗する場合、ローカルの操作とCIが実行した内容が同じとは限りません。scheme、target、ビルド構成、destination、署名条件を、成功時のコマンドや設定と比較します。Appleの一般的な設定・ビルド問題の確認方法も参考にし、ログに出たエラーに対応する設定を確認してください。

失敗がプロジェクト設定に由来するのか、Macビルドマシンに由来するのかはどう見分けますか？

同じコミットと同じビルド条件を使い、別の隔離環境でも同じエラーが再現するかを確認します。再現するなら、schemeや設定、コード、依存関係などプロジェクト側を優先して調べます。特定の再利用ノードだけで起きるなら、そのノード固有の環境状態も候補に含めます。ただし、どちらも手掛かりであり、これだけで原因を断定はできません。

依存関係の取得中に止まった場合は、ロックファイルが期待した状態か、プライベートリポジトリの認証情報がジョブから利用できるか、ビルドノードから必要な接続先へ到達できるかを別々に確認します。ネットワークへの接続エラーを、すぐにXcodeやMac本体の故障と決めつけないでください。

たとえば、同じノードで前のジョブが成功し、後続のジョブで依存関係の取得に失敗した場合、資格情報の利用範囲や接続条件の変化も調査候補になります。これは原因を確定する事例ではありません。ログ上の失敗段階を手掛かりに、関連する設定と環境を一つずつ確認するための見立てです。

Xcodeとコマンドライン環境を確認する

CIのコマンドが実際にどのXcodeを選んでいるか、まずノード上で確認します。xcode-select -pで選択中の開発者ディレクトリを、xcodebuild -versionで呼び出されるXcodeの情報を確認し、記録したビルド環境と照合してください。

Appleのコマンドラインツールのリファレンスには、xcodebuildやxcresulttoolなどのツールが掲載されています。ここで確認したいのは、ツールの有無だけではありません。CIが意図した開発者ディレクトリを使っているか、必要なXcodeとコマンドライン環境がそろっているかを分けて判断します。インストール状態の確認には、コマンドラインツールのインストール説明も参照できます。

コマンドが動くかどうかだけで、プロジェクトの問題とツールチェーンの問題を決めないでください。ログに示されたエラーと、選択されたXcode、ビルドコマンドを組み合わせて判断します。

ビルドノードの状態と環境残留を分ける

ジョブが止まったときは、コンパイルのエラーとノード自体の状態を別に見ます。自動化基盤を利用している場合は、ノードのオンライン状態とアプリケーション・ジョブのログを確認してください。たとえばセルフホステッドランナーの監視とトラブルシューティングでは、状態やログを使った確認方法が案内されています。

オフライン表示やジョブの中断は、ビルド処理がエラーを出して終了した状態とは異なります。ノードの接続、ジョブの実行記録、ビルドログの順に確認し、どの段階で止まったのかを残してください。

再利用しているノードだけで断続的に失敗するなら、一時的に隔離して同じコミットを再実行し、実行条件をそろえます。前のジョブから残ったキャッシュや設定が影響している可能性は調査対象ですが、再現記録なしに環境残留を原因と断定するのは避けます。偶発的な失敗だけを根拠に、ハードウェア性能不足と判断する必要もありません。Macビルド環境の監視や運用設計を見直す場合は、VpsKeepのMac関連ガイドも参考になります。

ログにコンパイルエラーが見当たらない場合は、ビルド処理が始まる前にジョブが止まっていないかを確かめてください。ノードの状態とビルドの失敗を同じ問題として扱うと、担当者の切り分けが遠回りになります。

xcresultと再現記録を保全する

テストやビルドが終わった後は、ジョブのログだけでなくXcodeの結果バンドルも保存します。xcresultには処理やテストの結果を調べる手掛かりが残り、xcresulttoolで内容を確認できます。Appleのテスト実行と結果の読み取り方法を参照し、失敗したテストや診断情報を調べてください。

xcresultから、テストやコンパイルの失敗箇所をどう確認しますか？

結果バンドルを開き、失敗したアクションやテスト、関連する診断情報をログと照合します。テスト結果に出た失敗とビルドログのエラーが対応しているかを見て、必要に応じてxcresulttoolを使って結果を確認してください。結果バンドルだけで原因が確定するとは限らないため、コミットや実行コマンドも一緒に保管します。

次の項目を、ジョブ単位で残しておくと再現と引き継ぎがしやすくなります。

• [ ] 失敗したコミットとワークフローを記録する
• [ ] 実行したビルドコマンド、scheme、targetを保存する
• [ ] 選択中のXcodeと開発者ディレクトリを記録する
• [ ] エラーが発生した段階とログ上の該当箇所を特定する
• [ ] CIのジョブログとxcresultを保管する
• [ ] 同じ条件を隔離環境で再実行し、再現の有無を記録する
• [ ] 証拠に応じてプロジェクト、CI基盤、ツールチェーンの担当者へ引き継ぐ

Macビルドマシンで時折だけ失敗するときは、どう再現条件を残せばよいですか？

まず失敗した実行と成功した実行を同じ記録形式で比較します。コミット、実行コマンド、ツールチェーンの選択、エラー段階、ノードの状態、結果バンドルをそろえ、隔離環境でも再現したかを付記してください。条件がそろわないまま「Macの故障」と結論づけるのではなく、追加調査に必要な証拠が何かを明確にして引き継ぎます。

症状に応じて復旧方法を選ぶ

プロジェクト設定の不一致や依存関係の取得失敗なら、該当する設定、資格情報、接続先を確認します。Xcodeの選択違いなら、CIが使う開発者ディレクトリとツールを修正します。ノードの停止や再利用環境の疑いが残る場合は、ノードを隔離して再現条件を確かめてください。

同じコミットを隔離した環境でも同じエラーが再現したら、プロジェクトまたはツールチェーンの問題として担当者へ渡し、ログと結果バンドルを添えて調査を依頼します。再現しない場合は、ノード状態や依存先など、実行時の差分を引き続き確認します。Appleの一般的なビルド問題の案内は、Xcode側で調べる項目の確認にも使えます。

ビルド環境が共有ノード一台に依存していると、環境の維持やジョブ間の影響を管理する負担が残ります。一方で、遠隔のMacを利用しても、プロジェクトの誤設定や依存先の障害が自動的に解消するわけではありません。物理インターフェースが必要な作業や、長期間にわたり高負荷で専有する運用なら、自社でMacを保有する方法も比較してください。

プロジェクトとツールチェーンの問題を切り分けた後、独立した遠隔Mac環境でCIを再現したい場合は、VpsKeepのMacレンタル案内を確認できます。購入したMacの調達・保守や遊休コストを避けながら、必要な期間の検証環境を用意したいチームには、レンタルが検討候補になります。利用条件や運用上の要件を先に照合し、自社での保有が適するケースと分けて選んでください。