Safari旧版本缓存React应用致白屏问题求助（Node.js+NGINX环境）

这是典型的浏览器缓存与React打包chunk哈希不匹配问题，Safari 16.x及旧版本对Cache-Control的解析逻辑和Chrome/Edge存在差异，即便设置了no-cache，它仍会优先读取本地缓存的旧chunk文件。而新版本打包后的chunk文件名虽带哈希，但如果入口HTML被缓存，页面就会加载旧的chunk路径，最终触发加载错误。

1. 修正入口HTML的缓存策略 #

no-cache仅要求每次请求验证缓存有效性，Safari在部分场景下仍会直接用缓存。给入口HTML文件设置更严格的缓存规则：

// Node.js http.createServer 中的响应头配置
if (req.url === '/' || req.url.endsWith('.html')) {
  res.setHeader('Cache-Control', 'no-store, must-revalidate');
  res.setHeader('Expires', '0');
} else {
  // 静态资源（JS/CSS/图片等）用带哈希的长期缓存
  res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
}

• no-store：禁止浏览器和中间缓存存储任何版本的响应，每次都从服务器拉最新HTML
• must-revalidate：强制缓存过期后必须向服务器验证有效性
• Expires: 0：兼容旧版浏览器的缓存控制逻辑

2. 确认React打包的chunk哈希配置 #

检查你的打包工具（Webpack/Vite）是否开启内容哈希，确保文件内容变化时，文件名的哈希值同步更新：

• Webpack：在output配置中使用[contenthash]

  output: {
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].chunk.js',
  }
  

• Vite：默认已开启内容哈希，打包后文件会自动带[hash]后缀，无需额外配置

3. 处理Safari缓存残留 #

对于已经出现问题的用户，仅强制刷新可能无法彻底清除缓存，需引导他们手动清理：

• 操作流程：Safari菜单 → 偏好设置 → 隐私 → 管理网站数据 → 搜索你的域名 → 移除 → 重启浏览器

4. 可选：添加版本检测自动刷新 #

在入口HTML中加入一段JS，检测当前应用版本与服务器最新版本是否一致，不一致则自动强制刷新：

<script>
  // 服务器渲染时注入当前版本号，比如从package.json的version字段获取
  const currentVersion = '<%= process.env.npm_package_version %>';
  fetch('/version.json')
    .then(res => res.json())
    .then(data => {
      if (data.version !== currentVersion) {
        window.location.reload(true); // 强制刷新，忽略本地缓存
      }
    })
    .catch(err => console.error('版本检测失败:', err));
</script>

同时在Node.js服务器新增/version.json接口，返回最新版本号：

app.get('/version.json', (req, res) => {
  res.json({ version: require('./package.json').version });
});

• Safari 16.x及旧版本对缓存规则的执行更严格，no-cache不等于禁止缓存，只是验证缓存有效性；no-store才是完全禁止缓存入口HTML
• 静态资源（chunk文件）适合长期缓存，因为文件名带内容哈希，内容变化时文件名也会更新，不会出现缓存冲突
• 入口HTML必须设置不缓存，确保用户每次打开页面都能获取最新的HTML，从而加载对应版本的chunk文件

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