Flutter Web使用canvaskit渲染器部署后卡在启动页问题求助

1. 先排查线上浏览器错误日志 #

• 打开Chrome/Safari的开发者工具（F12/Command+Option+I），切换到Console标签页，刷新页面，查看是否有报错信息（比如资源加载失败、JS执行错误）
• 切换到Network标签，筛选JS和Other类型，检查canvaskit.js、canvaskit.wasm等资源是否加载成功，有没有404/500状态码

2. 检查Firebase Hosting的缓存配置 #

• 确认firebase.json里的缓存规则是否影响了Flutter Web资源加载，尤其是canvaskit相关文件。如果对/canvaskit/目录设置了过久的缓存，可能导致旧资源和新代码不兼容
• 可以临时修改缓存规则，添加：

  "headers": [
    {
      "source": "/canvaskit/**",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=3600"
        }
      ]
    }
  ]
  

  部署后清除浏览器缓存再测试

3. 验证Flutter构建参数 #

• 部署时确保使用完整的构建命令：flutter build web --web-renderer canvaskit，不要遗漏渲染器指定参数
• 检查构建产物的build/web/main.dart.js开头是否包含canvaskit相关标识，确认构建时确实启用了canvaskit渲染器

4. 排查flutter_native_splash的影响 #

• 临时禁用flutter_native_splash（注释掉pubspec.yaml里的插件配置，重新构建部署），验证是否还会卡在启动页
• 检查index.html中插件注入的脚本，是否存在在canvaskit初始化完成前阻止页面渲染的逻辑，比如过度严格的加载状态判断

5. 检查代码中的环境差异逻辑 #

• 排查本次修改的少量代码，是否存在依赖调试环境特性的逻辑：
  • 全局状态初始化（比如Provider、GetX的启动逻辑是否在生产环境中阻塞）
  • 网络请求（线上是否存在跨域限制、API返回异常）
  • 自定义Canvas绘制（canvaskit对Canvas API的实现与html渲染器存在差异）

6. 尝试版本兼容验证 #

• 虽然flutter doctor检测正常，但3.3.10版本的canvaskit可能存在已知部署问题。可以尝试升级到同分支的后续稳定小版本，或回退到之前确认正常的构建版本，对比差异定位问题

内容的提问来源于stack exchange，提问作者AlanGuoDev