Swift 6.4への更新後、安定版ツールチェーンでは通るのに遠隔Mac CIだけでduplicate module nameが出ているなら、まずノードの再構築や全キャッシュ削除を始めないでください。最短の対処は、同じ依存関係のスキャンで見えているmodule.modulemapと検索パスを特定し、重複宣言の除去、依存ライブラリの更新、独自モジュール名の変更を順に判断することです。
最初の判断：Swift 6.4の新しい依存関係スキャンでは、同じスキャンから到達できるClang module名の一意性が問題になります。修正できない第三者SDKが原因なら、安定版CIを本番に残し、Swift 6.4は隔離した検証ノードで並行確認します。
SECTION 01 この記事を読むべき人
Objective-C、C/C++、バイナリSDKを含むSwiftプロジェクトを管理し、更新後に初めてモジュール重複エラーを見たアプリ開発者向けです。遠隔Macのビルドノード、依存キャッシュ、Xcodeツールチェーンの切り替えを担当するDevOps・ビルドエンジニアにも適しています。
また、Swift 6.4への移行をすぐ本番へ進めるか、依存修正まで保留するかを決める開発基盤の責任者にも、証拠を残した判断手順として使えます。
SECTION 02 まずログの種類とアップグレード時点を固定する
最初に、ビルドログの先頭にある有効な診断を保存します。終了コードだけでは、モジュール重複、宣言の再定義、モジュール未検出、リンク段階の失敗を区別できません。
| ログの特徴 | 主な故障領域 | 最初に確認する対象 |
|---|---|---|
duplicate module name |
同名Clang moduleの到達経路が複数 | module.modulemap、ヘッダー検索パス |
redefinition |
型・マクロ・宣言の重複 | Bridging Header、公開ヘッダー |
module not found |
モジュールの探索失敗 | SDK選択、検索パス、依存解決 |
リンク段階のundefined symbols |
オブジェクトやライブラリの結合 | Link Binary、アーキテクチャ、ライブラリ |
AppleのXcode 27リリースノートでは、Swiftの依存関係スキャナーについて、同じスキャンで到達するClang module名を一意に扱う要件が確認されています。ただし、これはベータ版の挙動を将来の正式版すべてに断定する根拠ではありません。Xcode 27 beta 6とSwift 6.4の組み合わせで出た具体的なエラーは、必ず自分のログで確認してください。
| 固定する証拠 | 安定版ノード | Swift 6.4ノード |
|---|---|---|
| XcodeとSwiftの選択結果 | 実行時の出力を保存 | 実行時の出力を保存 |
| 完全なビルドコマンド | 同じコミットで取得 | 同じコミットで取得 |
| 依存ロック | Package.resolvedなど |
同一ファイル |
| ビルド引数 | 環境変数を含めて保存 | 環境変数を含めて保存 |
| 作業ディレクトリ | クリーンな場所を指定 | 別のクリーンな場所を指定 |
AppleのXcodeシステム要件で対象XcodeとOSの組み合わせを確認し、ツールチェーンの違いと依存関係の違いを混ぜないようにします。
SECTION 03 Swift 6.4 duplicate module nameを出所別に分ける
自作モジュールとプロジェクト設定の重複
リポジトリ内のmodule.modulemapを検索し、モジュール名、ヘッダーの入口、実際に読み込まれるディレクトリを記録します。自作のClang moduleを作っている場合、同じ名前を持つ宣言を複製していないか確認してください。
Bridging Header、Header Search Paths、User Header Search Paths、明示的なコンパイラ引数も同時に見ます。宣言が一つでも、検索パスが別のコピーを先に見せていれば、遠隔Mac CIだけで衝突することがあります。モジュールマップの構文やシステムライブラリの扱いは、Swift Package Managerのmodule map資料と照合します。
修正の優先順位は、重複宣言の統合、独自モジュール名の変更、不要な検索パスの削除です。ランナー上の適当なディレクトリを消すだけの対応は、次の環境で再発するため採用しません。
第三者SDK、XCFramework、システムモジュールの重複
次に、vendored source、XCFramework、Swift Package、手動導入したSDKを依存関係の枝ごとに確認します。
| 重複の組み合わせ | 判断 | 推奨対応 |
|---|---|---|
| 二つの第三者コンポーネントが同じ名前を使用 | 依存同士の衝突 | 互換版を探し、片方を隔離して検証 |
| SDKがシステムモジュール名を再宣言 | システムとの衝突 | SDK提供元の修正版を優先 |
| 同じSDKのコピーが複数の検索パスに存在 | CI固有の探索衝突 | 探索順を固定し、不要なコピーを除外 |
Clangのモジュール探索とキャッシュの関係は、Clang公式Modules資料で確認できます。変更できないバイナリSDKに対して、CIの本番ブランチへ恒久的なパッチを直接入れるのは避けてください。隔離ブランチで修正を検証し、上流の互換更新、署名や配布物の再取得、ロールバック方法を残します。
旧版ツールチェーンでは通るのに、Swift 6.4でだけ失敗するのはなぜですか。
旧版が重複を検出しなかった、またはCIの探索順によって片方だけを読み込んでいた可能性があります。Swift 6.4側のスキャナーが同名モジュールを同じスキャン範囲で認識したとき、従来は表面化しなかった依存構造がエラーとして現れることがあります。これは一般論として断定せず、両方のログで読み込み経路を比較してください。
SECTION 04 遠隔Mac CIでは検索パスとキャッシュを別々に検証する
ローカルで再現しない場合は、遠隔Macの差分を一覧化します。Homebrewの導入先、SDKの選択、Shell初期化、環境変数、作業ディレクトリ、Package.resolved、ビルドスクリプトの引数を、成功ノードと失敗ノードで比較します。
Xcodeのビルド設定は、Appleのビルド設定ガイドを基準にし、設定名だけでなく最終的に展開された値をログへ残します。module.modulemapというファイル名だけを全ディスクから削除するのではなく、コンパイラのモジュール読み込み診断で実際の出所を絞り込みます。SwiftとClangの診断資料はSwift公式ドキュメントも参照してください。
二つの同名module.modulemapを、どの依存から読み込んだか調べるにはどうしますか。
まずリポジトリ、依存解決先、XCFrameworkの内部を検索し、候補ごとに絶対パスを記録します。次に、同一コミットと同一ビルド引数でモジュール読み込み診断を有効にし、ログに現れた実パスと検索パスを照合します。候補ファイルの数だけで結論を出さず、実際にスキャンへ到達した二つを特定することが重要です。
キャッシュ検証は、通常の作業領域を壊す前に、新しい作業ディレクトリと独立したキャッシュパスで行います。Module Cache、DerivedData、依存キャッシュを個別に分け、どの削除で挙動が変わったかを記録します。
DerivedDataを消せばSwiftのモジュール重複エラーは直りますか。
一時的な古い状態が残っている場合は変化する可能性がありますが、二つのモジュール宣言そのものは消えません。したがって、DerivedDataの削除は原因特定の後に行い、削除対象を限定して、並行ジョブへの影響と復元方法を明記します。修正後はクリーンビルドだけでなく、増分ビルドも実行し、キャッシュがエラーを隠していないことを確認します。
運用上の注意：共有ランナーのキャッシュを全消去すると、他のジョブの再現性や実行時間にも影響します。まず専用キャッシュ名へ切り替え、問題のジョブだけを再実行してください。
SECTION 05 修正・保留・二重運用を決める条件
次の条件分岐で、直ちに全ノードを更新するかを判断します。
- モジュールの出所が一つに整理され、クリーンビルドと増分ビルドが成功し、同じ条件で再実行しても結果が一致する場合は、Swift 6.4ノードを段階的に拡大します。
- 自作モジュールの重複が原因で、名前変更または宣言統合をレビューできる場合は、依存修正を先にマージし、安定版ノードで回帰確認してから新ツールチェーンへ進めます。
- 第三者SDKのバイナリを変更できず、上流の修正版も確認できない場合は、本番CIを安定版に戻し、Swift 6.4を互換性検証専用に残します。
- ログがリンクエラーや単純なモジュール未検出を示す場合は、duplicate moduleの修正手順を適用せず、該当する検索パスやライブラリ設定を別に調べます。
同一コミット、同一ロックファイル、同一ビルド引数で安定版とSwift 6.4を比較し、冷たい状態とキャッシュ済み状態の両方を記録します。第三者依存が原因なら、無理に本番へ入れるより、隔離ノードで上流修正を待つ方が、リリース工程の再現性を守れます。
実施タイムライン
| 時点 | 実施内容 | 合格条件 |
|---|---|---|
| 今すぐ | 最初の診断、ツールチェーン、依存ロックを保存 | 失敗境界が記録されている |
| 次の調査 | module.modulemapと実検索パスを照合 |
重複元を二つまで絞れている |
| 修正後 | 独立キャッシュでクリーン・増分ビルド | 両方で同じ成功結果になる |
| 放量前 | 安定版とSwift 6.4を同一条件で比較 | 差分の理由を説明できる |
| 依存修正待ち | 本番を安定版、検証をSwift 6.4へ分離 | 回退手順が実行可能 |
SECTION 06 遠隔Macを二つのツールチェーンで使う判断
手元のMacだけで環境を分けると、SDK、アカウント、キャッシュ、バックグラウンドジョブが混ざりやすくなります。遠隔Mac CIを使う場合でも、ツールチェーンの切り替え、キャッシュの分離、ログの保存先、再起動後の復旧を受け入れ条件として定義してください。
VPSNIXの遠隔Macサービスの案内を確認する際も、単に接続できるかではなく、あなたのプロジェクトで安定版とSwift 6.4を別ノードまたは別作業領域へ分けられるかを確認するのが先です。料金や利用条件を比較する場合は、プラン情報と、実際に必要な稼働期間、キャッシュ容量、管理方法を照合してください。
手元のWindowsやLinux環境だけで継続する方法は、Apple SDK、Xcode、署名、Clang moduleの再現性を保ちにくく、仮想化環境ではハードウェアやOSの制約も増えます。Mac miniの購入は長期にわたり同じ構成を占有し、故障交換、設置、夜間運用の管理も必要です。安定した本番線を残しながら、Swift 6.4用の検証環境を短期間で用意するなら、VPSNIXのMacレンタルで隔離ノードを作る方が、原因を切り分けた後に不要な機材を抱えずに済みます。
最終的な判断は、module mapの出所が説明できるか、依存SDKを管理できるか、二つのビルド経路を再現できるかで決めてください。まずはヘルプセンターで接続と運用条件を確認し、現在のCI構成に合う検証方法を選ぶのが安全です。
最終更新：2026年9月8日。Xcode 27リリースノート、Xcodeシステム要件、SwiftおよびClangの公式資料を再確認。Xcode 27のRCまたは正式版、Swift 6.4正式版、または主要SDKの互換修正版が公開された時点で再検証します。