Flutter Web生产环境因Service Worker缓存导致灰屏问题求助

问题根源 #

新版本上线后，旧的Service Worker仍在缓存并提供旧UI资源，导致用户导航时出现灰屏。你之前修改flutter_bootstrap.js指定serviceWorkerVersion的方法在3.24.1+版本未生效，是因为该版本Flutter Web对Service Worker的初始化逻辑做了调整。

有效解决方案 #

方案1：升级flutter_bootstrap.js配置

在自定义的flutter_bootstrap.js中添加强制更新参数，让新Service Worker立即接管页面：

{{flutter_js}}
{{flutter_build_config}}

_flutter.loader.load({
  serviceWorkerSettings: {
    serviceWorkerVersion: {{flutter_service_worker_version}},
    skipWaiting: true, // 跳过等待直接激活新Service Worker
    clientsClaim: true // 立即控制所有打开的客户端页面
  },
  onEntrypointLoaded: async function (engineInitializer) {
    const appRunner = await engineInitializer.initializeEngine();
    await appRunner.runApp();
  },
});

这两个参数能确保新Service Worker部署后立即生效，无需等待用户关闭所有标签页。

方案2：修改生成的Service Worker脚本

构建完成后，找到build/web/flutter_service_worker.js文件，在末尾添加以下代码：

self.addEventListener('install', (event) => {
  self.skipWaiting(); // 安装完成后直接激活新Service Worker
});

self.addEventListener('activate', (event) => {
  event.waitUntil(self.clients.claim()); // 接管所有已打开的页面
  // 清理旧版本缓存
  event.waitUntil(
    caches.keys().then((cacheNames) => {
      return Promise.all(
        cacheNames.filter(name => !name.includes('{{flutter_service_worker_version}}'))
          .map(name => caches.delete(name))
      );
    })
  );
});

新版本上线后，这段代码会自动删除旧缓存，确保用户加载的都是最新资源。

方案3：确保构建时版本标识正确

构建生产版本时使用以下命令，保证serviceWorkerVersion生成唯一标识：

flutter build web --release

同时检查web/index.html中的占位符是否正确配置：

<script>
  var serviceWorkerVersion = '{{flutter_service_worker_version}}';
</script>

该值由构建流程自动生成，是Service Worker识别新旧版本的核心标识。

验证步骤 #

部署后打开浏览器开发者工具（F12），进入Application标签页：

• 确认新的Service Worker处于激活并控制页面的状态
• 检查缓存存储中的资源是否为最新版本
• 按下Ctrl+Shift+R强制刷新页面，随后导航各页面确认灰屏问题消失

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