NextJS部署在CloudFront CDN下使用router.push触发硬刷新问题求助

• 配置NextJS的basePath
  因为应用部署在/next子路径下，必须在next.config.js中声明这个基础路径，否则NextJS的路由系统无法正确识别客户端路由，导致跳转时触发硬刷新。
  添加如下配置：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    basePath: '/next',
    // 保留其他原有配置
  }
  module.exports = nextConfig
  

  注意：所有路由跳转（包括router.push、<Link>组件）都不需要手动拼接/next，NextJS会自动处理路径拼接。

• 修正CloudFront的行为配置
  CloudFront默认不会处理NextJS的客户端路由，需要调整行为确保所有子路径下的非静态资源请求转发到应用入口：

  1. 在CloudFront分发的行为列表中，找到匹配/next/*的行为（没有则新建）。
  2. 设置错误页面：将404状态码指向/next/index.html，并将响应状态码改为200。这样当访问/next/about这类客户端路由时，CloudFront会返回入口文件，由NextJS的路由系统处理跳转。
  3. 调整缓存策略：避免缓存客户端路由页面，防止旧缓存导致的路径匹配错误。可以针对/next/_next/*（静态资源路径）设置缓存，对/next/*的其他路径设置不缓存或短缓存时间。

• 规范router.push的路径格式
  检查代码中router.push的参数，不要手动添加/next前缀：

  • 错误写法：router.push('/next/about')（会生成/next/next/about，导致404触发硬刷新）
  • 正确写法：router.push('/about')（NextJS会自动拼接basePath，生成正确的/next/about）

• 静态导出场景的额外配置
  如果是通过next export导出静态站点部署，需要在next.config.js中开启trailingSlash：

  const nextConfig = {
    basePath: '/next',
    trailingSlash: true,
  }
  

  这会让每个页面生成带斜杠的目录结构，确保CloudFront能正确匹配静态文件路径。

• 清除CloudFront缓存
  修改配置后，必须手动清除CloudFront的缓存，否则旧的缓存内容会继续引发问题。在CloudFront控制台创建无效化请求，路径填写/next/*即可。

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