Gatsby升级4.6.0后部署出现Loading Static Query白屏问题求助

根因说明 #

该问题和你写的Static Query本身无关，查询语句大小也不会触发该故障，核心原因是gatsby-plugin-offline插件生成的Service Worker缓存策略和新版本部署逻辑不匹配：
Gatsby每次构建都会给静态查询、页面数据生成唯一哈希ID，新版本发布后，用户浏览器中还在运行旧版本的Service Worker，缓存了旧版JS资源和查询数据，新旧版本的哈希ID不匹配，导致静态查询数据无法正常读取，就会卡在加载提示页面。只有清除浏览器缓存/隐身模式（无旧Service Worker）时才会恢复正常。 #

解决方案 #

方案一：调整离线插件配置（保留离线功能） #

1. 修改gatsby-config.js中gatsby-plugin-offline的配置，优化缓存规则：

{
  resolve: `gatsby-plugin-offline`,
  options: {
    // 页面启动时立即检查Service Worker更新
    updateOnStartup: true,
    // 新版Service Worker安装完成后立即激活，跳过等待
    skipWaiting: true,
    // 自动删除旧版本的所有缓存资源
    deletePreviousCaches: true,
    runtimeCaching: [
      // 页面数据、静态查询类请求优先走网络，避免读取旧缓存
      {
        urlPattern: /page-data\/.*\.json$/,
        handler: `NetworkFirst`,
        options: {
          cacheableResponse: {
            statuses: [200]
          }
        }
      },
      // 静态资源可继续使用缓存优先策略，设置30天过期
      {
        urlPattern: /\.(js|css|png|jpg|svg)$/,
        handler: `CacheFirst`,
        options: {
          cacheName: `static-assets`,
          expiration: {
            maxAgeSeconds: 30 * 24 * 60 * 60,
          }
        }
      }
    ]
  }
}

2. 在项目根目录的gatsby-browser.js中添加Service Worker更新监听，检测到新版本时提示用户刷新页面：

export const onServiceWorkerUpdateReady = () => {
  const confirmReload = window.confirm(`网站已更新，点击确定刷新即可获取最新内容`);
  if (confirmReload) window.location.reload();
};

3. 调整AWS CloudFront的缓存规则，对service-worker.js文件设置强制不缓存，响应头配置为：Cache-Control: max-age=0, no-cache, no-store, must-revalidate，确保用户每次访问都能拿到最新的Service Worker文件，不会被CDN缓存旧版本。

方案二：直接移除离线插件（无离线功能需求时推荐） #

如果你的站点不需要离线访问能力，直接删除gatsby-config.js中gatsby-plugin-offline的相关配置即可，从根源避免Service Worker缓存导致的各类版本兼容问题，该方案改造成本最低。 #

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