S3托管静态NextJS站点刷新非首页返回404问题如何解决

这个问题是静态SPA项目托管在对象存储时的典型问题，核心原因有两个：

• Next.js的页面跳转走的是客户端JS路由，不需要向服务端请求新的HTML文件，所以导航跳转正常
• 刷新页面时浏览器会直接向S3请求当前路径对应的静态文件，比如你访问/page1，S3默认会查找根目录下的page1文件，如果你导出的静态文件是page1.html或者/page1/index.html，S3找不到对应文件就返回404
• 你之前将错误页重定向到index.html用的是301/302跳转，会导致浏览器地址栏路径变成根路径，Next.js客户端路由识别到根路径就渲染首页，所以刷新后跳首页

方案1：适配S3默认索引规则（无需复杂路由配置，推荐） #

第一步：调整Next.js导出配置 #

修改项目根目录的next.config.js文件，添加如下配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 开启静态导出
  output: 'export',
  // 开启路径尾斜杠
  trailingSlash: true
}

module.exports = nextConfig

配置完成后重新执行npm run build导出静态文件，此时/page1路由会生成为/page1/index.html的目录结构，和S3的默认索引查找逻辑完全匹配。

第二步：配置S3静态网站托管 #

进入S3桶的「属性」-「静态网站托管」页面：

• 启用静态网站托管
• 索引文档填写index.html
• 错误文档填写404.html（没有的话可以随便填个不存在的文件，不需要配置重定向）
  配置完成后重新上传新导出的静态文件到S3桶即可。
  此时访问/page1时S3会自动返回/page1/index.html的内容，刷新也不会404，也不会跳首页。

方案2：保留无尾斜杠路径，适配客户端路由 #

如果不想在路径后加尾斜杠，可以用这个方案：

第一步：导出静态文件时不开启trailingSlash #

next.config.js只配置output: 'export'即可，此时/page1路由会导出为page1.html文件。

第二步：配置S3路由规则 #

在S3静态网站托管配置中找到「路由规则」，添加如下规则：

[
  {
    "Condition": {
      "HttpErrorCodeReturnedEquals": "404"
    },
    "Redirect": {
      "HttpRedirectCode": "200",
      "ReplaceKeyWith": "index.html"
    }
  }
]

注意这里的重定向码是200，不是301/302，所以浏览器地址栏的原路径会保留，Next.js客户端路由会自动根据当前路径渲染对应子页面，不会跳首页

如果你同时使用CloudFront作为CDN #

需要额外调整CloudFront配置：

• 进入对应分发的「错误页面」标签，添加自定义错误响应：
  • HTTP错误码选择404
  • 自定义错误响应选择「是」
  • 响应页面路径填写/index.html
  • HTTP响应码选择200
• 保存配置等待分发生效即可。

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