SwiftUI Preview が起動しない、更新を繰り返す、Canvasだけが失敗するといった症状を、プロジェクトの種類と利用環境ごとに切り分ける記事です。診断レポートの取得、依存関係の確認、権限の検証、復旧後の受け入れ確認まで、不要な全削除や再インストールを避ける手順を説明します。
SwiftUI Preview が起動しない、更新を繰り返す、Canvasだけが失敗するといった症状を、プロジェクトの種類と利用環境ごとに切り分ける記事です。診断レポートの取得、依存関係の確認、権限の検証、復旧後の受け入れ確認まで、不要な全削除や再インストールを避ける手順を説明します。
AppleのXcode 14リリースノートには、Previewの診断レポートを取得する導線が記載されています。つまり、SwiftUI Preview が動かないときは、最初に全キャッシュを削除したりXcodeを再インストールしたりせず、診断レポートで原因を分類するのが最短です。
症状：Canvasが起動しない、更新を繰り返す、プレビューだけ失敗する。
最速の対処：診断レポートを保存し、コード、依存関係、Simulator、システム環境の順に切り分けます。
このガイドは、SwiftUIで画面を反復開発している独立開発者、Simulatorではアプリが動くのにPreviewだけ失敗する開発者、VNCやリモートデスクトップ経由でMacを使う小規模チーム向けです。単発の再起動ではなく、長期運用する開発環境を再現可能な状態に戻したい場合に適しています。
Previewのビルド、通常のBuild、Simulatorでの実行は、同じプロジェクトを使っていても確認する経路が異なります。AppleのSwiftUI Previewの動作説明を基準に、Canvasの診断メニューからPreviews Diagnosticsを生成し、エラー発生時刻、対象ファイル、Scheme、実行先、選択したプラットフォームを記録します。
作業前に、次の情報を1つのメモへ残します。
ここで重要なのは、Canvasの末尾に出た大量のエラーではなく、最初の読み込み、リンク、コンパイルエラーを証拠の入口にすることです。Previewの診断に関するApple Developer Forumsの個別議論も参考になりますが、フォーラムの権限エラーや特定バージョンの報告は、すべての環境に共通する仕様とは扱いません。
新規プロジェクトに単純なTextまたは短い静的Viewを置き、同じMacでPreviewを試します。新規プロジェクトだけ成功するなら、まず元プロジェクトのコード、依存関係、リソースを疑います。新規プロジェクトも失敗するなら、SimulatorのRuntime、グラフィカルセッション、ディレクトリ権限、Xcode環境の確認へ進みます。
Cannot preview in this file の切り分けCannot preview in this file が表示された場合、最初にそのSwiftファイルが現在のTargetに含まれているか確認します。Previewマクロが有効な構文になっているか、対象プラットフォームがSchemeと一致しているかも確認します。
本体アプリが起動することだけでは、Previewが正常とは判断できません。Previewでは、Viewの生成時に実行される初期化処理やサンプルデータの作成が、通常起動時と異なる条件で失敗する場合があります。
まず画面を次のように縮小します。
最初に失敗した依存関係が分かれば、Canvas全体の問題ではなく、Preview用データまたは初期化処理の問題です。実際のAPI、ログイン状態、端末固有の保存データを読み込むPreviewは、再現性が低く、チームで共有する診断材料にもなりません。
データ駆動型の画面では、Preview専用のインメモリデータ、固定されたサンプル、差し替え可能なサービスを用意します。プロダクション用データベースへ直接接続したり、ログイン済みのシングルトンを前提にしたりすると、オブジェクト生成失敗、空データ、View描画失敗を区別できなくなります。
確認は一度に全部行わず、次の順で分けます。
SwiftDataの特定バージョンに関する挙動は、Appleの公式文書や該当するXcode 26リリースノートで確認します。開発者フォーラムの個別報告だけを根拠に、OSやXcode全体の不具合と断定するのは避けてください。
Runtime Linking Failure の確認順Runtime Linking Failure が出る場合、依存パッケージの解決成功、通常のコンパイル成功、Preview実行時のリンク成功を別々に確認します。Packageが解決できていても、Previewが使うTargetへ製品が接続されているとは限りません。
確認対象は次のとおりです。
Target作成時の構成はAppleのTarget設定ガイドで確認し、Build PhasesのリンクやリソースはBuild Phasesの公式説明と照合します。ログに複数の失敗が並んでも、最初のリンクまたはロードエラーを起点にします。
Package.resolvedを理由なく削除するのは得策ではありません。依存バージョンの固定状態を失うため、問題の再現条件が変わり、修正前後の比較が難しくなります。削除する場合は、リポジトリの変更を保存し、復元可能な状態を確認してから、依存解決の問題であることを示す証拠がある場合に限定します。
| 症状 | 先に見る場所 | 次の判断 |
|---|---|---|
| 静的なViewだけ失敗 | Target、Previewマクロ、Scheme | 最小Viewが成功するまでコードを縮小 |
| データ利用Viewだけ失敗 | Model、コンテナ、外部サービス | 固定データとインメモリ構成へ切り替え |
Runtime Linking Failure |
Package製品、Framework、Build Phases | 最初のリンクエラーを修正 |
| Simulatorも起動しない | Runtime、実行先、グラフィカルセッション | Previewではなく実行環境を復旧 |
| 新規プロジェクトも失敗 | 権限、DerivedData、Xcode環境 | 局所清掃後も再現するなら環境移行を検討 |
リモートMacでは、Xcodeが起動しているだけでなく、現在のユーザーに有効なグラフィカルログインセッションが必要です。VNC接続が切れた後にCanvasだけが更新を続ける場合は、Xcodeの再起動より先に、GUIセッション、画面ロック、Simulatorの起動状態を確認します。
プロジェクトディレクトリ、DerivedData、Simulatorデータ、テンポラリディレクトリについて、所有者と書き込み権限を確認します。保護されたディレクトリに置いた最小プロジェクトと、ユーザーが通常管理できる開発用ディレクトリに置いた同一プロジェクトを比較すると、ファイルアクセス制限を切り分けやすくなります。
注意：完全ディスクアクセスの付与は万能の解決策ではありません。必要な範囲、組織のセキュリティ方針、対象ディレクトリを確認し、まず開発用ディレクトリへの移動や所有権の修正で再現性を確かめます。
Simulatorの実行先に必要なRuntimeがインストールされ、単独で起動できることも確認します。AppleのXcodeでSimulatorまたは実機へアプリを実行する説明で実行先の条件を確認し、Simulator自体が起動しない状態をPreview固有の障害と混同しないようにします。
VNCMacのリモートMac環境の選び方を検討する場合も、価格だけでなく、GUIセッションを再初期化できるか、開発ディレクトリの権限を管理できるか、必要なRuntimeを維持できるかを確認します。iOS SimulatorをブラウザやVNC経由で扱う構成では、Simulatorのリモートアクセスと画面セッションの確認方法も、Previewとは別の接続経路として整理しておくと診断が安定します。
DerivedDataの削除でSwiftUI Previewが直る場合はありますが、常に有効な手段ではありません。古いビルド成果物やインデックスが壊れている可能性を確認するための局所的な対処であり、コード、Packageリンク、Simulator Runtime、権限の問題は残ります。
実施前に診断レポートとツールチェーン情報を保存し、対象プロジェクトのDerivedDataだけを特定します。全プロジェクトのキャッシュを一括削除すると、再インデックスや依存関係の再構築が発生し、元の故障条件を追跡できなくなることがあります。
復旧手順は次の順番にします。
最小プロジェクトでも継続して失敗する場合は、削除を繰り返すより、公式のログ提出手順に沿って再現プロジェクトと診断ログを整理します。Swift関連のログとフィードバック提出資料では、報告に必要な情報を確認できます。
環境を変えるかどうかは、次の条件で決めます。
修正後は、診断レポートを削除せず、脱敏したログ、ツールチェーンのバージョン、実施した操作、再起動後の結果を保存します。Xcodeの更新前後で同じ最小プロジェクトを確認すれば、環境変更による改善と偶然の復旧を区別できます。
現在のMacが個人所有の実機であれば、ストレージ、権限、Simulator Runtime、ログイン状態を自分で管理できる反面、専用の常時稼働環境を維持する負担があります。共有されたMacや一時的なクラウド環境では、GUIセッションが切れる、ディレクトリ権限を変更できない、Runtimeを保持できないといった問題が残り、Previewの再現性を落とします。
最小プロジェクトを使っても安定しない場合は、単にキャッシュを消すのではなく、権限、Runtime、ログインセッションを独立して管理できる環境で、実際のSwiftUIプロジェクトを受け入れ確認する方が合理的です。必要な期間だけVNCMacのMacを使い、Preview、Simulator、Package依存View、再起動後の復旧まで確認してから、長期移行や自前のMac購入を判断できます。常時高負荷の作業や物理デバイス接続が中心なら自前の実機が適しますが、遠隔開発、検証、継続的なiOSビルド環境が目的なら、管理可能なリモートMacの方が切り分けをやり直しやすくなります。