NNext.js 中文网 GitHub

自定义错误

覆盖并扩展内置的错误页面以处理自定义错误。

404 页面#

404 页面可能会被频繁访问。对每次访问都在服务端渲染错误页面会增加 Next.js 服务器的负载,从而导致成本增加和体验变慢。

为避免上述陷阱,Next.js 默认提供一个静态的 404 页面,无需添加任何额外文件。

小知识:默认的 404 和 500 页面通过 prefers-color-scheme 遵循操作系统的配色方案,不会读取应用级别的主题。由于 pages/404.js 和 pages/500.js 在你的自定义 App 内渲染,因此提供你自己的文件可让全局样式和主题生效。

自定义 404 页面#

要创建自定义 404 页面,可以创建 pages/404.js 文件。该文件在构建时静态生成。

pages/404.js
export default function Custom404() {
  return <h1>404 - Page Not Found</h1>
}

小知识:如果你需要在构建时获取数据,可以在此页面中使用 getStaticProps。

500 页面#

对每次访问都在服务端渲染错误页面会增加错误响应的复杂性。为了帮助用户尽快获得错误响应,Next.js 默认提供一个静态的 500 页面,无需添加任何额外文件。

自定义 500 页面#

要自定义 500 页面,可以创建 pages/500.js 文件。该文件在构建时静态生成。

pages/500.js
export default function Custom500() {
  return <h1>500 - Server-side error occurred</h1>
}

小知识:如果你需要在构建时获取数据,可以在此页面中使用 getStaticProps。

更高级的错误页面自定义#

500 错误由 Error 组件在客户端和服务端同时处理。如果你希望覆盖它,请定义 pages/_error.js 文件并添加以下代码:

jsx
function Error({ statusCode }) {
  return (
    <p>
      {statusCode
        ? `An error ${statusCode} occurred on server`
        : 'An error occurred on client'}
    </p>
  )
}

Error.getInitialProps = ({ res, err }) => {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404
  return { statusCode }
}

export default Error

pages/_error.js 仅在生产环境中使用。在开发环境中,你会看到一个包含调用堆栈的错误,以了解错误的来源。

复用内置错误页面#

如果你想渲染内置错误页面,可以通过导入 Error 组件来实现:

jsx
import Error from 'next/error'

export async function getServerSideProps() {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const errorCode = res.ok ? false : res.status
  const json = await res.json()

  return {
    props: { errorCode, stars: json.stargazers_count },
  }
}

export default function Page({ errorCode, stars }) {
  if (errorCode) {
    return <Error statusCode={errorCode} />
  }

  return <div>Next stars: {stars}</div>
}

Error 组件也接受 title 属性,如果你想在 statusCode 之外传递文本消息。

如果你有自定义的 Error 组件,请务必改为导入该组件。next/error 导出的是 Next.js 使用的默认组件。

注意事项#

Next.js 中文网