Flutter Web部署新版本后Service Worker不生效问题求助

核心修复步骤 #

• 绑定Service Worker版本号到请求URL
  你的代码中serviceWorkerUrl仅添加了?v=但未拼接实际版本号，导致浏览器判定为同一资源直接读取缓存。修改为带动态版本号的URL：

  serviceWorkerUrl: `/flutter_service_worker.js?v=${serviceWorkerVersion}`,
  

  每次构建后serviceWorkerVersion会基于文件哈希更新，URL随之变化，浏览器会主动请求新的Service Worker文件。

• 添加版本校验与强制刷新逻辑
  在加载Flutter引擎前，主动校验当前激活的Service Worker版本是否与新部署版本一致，不一致则触发更新并强制刷新页面：

  window.addEventListener('load', async function(ev) {
    // 检查Service Worker版本匹配情况
    if ('serviceWorker' in navigator) {
      const registration = await navigator.serviceWorker.getRegistration();
      if (registration?.active?.scriptURL.includes(serviceWorkerVersion) === false) {
        // 版本不匹配时触发更新并强制刷新
        await registration.update();
        window.location.reload(true);
      }
    }
  
    // 加载Flutter应用
    _flutter.loader.loadEntrypoint({
      entrypointUrl: `/main.dart.js?v=${serviceWorkerVersion}`, // 给主JS文件也添加版本号
      serviceWorker: {
        serviceWorkerVersion: serviceWorkerVersion,
        serviceWorkerUrl: `/flutter_service_worker.js?v=${serviceWorkerVersion}`,
      }
    }).then(function(engineInitializer) {
      return engineInitializer.initializeEngine();
    }).then(function(appRunner) {
      return appRunner.runApp();
    });
  });
  

额外优化：运行时检测新版本 #

如果需要在应用运行中实时检测更新（而非仅页面加载时），可在Dart代码中添加监听逻辑：

import 'package:flutter_web_plugins/flutter_web_plugins.dart';
import 'dart:html' as html;

void listenForSwUpdates() {
  if (kIsWeb) {
    html.window.navigator.serviceWorker?.addEventListener('controllerchange', (event) {
      if (html.window.confirm('检测到新版本，是否立即刷新？')) {
        html.window.location.reload(true);
      }
    });
  }
}

在main()函数初始化完成后调用该方法即可。

为什么之前的方案未完全生效？ #

• 修改pubspec版本号：Flutter Web的serviceWorkerVersion由构建文件哈希生成，与pubspec声明的版本号无关，因此该操作无法触发Service Worker更新。
• 添加no-cache元标签：仅对HTML文档本身生效，Service Worker、main.dart.js等静态资源的缓存由HTTP响应头和Service Worker自身策略控制，元标签作用有限。
• 简单缓存清除逻辑：未针对Service Worker的版本校验做精准处理，无法稳定触发更新流程。

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