Flutter Web release模式部署GitHub Pages后内容不更新如何解决

核心原因 #

这类问题90%以上都是缓存+构建流程不规范导致，和Flutter 2.0本身的代码逻辑无关，debug模式正常说明功能代码没有问题：

• Flutter 2.0 release构建默认会生成带强缓存策略的flutter_service_worker.js（PWA服务工作线程），旧版本的服务工作线程会拦截浏览器请求，直接返回本地缓存的旧资源，不会主动请求服务器拉取新版本。
• GitHub Pages依托全球CDN分发静态资源，默认对html、js等静态资源设置了10分钟到数小时不等的缓存周期，若未触发缓存刷新，CDN节点会持续返回旧版本文件。
• 部署时未清空旧目录的残留文件，旧版本带哈希命名的资源没有被清理，新的index.html错误引用到旧资源，导致页面显示旧版本。

排查修复步骤 #

• 第一步：清理本地构建缓存
  不要直接执行构建命令，先依次执行以下操作：
  1. 运行flutter clean清除本地所有历史构建产物
  2. 删除本地存放GitHub Pages部署文件的目录（即你之前复制build/web内容的目标目录）下的全部文件，不要保留任何旧文件
  3. 运行flutter pub get同步依赖
  4. 重新执行flutter build web --release，构建完成后检查build/web目录下的main.dart.js修改时间为当前时间，确认产物是最新生成的
• 第二步：处理Service Worker强缓存问题
  Flutter 2.0默认的PWA缓存策略非常激进，是导致版本不更新的最常见原因：
  • 如果你不需要PWA离线访问能力，构建时直接加参数禁用服务工作线程：flutter build web --release --pwa-strategy=none，构建产物里不会生成带强缓存逻辑的service worker文件，从根源避免缓存拦截问题。
  • 如果你需要保留PWA能力，不要手动修改生成的flutter_service_worker.js文件，确认每次构建时该文件是自动生成的新版本，不要用旧文件覆盖。
• 第三步：规范部署操作
  1. 将新生成的build/web目录下所有文件完整复制到GitHub Pages对应的部署目录/分支，不要只复制你修改过的文件，确保所有旧的残留文件都被清理、替换为新构建的文件
  2. 提交代码推送到GitHub后，先进入仓库的Pages配置页面，等部署状态显示为已完成（绿色标识）后再尝试访问，不要刚推送完就刷新
  3. 访问时如果还是旧版本，打开浏览器开发者工具，在Application面板找到Service Workers选项，注销当前站点的旧服务工作线程，再执行清除站点数据操作，最后按Ctrl+Shift+R（Windows/Linux）或Cmd+Shift+R（Mac）硬刷新页面跳过本地缓存。
• 第四步：解决GitHub Pages CDN缓存问题
  打开你项目根目录下web/index.html源文件，在<head>标签内添加以下meta标签，禁止浏览器和CDN缓存入口html文件：

  <meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
  <meta http-equiv="Pragma" content="no-cache">
  <meta http-equiv="Expires" content="0">
  

  入口html不缓存的情况下，每次访问都会拉取最新的index.html，自动引用最新构建生成的带哈希值的js、css资源，不会出现资源引用错误。

标准部署流程（可避免后续出现同类问题） #

• 每次代码修改完成确认debug模式功能正常后，先执行flutter clean
• 执行flutter pub get确认依赖版本正确
• 根据是否需要PWA能力，执行对应构建命令：
  • 不需要PWA：flutter build web --release --pwa-strategy=none
  • 需要PWA：flutter build web --release
• 完全清空GitHub Pages部署目录下的旧文件
• 将build/web下的全部新构建产物复制到部署目录
• 提交推送代码，等待GitHub Pages部署状态显示完成
• 首次访问新版本时做一次硬刷新，清除本地旧缓存即可

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