Unity WebGLのビルドが終わらない：原因別チェックリスト
遊びをつくる執筆にClaudeを使用しています。
Unity WebGLのビルドは、同じプロジェクトでもマシンの状態や設定の組み合わせによって、数分で終わることもあれば、何十分も進捗バーが止まったまま戻ってこないこともあります。「フリーズしているのか、処理中なのか」の判断がつきにくい点がこのビルドの厄介さです。 この記事では、「ビルドが終わらない・途中で止まる」という症状を原因別に整理し、それぞれに対応するチェック項目と対処手順を示します。「ビルド時間が長すぎる（遅い）」と「ビルドが途中でエラーになる」は似て非なる問題なので、どちらに当てはまるかを最初に判断するところから始めましょう。
この記事の目次
まず「止まっている」のか「時間がかかっている」のかを見極める
Unity WebGLのビルドは通常のスタンドアロンビルドより大幅に時間がかかります。EmscriptenというC++→WebAssemblyのコンパイラがC#をいったんC++に変換してからコンパイルするため、小さなプロジェクトでも10〜20分、アセットが多いプロジェクトでは1時間を超えることがあります。
判断の目安は次の二点です。
- Consoleウィンドウに何も出ていないまま15分以上経過している場合は、処理が止まっている可能性が高いです。
- Consoleに定期的に行が追加されている場合は、時間はかかっていても処理は進んでいます。
タスクマネージャー（Windows）またはアクティビティモニタ（macOS）でCPU使用率を確認するのも有効です。Unityやtundra、emccなどのプロセスがCPUを消費していれば、ビルドは動いています。これらが0%になって数分経っても何も変わらなければ、フリーズと判断して次のセクションに進んでください。
原因1：メモリ不足とスワップによる実質停止
WebGLビルドはメモリを大量に使います。EmscriptenのコンパイルフェーズではマシンRAMが不足するとOSがスワップ領域（仮想メモリ）を使い始め、処理速度が極端に落ちて「止まっているように見える」状態になります。
チェック項目
- 物理RAMが16GB未満のマシンで大規模プロジェクトをビルドしていないかを確認します。8GBのマシンでは、アセット量によってはスワップが頻発します。
- ビルド中に他のアプリケーションを開いていないか確認します。ブラウザのタブを多く開いた状態でのビルドは要注意です。
- macOSでは「メモリプレッシャー」がオレンジ・赤になっていないかをアクティビティモニタで確認します。
対処
ビルド中はUnity以外のアプリをできる限り閉じます。メモリ不足が慢性的な場合は、Player Settings → Other Settings → Managed Stripping Level を「High」に設定するとコード量が減り、コンパイル負荷が下がります。また、使っていないアセットをプロジェクトから除外することも効果があります。
原因2：キャッシュの破損とインクリメンタルビルドの誤動作
UnityのWebGLビルドはインクリメンタルビルド（差分だけ再ビルド）を試みますが、キャッシュファイルが壊れているとその判定自体がループして止まることがあります。
チェック項目
- 最後に成功したビルドからUnityのバージョンを変えていないか確認します。バージョン変更後の最初のビルドはフルビルドになるため時間がかかりますが、変更直後にキャッシュが混在すると異常停止することがあります。
- Library フォルダが以前のバージョンのまま残っていないかを確認します。
対処
Library フォルダを削除してからビルドを再試行します。Libraryはビルド時に自動再生成されるキャッシュフォルダなので削除しても問題ありません。ただし削除後の最初のインポートに数分〜十数分かかるため、時間を確保してから実施してください。
次の手順で行います。
- Unityエディタを閉じます。
- プロジェクトフォルダ直下の Library フォルダを削除します（Assets や ProjectSettings は触りません）。
- Unityを再起動してプロジェクトを開きます。
- インポートが完了したあとにWebGLビルドを再実行します。
原因3：シェーダーコンパイルの詰まり
WebGLビルドのかなりの時間はシェーダーのコンパイルが占めます。カスタムシェーダーが多い、またはURPやHDRPを使っているプロジェクトでは、シェーダーバリアント（組み合わせ）が膨大になり、数百〜数千のバリアントを一つずつコンパイルする工程で長時間止まって見える状態になります。
チェック項目
- ConsoleウィンドウのStatusバーに「Compiling shader variants」のような表示が出たまま止まっていないかを確認します。
- プロジェクトにカスタムシェーダーが多数含まれていないかを確認します。
対処
Shader Variantコレクションを使ってバリアントを必要なものに絞るのが根本的な対処です。Edit → Project Settings → Graphics にある「Shader Stripping」のオプションでビルドに不要なバリアントを除外できます。
すぐに試せる暫定対処としては、Edit → Project Settings → Player → Other Settings → Graphics APIs でWebGLがWebGL 2.0のみになっているか確認します。WebGL 1.0との両対応にしているとバリアントが増えます。
また、URPを使っている場合はURPアセットの「Additional Lights」や「Shadows」の設定を最小限にすると、バリアントの組み合わせを大幅に減らせます。
原因4：ビルドスクリプトや外部ツールとの競合
エディタ拡張やIPreprocessBuildWithReportなどのビルド前フックが無限ループや例外を起こしていると、ビルドがそのステップで止まり続けます。アセットストアから導入したツールが原因になることもあります。
チェック項目
- Consoleの出力が途絶えているタイミングが、いつもビルドの同じ段階かを確認します（「Preprocessing assets」など）。毎回同じ箇所で止まる場合はスクリプトが原因の可能性が高いです。
- 最近アセットストアのパッケージを追加・更新していないかを確認します。
対処
原因を切り分けるために、新しい空のプロジェクトで同じビルド設定のWebGLビルドを実行してみます。空プロジェクトで正常に終わるなら、元のプロジェクトのスクリプトかアセットに問題があります。
怪しいと思うパッケージを一時的に無効化するには、パッケージのフォルダ名の先頭に _ を付けてリネームするか、Package Managerから削除して再ビルドします。問題が解消したらそのパッケージを特定できます。
原因5：Unityエディタ自体のクラッシュ・ハング
上記のいずれでもなく、エディタのプロセスそのものがフリーズしているケースもあります。
判断と対処
タスクマネージャーやアクティビティモニタでUnityプロセスのCPU・メモリが長時間ゼロのまま変化せず、エディタのウィンドウも操作不能になっている場合はエディタがフリーズしています。この場合はプロセスを強制終了してから再起動します。
再起動後は次の点を確認します。
- Edit → Preferences → GI Cache の「Clean Cache」を実行します（GIキャッシュの破損がビルド停止を引き起こすことがあります）。
- Unityのバグレポートツールでクラッシュログを確認し、エラーの内容をUnityフォーラムやIssue Trackerで検索します。同じバージョンの既知バグの場合はパッチリリースへのアップデートで解消することがあります。
次の行動
ビルドが止まっている場合は、まずConsoleの最終ログとCPU使用率を確認して「動いているか止まっているか」を判定し、上記の原因別チェックリストの上から順に照合してください。Libraryフォルダの削除とシェーダーバリアントの削減は副作用が少ないため、原因が不明なときの最初の対処として試す価値があります。WebGLビルドが完成したら、アソバースへのZIPファイル投稿でそのまま公開できますので、ぜひ試してみてください。
参考資料
- Unity公式ドキュメント「WebGL: Building and running」
- Unity公式ドキュメント「Shader variant stripping」
- Unity公式ドキュメント「Managed code stripping」
- Unity Issue Tracker（既知バグの確認用）
