Flutter Web应用缓存问题及Service Worker报错解决方案问询

一、先解决 entrypointUrl 参数导致的页面加载报错 #

你遇到的 Unexpected token '<' 本质是服务器把带 ?v=xxx 参数的 main.dart.js 请求，错误返回了HTML页面（比如404或首页 fallback），而非目标JS文件。按以下步骤修复：

1. 调整服务器配置，允许JS文件带查询参数

   • 若用Nginx，在站点配置中添加规则确保main.dart.js请求被正确解析：

     location ~* ^/main.dart.js {
       try_files $uri $uri/ =404;
     }
     

   • 若用Apache，修改mod_rewrite规则，跳过对main.dart.js的重定向：

     RewriteRule ^main.dart.js$ - [L]
     RewriteRule ^(.*)$ index.html [L]
     

2. 正确使用自动注入的 serviceWorkerVersion 变量
   确保web/index.html中loadEntrypoint的配置正确，serviceWorkerVersion是Flutter构建时自动生成的变量，无需手动定义：

   window.addEventListener('load', function(ev) {
     _flutter.loader.loadEntrypoint({
       serviceWorker: {
         serviceWorkerVersion: serviceWorkerVersion,
       },
       entrypointUrl: "main.dart.js?v=" + serviceWorkerVersion,
     }).then(function(engineInitializer) {
       return engineInitializer.initializeEngine();
     }).then(function(appRunner) {
       return appRunner.runApp();
     });
   });
   

二、修复 Service Worker 基础报错 #

注释entrypointUrl后仍有Service Worker报错，先排查基础配置：

• 确认web/manifest.json的start_url为./或匹配部署路径，保证Service Worker能正确注册。
• 部署时确保web/目录下的flutter_service_worker.js、manifest.json、main.dart.js等文件完整上传，无遗漏。
• 确保部署环境为HTTPS（localhost除外），Service Worker仅支持HTTPS协议。

三、实现无需手动清缓存的自动更新 #

解决报错后，通过以下配置让浏览器自动识别新版本：

1. 启用Service Worker更新提示
   在loadEntrypoint的Service Worker配置中添加更新回调，主动提示用户刷新：

   serviceWorker: {
     serviceWorkerVersion: serviceWorkerVersion,
     onServiceWorkerUpdateReady: () => {
       if (confirm('新版本已就绪，是否立即刷新？')) {
         window.location.reload();
       }
     },
     onServiceWorkerUpdateFailed: () => {
       console.log('Service Worker 更新失败');
     }
   }
   

2. 利用Flutter默认的哈希文件名机制
   执行flutter build web --release构建时，Flutter会自动给静态文件添加哈希后缀（如main.abc123.dart.js），浏览器会自动识别新文件，无需手动加?v=参数。同时flutter_service_worker.js会同步更新缓存清单，自动缓存新版本资源。

3. 强制关键文件不缓存
   在服务器配置中，给index.html和flutter_service_worker.js设置无缓存响应头，确保每次请求都获取最新版本：

   • Nginx示例：

     location = /index.html {
       add_header Cache-Control "no-cache, no-store, must-revalidate";
       add_header Pragma "no-cache";
       add_header Expires 0;
     }
     location = /flutter_service_worker.js {
       add_header Cache-Control "no-cache, no-store, must-revalidate";
       add_header Pragma "no-cache";
       add_header Expires 0;
     }
     

   • Apache示例：

     <Files "index.html">
       Header set Cache-Control "no-cache, no-store, must-revalidate"
       Header set Pragma "no-cache"
       Header set Expires 0
     </Files>
     <Files "flutter_service_worker.js">
       Header set Cache-Control "no-cache, no-store, must-revalidate"
       Header set Pragma "no-cache"
       Header set Expires 0
     </Files>
     

内容的提问来源于stack exchange，提问作者Eduardo Rodríguez