Cloudfront+S3部署Next.js静态站偶发加载异常如何解决

这是Next.js静态导出+CloudFront+S3部署架构下的典型版本缓存错位问题：
Next.js每次构建会为JS/CSS等静态资源生成带内容hash的文件名，内容变更时hash同步变化。如果CloudFront边缘节点缓存了旧版本的HTML文档，用户访问时拿到的旧HTML里引用的是上一版构建的JS chunk路径，但此时S3里已经被新版本构建替换了旧chunk文件，客户端路由跳转（Next.js的Link点击跳转默认是客户端渲染，不会重新拉取HTML）时就会请求不存在的JS资源，触发渲染破碎。用户手动刷新时会重新请求最新的HTML文档，引用的JS路径和S3中现存资源匹配，就会恢复正常。
因为CloudFront不同边缘节点的缓存失效不是强一致同步的，加上部分用户本地浏览器也会缓存旧HTML，所以故障只会在部分环境、部分节点偶发，和描述的特征完全吻合。

• 复现故障时打开浏览器开发者工具，切到网络面板查看加载失败的JS资源状态码，确认是否为404/403，再比对失败资源的hash值和S3桶内当前留存的chunk hash是否匹配，同时查看当前页面HTML响应头里的日期、缓存标识，确认HTML版本和JS资源版本是否存在错位。
• 检查CloudFront当前的缓存规则，确认/_next/static/路径下的静态资源和HTML页面是否混用了相同的缓存策略，是否给HTML配置了过长的缓存TTL。
• 核对现有部署流水线的执行顺序：确认是否存在「先删除S3旧资源、再上传新资源」「未等S3资源全量上传完成就触发CloudFront缓存失效」的逻辑，这类逻辑会制造版本错位的时间窗口。
• 绑定不同区域的测试节点请求站点，验证是否只有未完成缓存同步的边缘节点会返回旧版本HTML触发故障。

1. 拆分路径配置差异化缓存策略（核心修复） #

• 对/_next/static/路径下所有带内容hash的静态资源（JS、CSS、字体、构建生成的图片），配置响应头Cache-Control: public, max-age=31536000, immutable，CloudFront对应路径的TTL设置为31536000秒。这类资源文件名和内容强绑定，永久缓存不会产生冲突，还能提升加载速度。
• 对所有HTML文档请求（所有页面对应的路由路径，不含静态文件后缀的请求），配置响应头Cache-Control: public, max-age=0, must-revalidate，CloudFront对应路径的默认TTL、最大TTL全部设置为0，强制每次请求都回源校验最新版本，从根源上避免用户拿到旧版HTML。

2. 调整部署流程消除版本错位窗口 #

部署顺序严格按照以下步骤执行，不要打乱：

1. 执行Next.js全量静态构建
2. 将构建产物中/_next/static/路径下的所有新资源上传到S3，不要删除S3中已有的旧版本静态资源
3. 确认所有静态资源上传完成、S3跨区同步结束后，再上传新版本的HTML文件
4. 最后发起CloudFront缓存失效，仅针对HTML路径做失效即可，无需全量失效所有路径，既降低成本也加快失效速度
5. 旧版本的静态资源至少保留7天再清理，给本地缓存了旧HTML的用户留足缓冲时间

3. 增加客户端容错兜底 #

在Next.js全局入口文件中增加Chunk加载失败的自动刷新逻辑，即使用户拿到旧HTML触发资源加载错误，也会自动硬刷新拉取最新版本，无需用户手动操作，代码示例：

// pages/_app.js 全局入口
if (typeof window !== 'undefined') {
  window.addEventListener('error', (e) => {
    const isChunkLoadFail = [
      'ChunkLoadError',
      'Loading chunk',
      'Failed to fetch dynamically imported module'
    ].some(keyword => e.message.includes(keyword))
    if (isChunkLoadFail) {
      window.location.reload(true) // 硬刷新跳过本地缓存
    }
  })
}

4. CloudFront边缘兜底配置 #

给CloudFront配置自定义错误响应：当/_next/static/路径下的资源返回403/404状态码时，设置最小TTL为0，强制回源重新拉取资源，避免边缘节点缓存错误响应。

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