AWS S3 + CloudFrontでデプロイ時に静的ファイルを読み込めず白画面が発生する問題を解決する

デプロイ時に静的ファイルを読み込めず白画面が発生する問題を、AWS S3 + CloudFrontで解決した内容を紹介する記事です。AWS S3 + CloudFrontで安定した静的ファイル配信を検討している方の参考になれば幸いです。

[問題発生の背景]

• React + ViteベースのFrontendサービスを運用
• デプロイ後、断続的に白画面が発生 → 静的ファイルを読み込めない
• コンソールエラー: MIMEタイプ不一致 (text/html が返される)

[問題分析]

• MIMEタイプ不一致: 静的ファイルではなくHTMLレスポンスが返る
• GitHub Actionsのキャンセル → ECSインスタンス削除の仮説
• デプロイ時点と静的ファイル配信の不一致
• 旧バージョンの index.html が新しい静的ファイルを参照するが、そのファイルが削除されている

[解決方法]

• CloudFront + S3を活用（最終決定）
• S3の絶対パスを使用して旧バージョンの静的ファイルを維持
• Viteビルド時にファイル名へ commitHash、timestamp を追加 → 一意性を維持
• S3 Lifecycle設定で不要なファイルを自動削除
• CloudFrontと連携して高速かつ安定した静的ファイル配信を実現
• Local、Dev、Prod環境を個別に設定

[検証結果]

• CloudFront + S3方式が正常動作することを確認
• キャッシュ戦略を適用: ブラウザキャッシュ（Cache-Control, max-age）を点検
• ファイルに一意性を持たせることでキャッシュ無効化が不要
• 従来のような静的ファイル欠落問題なしに安定したデプロイが可能

[学んだこと]

• デプロイ環境での静的ファイル管理はUXに大きな影響を与えうる。
• 仮説検証では、素早くシンプルなアプローチが重要
• S3 + CloudFrontを活用したデプロイ環境最適化の経験
• 環境別のデプロイ戦略（Local、Dev、Prod）の差別化が必要
• ブラウザキャッシュの挙動（Cache-Control, from disk cache）への理解は必須

[cnaa97]

ローリングだから当然問題になります。デプロイ時間を短くするか、デプロイを分離してトラフィックを片側に寄せるブルーグリーン戦略にすればいいです。

あるいは、Reactでエラーをキャッチしてリロードを強制してもいいです。