Flutter HTML渲染器Web应用在Safari 16.4无法加载的问题求助

核心原因 #

Safari 16.4默认禁用了Web Worker中的WebGL特性，而该版本下Flutter HTML渲染器的初始化逻辑依赖这一特性，导致加载失败出现空白页面。

可行解决方案 #

1. 降级Flutter SDK版本 #

Flutter 3.7.x及更早的稳定版，其HTML渲染器未引入Web Worker中使用WebGL的逻辑，在Safari 16.4中可正常运行。如果项目对Flutter新特性依赖不高，可考虑降级到这类稳定版本构建。

2. 禁用Web Worker中的WebGL检测 #

找到构建后web/main.dart.js中检测WebGL在Worker中可用性的逻辑，强制返回false，让渲染器回退到非Worker的渲染路径。修改后重新执行：

flutter build web --release --web-renderer=html

注：若直接修改Flutter源码的web引擎部分，需重新编译SDK后再构建项目。

3. 添加浏览器版本检测与用户引导 #

在web/index.html中添加前端检测逻辑，针对Safari 16.4用户给出明确引导：

const userAgent = navigator.userAgent;
const isSafari = /^((?!chrome|android).)*safari/i.test(userAgent);
const safariVersion = userAgent.match(/Version\/(\d+\.\d+)/);
if (isSafari && safariVersion && safariVersion[1] === '16.4') {
  alert('当前Safari版本需开启WebGL in Web Workers才能运行，请前往「Develop > Experimental Features」中开启该选项，或升级Safari到16.5以上版本');
}

4. 构建时禁用Web Worker #

使用--no-web-worker参数强制禁用Web Worker，完全避开Safari 16.4的限制：

flutter build web --release --web-renderer=html --no-web-worker

注：该方案可能会带来一定性能损耗，需测试验证是否符合你的性能要求。

补充说明 #

Safari 16.5及后续版本已默认开启Allow WebGL in Web Workers，用户升级浏览器后即可正常访问，无需额外操作。

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