编辑“︁Next.js 404 页面处理”︁

{{DISPLAYTITLE:Next.js 404 页面处理}}

== 介绍 ==  
'''Next.js 404 页面处理'''是路由系统的重要组成部分，用于在用户访问不存在的路径时提供友好的错误提示。Next.js 提供了两种方式实现 404 页面：  
* 默认的静态 404 页面（自动生效）  
* 自定义动态 404 页面（通过代码逻辑控制）  

本文将详细讲解这两种方法的实现原理、适用场景及最佳实践。

== 默认 404 页面 ==  
Next.js 默认在 `pages/404.js` 或 `pages/404.tsx` 位置提供静态 404 页面。如果该文件存在，框架会自动将其作为未匹配路由的兜底页面。

=== 基础示例 ===  
<syntaxhighlight lang="javascript">  
// pages/404.js  
export default function Custom404() {  
  return <h1>404 - Page Not Found</h1>;  
}  
</syntaxhighlight>  

'''输出效果'''：  
当访问 `http://localhost:3000/non-existent-route` 时，自动渲染上述组件。

== 动态 404 处理 ==  
对于需要编程控制的场景（如基于 API 数据动态显示错误信息），可通过以下方式实现：

=== 方法 1：`getStaticProps`/`getServerSideProps` ===  
<syntaxhighlight lang="javascript">  
// pages/404.js  
export async function getStaticProps() {  
  return {  
    props: {  
      errorData: { message: "Additional debug info" }  
    }  
  };  
}  

export default function Dynamic404({ errorData }) {  
  return (  
    <div>  
      <h1>404</h1>  
      <p>{errorData.message}</p>  
    </div>  
  );  
}  
</syntaxhighlight>  

=== 方法 2：路由钩子（高级用法） ===  
在 `pages/_app.js` 中通过 `router` 对象检测 404：  
<syntaxhighlight lang="javascript">  
import { useRouter } from 'next/router';  

function MyApp({ Component, pageProps }) {  
  const router = useRouter();  

  if (router.isFallback) {  
    return <div>Loading...</div>;  
  }  

  // 手动检查路径有效性  
  if (pageProps.statusCode === 404) {  
    return <Custom404 />;  
  }  

  return <Component {...pageProps} />;  
}  
</syntaxhighlight>  

== 实际应用场景 ==  
=== 案例 1：多语言 404 页面 ===  
结合 Next.js 国际化路由，根据语言显示不同错误信息：  
<syntaxhighlight lang="javascript">  
// pages/404.js  
import { useRouter } from 'next/router';  

const messages = {  
  en: { title: "Not Found", description: "..." },  
  ja: { title: "ページが見つかりません", description: "..." }  
};  

export default function Locale404() {  
  const { locale } = useRouter();  
  return (  
    <div>  
      <h1>{messages[locale].title}</h1>  
      <p>{messages[locale].description}</p>  
    </div>  
  );  
}  
</syntaxhighlight>  

=== 案例 2：SSR 动态检测 ===  
在服务端渲染时验证路由有效性：  
<syntaxhighlight lang="javascript">  
// pages/[slug].js  
export async function getServerSideProps({ params }) {  
  const res = await fetch(`https://api.example.com/validate/${params.slug}`);  
  if (res.status === 404) {  
    return { props: { notFound: true } }; // 触发 404 页面  
  }  
  // ...正常数据处理  
}  
</syntaxhighlight>  

== 技术原理 ==  
Next.js 404 处理流程可通过以下 Mermaid 图表示：  
<mermaid>  
graph TD  
    A[请求路由] --> B{路由是否存在?}  
    B -->|是| C[渲染对应页面]  
    B -->|否| D[检查 pages/404.js]  
    D --> E{文件存在?}  
    E -->|是| F[渲染404组件]  
    E -->|否| G[显示默认错误页]  
</mermaid>  

== 数学表达（可选） ==  
在动态路由匹配中，404 状态可表示为：  
<math>  
\text{HTTP Status} = \begin{cases}  
200 & \text{if } \exists p \in P \mid p \sim r \\  
404 & \text{otherwise}  
\end{cases}  
</math>  
其中：  
* <math>P</math> 为所有已定义路由的集合  
* <math>r</math> 为当前请求路径  
* <math>\sim</math> 表示路径匹配关系  

== 最佳实践 ==  
1. '''静态优先'''：若无动态需求，优先使用 `pages/404.js`  
2. '''性能优化'''：动态 404 页面应避免阻塞渲染  
3. '''SEO 友好'''：确保返回正确的 HTTP 状态码  
4. '''用户体验'''：提供返回首页或搜索建议的链接  

== 常见问题 ==  
=== Q1: 如何测试 404 页面？ ===  
* 开发环境：直接访问无效路径  
* 生产环境：使用 `next build && next start` 模拟  

=== Q2: 为什么自定义 404 页面不生效？ ===  
检查：  
1. 文件是否位于 `pages` 目录  
2. 是否命名为 `404.js`/`404.tsx`  
3. 是否被其他中间件拦截  

== 扩展阅读 ==  
* [[Next.js 官方文档 - 错误页面|https://nextjs.org/docs/advanced-features/custom-error-page]]  
* [[HTTP 状态码规范|https://tools.ietf.org/html/rfc7231#section-6.5.4]]  

{{Next.js Learning Path Navbox}}

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js路由系统]]