Flutter Web 使用 FlutterLoader.load 替代 loadEntrypoint

问题描述

升级至 Flutter 3.22.0 后，使用 Web 平台时系统会提示警告：FlutterLoader.loadEntrypoint 已被废弃，请改用 FlutterLoader.load。但当开发者将代码中的 loadEntrypoint 替换为 load 后，会出现新的错误提示："FlutterLoader.load requires _flutter.buildConfig to be set"。

该问题的本质是 Flutter 3.22.0 中对 Web 初始化机制进行了重构，新版 load 方法需要额外的 _flutter.buildConfig 配置参数，而旧版初始化脚本无法直接兼容新 API 要求。

解决方案

推荐方法

根据项目初始化复杂度选择以下两种方案：

✅ 方案一：重新生成 Web 文件（推荐）

适用于新项目或无需自定义初始化的场景：

删除项目中旧的 Web 资源文件
通过 Flutter 命令重新生成 Web 平台文件

bash

# 删除原有 web 目录
rm -rf web/

# 重新生成 Web 平台文件
flutter create . --platforms=web

此方法会自动生成适配最新版本的标准初始化脚本，无需手动修改代码。

✅ 方案二：手动更新初始化脚本

适用于需要自定义初始化行为的场景（如添加启动画面）：

更新 index.html 的初始化脚本，包含 _flutter.buildConfig 变量并遵循新 API 规范：

html

<body>
  <!-- 启动画面元素 -->
  <picture id="splash">
    <source srcset="splash/img/logo-light.png" media="(prefers-color-scheme: light)">
    <source srcset="splash/img/logo-dark.png" media="(prefers-color-scheme: dark)">
    <img width="300" height="300" alt="App Logo"/>
  </picture>

  <script>
    window.addEventListener('load', function(ev) {
      // 必填的 Flutter 配置变量
      {{flutter_js}}
      {{flutter_build_config}}

      _flutter.loader.load({
        serviceWorker: {
          serviceWorkerVersion: {{flutter_service_worker_version}},
        },
        onEntrypointLoaded: async (engineInitializer) => {
          const appRunner = await engineInitializer.initializeEngine();
          
          // 移除启动画面
          const splash = document.getElementById('splash');
          if (splash) splash.remove();
          
          appRunner.runApp();
        }
      });
    });
  </script>
</body>

关键变更说明

必须注入 buildConfig：通过 {{flutter_build_config}} 模板变量注入所需配置

新的初始化流程：

javascript

_flutter.loader.load({
  // 配置项
  onEntrypointLoaded: (engineInitializer) => {
    engineInitializer.initializeEngine().then(appRunner => {
      appRunner.runApp();
    });
  }
});

生命周期控制：在 initializeEngine() 完成后执行 runApp()，可在此插入自定义逻辑

版本兼容性说明

注意事项

该 API 变更影响 Flutter 3.22.0+ 的 Web 项目
混合使用新旧 API 会导致 Uncaught TypeError: _flutter.loader.load is not a function
官方文档参考：Flutter Web 初始化文档

迁移策略建议

简单项目 → 采用方案一（重新生成文件）
定制化项目 → 采用方案二（手动更新脚本）
遗留项目 → 备份 web/ 目录后先尝试方案一，再移植自定义逻辑

示例工程结构

成功迁移后的典型文件结构：

your_project/
├── lib/          # Dart 主代码
├── web/          # 重新生成的Web资源
│   ├── index.html # 更新后的入口文件
│   └── ...       
└── pubspec.yaml  # Flutter 3.22.0+

按需选用上述方案可彻底解决废弃警告和 _flutter.buildConfig缺失问题，同时保证应用在最新 Flutter 版本上正常运行。

相关文章

Flutter Web 使用 FlutterLoader.load 替代 loadEntrypoint ​

问题描述 ​

解决方案 ​

✅ 方案一：重新生成 Web 文件（推荐） ​

✅ 方案二：手动更新初始化脚本 ​

关键变更说明 ​

版本兼容性说明 ​

迁移策略建议 ​

示例工程结构 ​