如何防止 Next.js 渲染未定义的路由并正确显示 404 页面-js教程-PHP中文网

如何防止 Next.js 渲染未定义的路由并正确显示 404 页面

Next.js 默认会对未明确声明的嵌套路由（如 /admin/something）回退到最近的父级页面（如 /admin），导致意外渲染。本文详解如何在 App Router 和 Pages Router 中分别配置标准化的 404 页面，彻底拦截非法路径并返回精准的“Not Found”响应。

next.js 默认会对未明确声明的嵌套路由（如 `/admin/something`）回退到最近的父级页面（如 `/admin`），导致意外渲染。本文详解如何在 app router 和 pages router 中分别配置标准化的 404 页面，彻底拦截非法路径并返回精准的“not found”响应。

在 Next.js 中，当访问类似 /admin/something 这样未显式定义的嵌套路由时，框架默认会尝试“降级匹配”——即回退至最接近的已定义路由（如 app/admin/page.tsx），而非返回 404。这种行为虽便于快速开发，但违背 RESTful 路由语义，也影响用户体验与 SEO。解决的关键在于显式声明错误处理机制，且必须严格遵循 Next.js 的文件约定。

✅ App Router 方案：使用 `not-found.js/ts`

App Router 下，Next.js 提供了专用的 not-found 文件机制，它会在任何不匹配的路由路径下自动触发（包括动态段、捕获段及深层嵌套路径），且优先级高于布局和页面组件。

请在 src/app/ 目录下创建 not-found.tsx（推荐 TypeScript）：

'use client'; // 因含交互元素（如 Link），需标记为客户端组件

import Link from 'next/link';

export default function NotFound() {
  return (
    <div classname="flex flex-col items-center justify-center min-h-screen p-4 text-center">
      <h2 classname="text-2xl font-bold text-gray-800">Page Not Found</h2>
      <p classname="mt-2 text-gray-600">The requested URL does not exist.</p>
      <link href="/" classname="mt-4 px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors">
        Return to Home
      
    </div>
  );
}

⚠️ 注意事项：

文件名必须为 not-found.tsx（或 .js），大小写敏感，不可加后缀如 page 或 layout；
放置位置必须是 app/not-found.tsx（根层级），子目录下的 not-found 仅作用于该段路由；
若使用 useRouter 或 Link，需添加 'use client' 指令；
此组件不接收 params 或 searchParams，仅作全局兜底。

✅ Pages Router 方案：使用 `404.js/ts`

Pages Router 则沿用传统约定，在 pages/ 目录下创建 404.tsx 即可：

Feishu calendar sync, local ics to json data for AI agent

将ICS日历文件转为JSON格式，用于飞书日历导入导出及数据集成。

下载

import Link from 'next/link';

export default function Custom404() {
  return (
    <div classname="flex flex-col items-center justify-center min-h-screen p-4">
      <h2>404 — Page Not Found</h2>
      <p>Sorry, we couldn’t find the page you’re looking for.</p>
      <link href="/" passhref legacybehavior>
<a classname="mt-3 text-blue-600 hover:underline">Go back home</a>
      
    </div>
  );
}

⚠️ 注意事项：

文件名必须为 404.tsx，位于 pages/404.tsx；
不支持在 pages/admin/ 等子目录中定义局部 404；它是全站唯一兜底页；
legacyBehavior 和 passHref 在较新版本中可省略（Next.js 13.4+ 默认启用）；
该页面在构建时静态生成，无需服务端逻辑。

? 验证与调试建议

启动开发服务器后，手动访问 /admin/xyz、 /vendor/123/edit 等未定义路径，确认跳转至自定义 404 页面；
检查浏览器 DevTools 的 Network 标签页，状态码应为 404（App Router 在 SSR 下返回 404 状态；Pages Router 默认返回 404，无需额外配置）；
若仍渲染父页面，请检查：
- 是否存在 app/admin/[...slug]/page.tsx 或 app/admin/[id]/page.tsx 等通配动态路由干扰匹配；
- 是否误将 not-found.tsx 放在 app/admin/not-found.tsx（此为局部，无效）；
- Pages Router 中是否遗漏 pages/404.tsx 或命名错误（如 NotFound.tsx）。