Next.js 13自定义not-found.tsx部署至Vercel后无法生效求助

排查与修复步骤 #

• 确认文件路径与命名
  确保not-found.tsx（或.js）严格放置在app/根目录下，不能嵌套在子文件夹中。Next.js 13 App Router的全局404页面必须遵循app/not-found.tsx的路径规则，子路由自定义404才需要放在对应子目录。

• 升级Next.js版本
  你当前使用的13.4.8版本存在Vercel部署的兼容性问题，建议升级到13.4.10及以上的稳定版本（如13.4.19）。旧版本在Vercel的Edge Runtime环境中，自定义404页面的渲染逻辑可能出现异常。

• 检查Vercel配置文件
  若项目根目录存在vercel.json，确认其中没有覆盖默认错误页面的路由规则。避免出现拦截404请求的配置，比如：

  {
    "routes": [
      // 这类规则会覆盖Next.js的404处理逻辑，需删除
      { "src": "/.*", "dest": "/index.html" }
    ]
  }
  

  若无vercel.json，无需额外创建，Vercel会默认遵循Next.js App Router的规则。

• 清除缓存重新部署
  在Vercel控制台触发重新部署，并勾选「清除构建缓存」选项。旧缓存可能导致新的not-found.tsx未被正确打包部署。

• 验证组件导出方式
  确保not-found.tsx使用默认导出的React组件，示例正确写法：

  export default function NotFound() {
    return (
      <div>
        <h1>自定义404页面</h1>
        <p>你访问的页面不存在</p>
      </div>
    );
  }
  

• 调整Runtime配置
  若项目全局启用了Edge Runtime（如在layout.tsx中设置export const runtime = 'edge'），可尝试在not-found.tsx中显式指定Node.js Runtime：

  export const runtime = 'nodejs';
  

  部分Edge Runtime场景下，自定义404页面会回退到默认提示。

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