SwiftPMのSwiftBuild移行でWindows CIが落ちる原因と直し方：platform 'windows' が見つからないエラーを潰す実践ガイド

SwiftPMで新しいビルドシステム「SwiftBuild」を既定にしようとすると、WindowsのCIだけが突然コケる――その典型例が「読み込まれたplatform一覧にwindowsが存在しない」という系統のエラーです。この記事では、ログに出ているメッセージを手がかりに、何が起きているのか・どこを点検すべきか・直すための現実的な手順を、ノイズを取り除いて整理します。

• SwiftPMのSwiftBuild移行でWindows CIが落ちる原因と直し方：platform 'windows' が見つからないエラーを潰す実践ガイド
  • 何が起きているか：エラー文を日本語に翻訳して状況整理
  • よくある原因パターン（優先度順）
    • 1) SwiftBuildのplatformレジストリがWindowsを含んでいない（または無効化されている）
    • 2) “Windowsでビルドしている”つもりでも、SwiftBuildに渡っているplatform指定が空（nil）になっている
    • 3) Windows SDK/ツールチェーン検出が不完全で“platform確定”まで到達していない
  • まずやるべき切り分け（最短で原因を絞る）
    • A. 同じcheckout・同じCI環境で「native build」は成功するか
    • B. SwiftBuildで“platform一覧”がどう決まっているかを見る
    • C. host/target triple が想定通りか確認する
  • 修正アプローチ：現実的に効く順に試す
    • 1) SwiftBuild関連の依存とバージョンを固定し、Windows対応のある組み合わせに寄せる
    • 2) Windows CIでSwiftBuildへplatformを明示的に伝える（nil回避）
    • 3) DocC系ターゲットを「Windowsではビルドしない」扱いにする（暫定回避）
    • 4) SwiftBuildを既定化するPRに「Windowsだけnativeを維持」するガードを入れる（段階的移行）
  • 追加で見ると効くログ観点
  • まとめ：このタイプのWindows失敗は“環境”ではなく“platform定義の断絶”を疑う

何が起きているか：エラー文を日本語に翻訳して状況整理

今回のログの核心はこの2つです。

• Could not find a platform named 'windows' from loaded platforms ...

• Could not choose a single platform for target ... from the supported platforms ...

つまり、

1. SwiftBuild側が「platformとしてのWindows」をロードできていない

2. その結果、依存解決やターゲットの特殊化（workspace specialization）が「どのplatformでビルドするか」を確定できず、DocC関連ターゲット（docc-product / DocCCommonなど）の評価段階で止まっている

という流れです。

ここで重要なのは、**「Windowsマシン上で走っているのに、SwiftBuildが“windows”というplatform定義を持っていない」**というギャップが根本原因になっている点です。SwiftPMの従来ビルド（native）では動いていたのにSwiftBuildで落ちる場合、ほぼこの“platform定義の解釈差”に集約されます。

よくある原因パターン（優先度順）

1) SwiftBuildのplatformレジストリがWindowsを含んでいない（または無効化されている）

ログに出ているロード済みplatformが android freebsd linux none openbsd qnx webassembly だけ、という時点で、SwiftBuildが参照しているplatform一覧が「Windows対応版」になっていません。

• SwiftBuild統合が有効でも、**使われているSwiftBuild本体や周辺コンポーネントが“Windows platformを公開していない版”**だと、この状態になります。

• CIのtoolchain更新や依存解決の結果、SwiftBuild関連が意図せず別の実装や設定に切り替わっているケースもあります。

2) “Windowsでビルドしている”つもりでも、SwiftBuildに渡っているplatform指定が空（nil）になっている

ログに Specialization parameters ... platform 'nil' が出ています。これは「Windowsを指定したいのに、SwiftBuildへplatformが伝搬していない」兆候です。

• workspace側の指定が抜けている

• 実行環境の検出（host triple / SDK検出）が失敗してplatform確定できない

• あるいはターゲット選択の流れで、platform選択ロジックが期待通り動かない

などで起こります。

3) Windows SDK/ツールチェーン検出が不完全で“platform確定”まで到達していない

Windowsは、MSVC・Windows SDK・環境変数・PATHなど、検出要素が多いです。SwiftPM nativeは耐性があっても、SwiftBuild統合側は前提が違うことがあります。

• “ビルドは開始できるがplatform確定ができない”という形で表面化しやすいです。

まずやるべき切り分け（最短で原因を絞る）

A. 同じcheckout・同じCI環境で「native build」は成功するか

SwiftBuildを既定にした変更が原因か、Windows側の環境変化が原因かを分離します。

• nativeで通る → SwiftBuild統合／platform解釈が原因の可能性が高い

