error.js

error 檔案定義了路由區段的錯誤 UI 邊界。

它對於捕獲發生在伺服器元件 (Server Components) 和客戶端元件 (Client Components) 中的意外錯誤並顯示備用 UI 非常有用。

'use client' // 錯誤元件必須是客戶端元件

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // 將錯誤記錄到錯誤報告服務
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // 嘗試通過重新渲染區段來恢復
          () => reset()
        }
      >
        Try again
      </button>
    </div>
  )
}

Props

`error`

一個 Error 物件的實例，轉發到 error.js 客戶端元件。

`error.message`

錯誤訊息。

對於從客戶端元件轉發的錯誤，這將是原始錯誤的訊息。
對於從伺服器元件轉發的錯誤，這將是一個通用錯誤訊息，以避免洩露敏感細節。可以使用 errors.digest 來匹配伺服器端日誌中的相應錯誤。

`error.digest`

在伺服器元件中拋出的錯誤的自動生成雜湊值。可用於匹配伺服器端日誌中的相應錯誤。

`reset`

一個用於重置錯誤邊界的函數。執行時，該函數將嘗試重新渲染錯誤邊界的內容。如果成功，備用錯誤元件將被重新渲染的結果替換。

可用於提示用戶嘗試從錯誤中恢復。

須知:

error.js 邊界必須是**客戶端元件**。

在正式環境建置中，從伺服器元件轉發的錯誤將被剝離特定錯誤細節，以避免洩露敏感資訊。

error.js 邊界不會處理在同一區段的 layout.js 元件中拋出的錯誤，因為錯誤邊界嵌套在該布局元件內部。

要處理特定布局的錯誤，請在布局的父區段中放置一個 error.js 檔案。

要處理根布局或模板內的錯誤，請使用 error.js 的變體 app/global-error.js。

`global-error.js`

要專門處理根 layout.js 中的錯誤，請使用位於根 app 目錄中的 error.js 變體 app/global-error.js。

'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

須知:

global-error.js 在激活時會替換根 layout.js，因此必須定義自己的 <html> 和 <body> 標籤。

在設計錯誤 UI 時，您可能會發現使用 React Developer Tools 手動切換錯誤邊界很有幫助。

not-found.js

not-found 檔案用於在路由區段中拋出 notFound() 函數時渲染 UI。

版本歷史

版本	變更
`v13.1.0`	引入 `global-error`。
`v13.0.0`	引入 `error`。

On this page