Flutter Web部署后出现白页及Uncaught (in promise) null错误的解决方法

DevOps 小满

2026-6-14

解决Flutter Web部署后白页及"Uncaught (in promise) null"错误

核心问题排查与修复

从你提供的flutter_bootstrap.js代码来看，存在几处配置错误直接导致了初始化失败：

1. 修正资源路径配置

代码里config中的assetBase和canvasKitBaseUrl用了字面量字符串"assetBase"和"canvasKitBaseUrl"，这是无效值，Flutter无法定位到正确的资源文件：

如果资源部署在网站根目录，直接删除这两个配置项（使用默认路径），或显式设置为"/"：
```
config: {
  'renderer': 'html'
  // 移除无效的assetBase和canvasKitBaseUrl配置
},
```

如果资源部署在子目录（比如/flutter-app/），则设置为对应路径：

config: {
  'renderer': 'html',
  'assetBase': '/flutter-app/',
  'canvasKitBaseUrl': '/flutter-app/canvaskit/'
},

2. 调整Service Worker配置

若部署环境未配置Service Worker，或serviceWorkerVersion值不正确，会触发初始化报错：

不需要Service Worker的话，直接删除serviceWorkerSettings配置块：

// 移除这段配置
// serviceWorkerSettings: {
//   serviceWorkerVersion: "2683295721",
// },

若要使用Service Worker，确保serviceWorkerVersion与Flutter构建时自动生成的版本一致（不要手动修改该值）。

3. 优化错误排查（可选）

为了更精准定位问题，可以在捕获块中补充详细错误打印，甚至添加用户提示：

onEntrypointLoaded: async function (engineInitializer) {
  try {
    let appRunner = await engineInitializer.initializeEngine();
    await appRunner.runApp();
    await addDelay(500);
    if (web_initial_loader) {
      web_initial_loader.remove();
    }
  } catch (error) {
    console.error("Flutter初始化错误详情:", error, error.stack);
    // 给用户显示加载失败提示
    if (web_initial_loader) {
      web_initial_loader.innerHTML = "应用加载失败，请刷新重试";
    }
  }
}