• nativeでも落ちる → Windows SDKやtoolchain、依存側の変更も疑う

B. SwiftBuildで“platform一覧”がどう決まっているかを見る

ログに「loaded platforms」が出ているので、ここが最大の手がかりです。

• 期待：windows が含まれる

• 現状：含まれない

この差分を埋める作業が修正の本体になります。

C. host/target triple が想定通りか確認する

Windows CIでありがちなのが、ビルドのホスト判定がどこかでズレることです。

• x86_64-unknown-windows-msvc で動いているはずなのに、SwiftBuild側のhost検出が別の値になっていると、platform確定が崩れます。

修正アプローチ：現実的に効く順に試す

1) SwiftBuild関連の依存とバージョンを固定し、Windows対応のある組み合わせに寄せる

“platform一覧にwindowsが無い”のは、多くの場合「Windowsを提供しないSwiftBuild実体を掴んでいる」状態です。

• SwiftPM側でSwiftBuild統合を既定化するPRを作っているなら、CIで使うSwiftBuild（および関連ライブラリ）が、Windows platformを公開する前提で揃っているかを確認します。

• “キャッシュから引かれている”ログがあるため、キャッシュに残った古い成果物が混ざっている可能性もあります。Windows CIだけキャッシュ戦略が違うと、片側だけ古い構成で動きます。

実務的には、Windowsだけ一時的に

• SwiftBuild実行コンポーネントの取得元やrevisionを明示

• CIキャッシュを無効化／キー変更
  をして、確実に同一世代の部品で揃うか見ます。

2) Windows CIでSwiftBuildへplatformを明示的に伝える（nil回避）

ログが platform 'nil' を示している以上、少なくとも「自動検出に失敗している」可能性があります。

• SwiftPMがSwiftBuildへ渡すworkspace/targetの特殊化パラメータに、Windowsが入るようにする

• あるいは、CIジョブ側でtarget tripleやSDK検出に必要な環境変数が欠けていないかを点検する

ポイントは、SwiftBuildが“windows platformをロードできる状態”＋“選択できる状態”の両方が必要ということです。片方だけ整えても、エラーは形を変えて残ります。

3) DocC系ターゲットを「Windowsではビルドしない」扱いにする（暫定回避）

ログで落ちているのは swift-docc をビルドして DocC を生成する流れです。WindowsでDocCを“生成物として必要としない”のであれば、暫定的に逃がせます。

• CIの対象をWindowsでは外す

• 生成物のビルド条件を分ける

• “WindowsではDocCをビルドしない”選択になるようにパッケージ構成を調整する

ただしこれは根治ではありません。SwiftBuild既定化の目的が「全platformで同じビルド体験」なら、最終的には(1)(2)の解決が必要です。

4) SwiftBuildを既定化するPRに「Windowsだけnativeを維持」するガードを入れる（段階的移行）

SwiftBuildは機能差が残ることがあり、既定化のタイミングでWindowsだけ破綻するのは珍しくありません。既定化PRの価値を落とさずに前進させるなら、

• Windows CIでは従来ビルドを使う

• 他platformでSwiftBuildを既定化する

• Windows対応が揃った時点で切り替える

という段階移行が最も事故が少ないです。特に、CIが「常に緑であること」が優先のプロジェクトでは、この設計が現実解になります。

追加で見ると効くログ観点

• loaded platforms の一覧がどこで決まったか（SwiftBuildサービス起動時・設定読み込み時）

• workspace specialization parameters が platform nil になっている起点（workspace生成、コマンド引数、環境検出）

• docc-product が要求する supportedPlatforms が空に見える理由（ターゲット定義側か、解釈側か）

ここが追えると、修正は「Windows platform定義がロードされるようにする」か「platform確定パラメータの伝搬を直す」か、どちらに手を入れるべきかが決まります。

まとめ：このタイプのWindows失敗は“環境”ではなく“platform定義の断絶”を疑う

今回のログは、単なるコンパイルエラーではなく「SwiftBuildがWindowsというplatformを認識できていない」ことが直接の原因です。なので対処も、MSVCやSDKの再インストールより先に、

• SwiftBuild側でWindows platformがロードされる構成になっているか

• platform選択パラメータがnilになっていないか

• キャッシュや依存の世代ズレで、Windowsだけ別のSwiftBuildを掴んでいないか

を順に潰すのが最短ルートです。

SwiftBuild既定化は、成功すればクロスプラットフォームのビルド体験を一段揃えられる一方、移行期は「platform解釈の差」が露骨に出ます。今回のエラーはまさにそのサインなので、上の切り分け手順で原因を一点に絞り、Windowsでもloaded platformsにwindowsが載る状態を作るのがゴールになります。