本文详解 flutter web 应用中加载指示器（splash screen）无法被正确移除的根本原因及修复方法，重点说明 `flutter.js` 初始化机制替代 `main.dart.js` 直接引入的必要性，并提供兼容最新 flutter 版本的完整 `index.html` 实现。
在 Flutter Web 项目中，为提升用户体验，常需在 Flutter 引擎初始化完成前显示自定义加载页（如 splash 图标）。官方文档推荐通过 onEntrypointLoaded 回调移除 DOM 中的 #loading 元素。但许多开发者发现：即使调用 document.getElementById("loading").remove()，加载层仍残留于页面上——这并非代码逻辑错误，而是因项目未适配新版 Flutter Web 的初始化架构所致。
? 根本原因：过时的初始化脚本链
旧版 index.html 直接引入 main.dart.js 并手动调用 _flutter.loader.loadEntrypoint，但该方式已废弃。Flutter 3.10+（尤其是 3.13 起）强制要求使用 flutter.js 作为统一入口脚本，它会自动注入 serviceWorkerVersion、注册 window.flutter 全局对象，并确保 _flutter.loader 在 DOM 就绪后才可用。若缺失 flutter.js 或仍保留 main.dart.js，_flutter.loader 可能未定义或行为异常，导致 remove() 调用静默失败。
✅ 正确实现步骤
-
重建 Web 支持（关键！）
运行以下命令，生成符合当前 Flutter SDK 规范的 Web 模板：flutter create . --platforms=web
⚠️ 注意：此操作会覆盖原有 web/index.html 和 web/flutter.js，请提前备份自定义样式或配置。
-
按规范组织 中的脚本
包含以下两段（顺序不可颠倒）：
确保 index.html<script> // serviceWorkerVersion 由 flutter build 自动注入，请勿修改 var serviceWorkerVersion = null; </script> <script src="flutter.js" defer></script>
flutter.js 是 Flutter 官方提供的轻量级引导器，负责动态加载 main.dart.js、处理 Service Worker 版本控制，并暴露稳定 API。
-
在 底部编写安全的移除逻辑
使用可选链（?.）避免元素不存在时报错，并确保在 initializeEngine() 的 Promise 解析后执行：<script> window.addEventListener('load', function () { _flutter.loader.loadEntrypoint({ serviceWorker: { serviceWorkerVersion }, onEntrypointLoaded: function (engineInitializer) { engineInitializer.initializeEngine().then(function (appRunner) { // ✅ 安全移除 loading 层（支持元素不存在场景） document.getElementById('loading')?.remove(); // ✅ 启动 Flutter 应用 appRunner.runApp(); }); } }); }); </script>
? 注意事项与最佳实践
- 不要手动引入 main.dart.js：flutter.js 会按需加载它，显式引入会导致重复加载或冲突。
-
CSS 作用域隔离：将加载页样式内联在 内（如示例所示），避免全局 body 样式污染主应用布局。
- 兼容性兜底：若需支持旧版 Flutter，可通过 if (typeof _flutter !== 'undefined') 判断初始化器是否存在。
- 调试技巧：在浏览器控制台执行 console.log(_flutter)，确认其是否为有效对象；若为 undefined，即表明 flutter.js 未正确加载。
通过以上重构，#loading 元素将在 Flutter 渲染第一帧前被精准移除，实现无缝过渡。此方案不仅解决当前问题，更确保项目长期兼容 Flutter Web 的持续演进。
立即学习“前端免费学习笔记（深入）”；
