Next.js升级至11.1.2版本后首页跳转404其他路由正常如何解决

排查定位步骤 #

• 检查pages目录首页文件有效性：确认pages/index.js（或.jsx/.tsx）文件是否存在，文件名拼写、大小写是否完全符合规范，排查升级过程中文件是否被意外删除、移动或重命名
• 核对next.config.js配置规则：检查是否配置了basePath、redirects、rewrites配置项，是否存在匹配根路径/的重定向/重写规则，Next.js 11.1.2对rewrites规则的优先级处理做了调整，可能会触发之前未生效的旧规则
• 排查public目录静态文件冲突：确认public目录下是否存在index.html文件，Next.js 11+版本会优先响应public目录下的静态资源，若存在该文件且内容异常，会直接覆盖pages目录下的首页路由返回404
• 校验自定义App的渲染逻辑：即使_app.js没有配置拦截规则，也需要检查_app.js的getInitialProps、首页文件的getServerSideProps/getStaticProps方法中是否存在根路径相关的权限校验、跳转逻辑，版本升级后API返回值变化可能导致原有逻辑误判触发404
• 清除缓存复现问题：执行rm -rf .next node_modules package-lock.json yarn.lock命令清除构建缓存和依赖文件，重新安装依赖后启动项目，排除旧版本构建缓存、多版本依赖冲突导致的路由异常

常见问题解决方案 #

• 若为rewrites/redirects规则冲突：调整规则优先级，将根路径相关的规则放到规则列表末尾，或者明确排除根路径，参考配置调整如下：

// next.config.js
module.exports = {
  async rewrites() {
    return [
      // 其他子路由规则放在前面
      {
        source: '/:path*',
        destination: '/api/:path*',
        // 新增规则排除根路径匹配
        missing: [{ type: 'path', key: 'path', value: '' }]
      }
    ]
  }
}

• 若为public目录静态文件冲突：删除或重命名public目录下的index.html文件，首页静态内容统一放在pages/index.js中处理
• 若为依赖版本冲突：在package.json中固定next版本为11.1.2，清除缓存后重新安装依赖，避免多个next版本共存导致的路由解析异常

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