症状：Xcode 27 BetaでXCFrameworkのリンクやアーキテクチャエラーが出るなら、まず対象プラットフォームの変種、次に必要なアーキテクチャスライスを確認してください。 最短の切り分け：実際にリンクされたファイルとビルド環境まで照合し、不足があれば依存元に更新版を求めるか、対応する成果物を再構築します。Rosettaでの起動やバイナリの一括結合を、最初の回避策にしないでください。
SDKやバイナリ依存を配布する担当者、リモートMac CIだけで失敗するビルドを調査するエンジニア向けです。 ローカルとCIの差が依存パッケージ由来か、ビルド先や環境由来かを切り分けたいAppleプラットフォーム開発者にも役立ちます。
Xcode 27 BetaのXCFrameworkアーキテクチャエラーを故障箇所から切り分ける
最初に確認するのは、「どの段階で、どのターゲットが失敗したか」です。コンパイル時のモジュール読み込みエラー、リンク時のアーキテクチャ不一致、実行時のロード失敗では、調べる対象が異なります。失敗したターゲット名、完全なエラーログ、選択したビルド先を同じ記録に残してください。
エラーが出た段階は、どう見分けますか？
ログに Compile やモジュール読み込みの失敗があればコンパイル段階、Ld や linker、building for ... but linking in ... が含まれるならリンク段階を優先して調べます。実行後にライブラリを読み込めない場合は、ビルド時に使われた成果物と実行環境の組み合わせを確認します。
Xcode 27 Betaは正式安定版と決めつけず、調査対象のビルド環境として記録します。Appleのリリース情報では、2026年10月6日時点でXcode 27 Beta 6のリリースノートと、Xcodeのリリース一覧に掲載された他のバージョンを照合できます。実際の診断では、端末側とCI側のXcode選択も同じ記録に含めます。
プラットフォーム変種をビルド先と照合する
XCFrameworkは、CPUアーキテクチャ名だけで互換性を判断できません。iOS実機、iOS Simulator、macOS、Mac Catalystは別のプラットフォーム対象として扱い、パッケージにビルド先に合う変種があるかを確かめます。Appleの複数プラットフォーム向けバイナリframework作成ガイドに沿って、パッケージの構成と対象の組み合わせを確認してください。
iOS Simulatorと実機で、同じXCFrameworkのバイナリを共用できますか？ 同じCPUアーキテクチャを含むというだけでは判断できません。Simulator用と実機用のプラットフォーム変種が別々に用意されているかを確認し、現在のビルド先に対応するものがなければ、依存元の更新または再構築を検討します。Apple Silicon Simulatorで必要なスライスが不足している場合も、RosettaでXcodeを起動して解決したと判断するのではなく、依存パッケージ自体を調べます。
パッケージの宣言と実際のリンク先を照合する
対象の変種が存在していても、中に必要なアーキテクチャが含まれるとは限りません。XCFramework内の Info.plist で AvailableLibraries、LibraryIdentifier、LibraryPath、SupportedPlatform、SupportedPlatformVariant、SupportedArchitectures を調べ、選択対象を特定します。
ターミナルでは、たとえば plutil -p <XCFramework>/Info.plist で宣言を確認し、ログから実際に選択されたframeworkまたはlibraryのパスを追います。そのうえで、該当するバイナリに lipo -archs <binary> を実行し、宣言されたアーキテクチャと実体が一致するか照合します。宣言上は対応していても、参照先が旧成果物ならリンクは失敗します。
XCFrameworkが対象プラットフォームとアーキテクチャを含むか、どう確かめますか？
まずビルド先に合う SupportedPlatform と SupportedPlatformVariant を見つけ、続いてその項目の SupportedArchitectures と LibraryPath を確認します。最後に、該当パスの実バイナリを調べ、ビルドログに出たリンク先と同じファイルか照合してください。
frameworkと静的ライブラリでは、XCFrameworkに格納する対象や参照するパスが異なる場合があります。AppleのXCFramework作成手順を基準に、配布時の指定方法と実際のフォルダ構成を点検します。出所や配布物の正当性も確認する場合は、AppleのXCFrameworkの出所確認手順を参照してください。
arm64のようなアーキテクチャ名が一致しても、Simulator用と実機用の変種が一致するとは限りません。変種の選択、バイナリの実体、リンクログの順で照合してください。
リモートMac CIだけ失敗するときは依存解決を固定する
同じコミットが手元では通り、リモートMac CIで失敗するなら、すぐにノード固有の問題と断定しないでください。CIが別のXcodeを選択している、依存の解決結果が異なる、キャッシュに古いXCFrameworkが残っている、ビルド設定やビルド先が違う、といった条件を並べて比較します。
本機では成功するのに、リモートMac CIでリンクに失敗する場合は？ 同じコミット、同じビルド先、同じ依存解決結果になるよう固定し、Xcodeの選択、ビルド設定、依存元、取得した成果物の版を両環境で記録します。Xcodeの設定差はAppleのBuild Settingsリファレンスも参照し、ログや依存一覧は認証情報を除いて比較可能な形で保存します。
切り分けは次の順で進めます。
- 失敗したターゲット、ビルド先、完全なエラーと失敗段階を記録します。
- 同一コミットで、端末側とCI側のXcode選択およびビルド設定を比較します。
- 依存解決結果とキャッシュを固定し、取得したXCFrameworkの版と配置先を照合します。
Info.plistから対象変種を選び、そのバイナリの宣言と実際のアーキテクチャを確かめます。- ログに出たリンク対象のパスを特定し、古い成果物や別の依存元を参照していないか確認します。
- 依存元に不足がある場合は、対応版の提供、ソースからの再構築、アップグレードの保留を選びます。
- 修正後、プロジェクトで実際にサポートする実機とSimulatorのビルド先をそれぞれ検証し、ログと依存版を回帰確認用に保存します。
診断結果から次の対応を選ぶ
次の表は、症状から優先して確認する箇所を選ぶための運用上の目安です。評価は診断の優先度であり、特定の依存パッケージが対応済みであることを示すものではありません。
| 観測した症状 | 優先して確認する箇所 | 優先度 | 次の対応 |
|---|---|---|---|
| 対象プラットフォームの変種が見つからない | SupportedPlatform と SupportedPlatformVariant | 高 | 依存元に対象変種の提供を確認します |
| 変種はあるが必要なアーキテクチャがない | SupportedArchitectures と実バイナリ | 高 | 対応成果物を取得するか再構築します |
| 宣言と実際のバイナリが食い違う | LibraryPath、実ファイル、取得元 | 高 | 古い成果物や誤った参照先を除外します |
| ローカルとCIで選ばれるファイルが異なる | Xcode選択、依存解決、キャッシュ、ビルド設定 | 中 | 条件を固定し、両環境のログを比較します |
| 失敗段階や選択ターゲットが特定できていない | 完全なログとビルド先 | 高 | 原因の推測を止め、再現条件を記録します |
| 判定 | 確認できたこと | 選ぶ対応 |
|---|---|---|
| 対応変種と必要なスライスがあり、実際のリンク先も一致 | ローカルとCIで依存版・ビルド先を揃えて再現できる | 実機とSimulatorの対象ビルドを通し、ログを基準として保存します |
| 対象変種またはスライスが依存にない | ログとパッケージ内容で不足を確認できる | 供給元の更新を待つか、ソースから再構築します |
| ローカルとCIの依存版や設定が異なる | 同一条件に固定すると結果が変わる | 差分を修正し、固定条件で両環境を再実行します |
| 端末、ネットワーク、または実行中のMacが手元で再現できない | 必要な検証対象や運用条件がローカルにない | リモートMac環境を含む検証方法を比較します |