FlutterLoader.loadEntrypointの非推奨化と移行ガイド
問題点
Flutter 3.22.0にアップデートする際、FlutterLoader.loadEntrypointの使用が非推奨化され、代わりにFlutterLoader.loadの使用が推奨されています。しかしながら、loadEntrypointを単純にloadに置換すると、以下のエラーが発生します：
"FlutterLoader.load requires _flutter.buildConfig to be set"この問題は、古いバージョンのFlutterで作成されたプロジェクトをアップグレードする際に発生します。loadメソッドには新しい必須パラメータと初期化ロジックが追加されており、単純なリネームだけでは対応できません。
解決策
以下に効果的な移行手法を2パターン紹介します。いずれの方法も公式ドキュメント（Flutter Webブートストラップ）に準拠した最新の初期化方法です。
方法1: Webファイルの完全再生成（シンプルなプロジェクト向け）
最も確実で簡単な方法は、プロジェクトのwebディレクトリを完全に再生成することです：
bash
# 既存のwebディレクトリを削除（バックアップ推奨）
rm -rf web
# FlutterにWeb向けファイルを再生成させる
flutter create . --platforms=web特徴
- メリット：公式推奨方式で実装の手間が最小限
- 適用先：複雑なカスタマイズを行っていない標準的なプロジェクト
- 出力ファイル：自動的に
flutter_bootstrap.jsを利用した最新初期化コードが生成されます
方法2: 手動での高度な移行（カスタマイズ済みプロジェクト向け）
カスタム初期化やスプラッシュ画面などを実装しているプロジェクトの場合、以下のように手動でindex.htmlを更新します：
html
<body>
<!-- スプラッシュ画面などのカスタム要素 -->
<picture id="splash">
<source srcset="splash/img/splash.png">
<img src="splash/img/splash.png" alt="起動画面">
</picture>
<script>
window.addEventListener('load', function(ev) {
{{flutter_js}}
{{flutter_build_config}} // エラーの原因となる必須設定
_flutter.loader.load({
serviceWorker: {
serviceWorkerVersion: {{flutter_service_worker_version}},
},
onEntrypointLoaded: function(engineInitializer) {
engineInitializer.initializeEngine().then(function(appRunner) {
// アプリ起動前にスプラッシュ画面を削除
if(document.getElementById('splash'))
document.getElementById('splash').remove();
appRunner.runApp();
});
}
});
});
</script>
</body>注意点
{{flutter_build_config}}の挿入が必須 - これがないと_flutter.buildConfig not setエラーが発生serviceWorkerVersionと{{flutter_service_worker_version}}の整合性が必要onEntrypointLoadedコールバック内での初期化処理がポイント
移行のポイント解説
変更が必要な理由
- レンダリング最適化：新しいローダーはサービスワーカー管理やリソース先読み処理を改善
- パラメータ変更：
loadEntrypointより3つの追加引数（entrypointUrl, shouldLoadMain, loadMain）が削除され簡略化 - 必須設定：
_flutter.buildConfigにランタイム設定情報を設定することが必須に
新初期化フローの仕組み
適用後の動作確認
正しく移行が完了すると：
- 非推奨警告がコンソールに表示されない
- アプリ起動前にビルド設定エラーが発生しない
loadメソッドが定義通りのライフサイクル（スプラッシュ表示→初期化→切り替え）を実行
移行後に問題が発生する場合は、DevToolsの「ネットワーク」タブでflutter_bootstrap.jsとbuild_config.jsのロード状況を確認してください。