error.js

error 檔案可讓您處理非預期的執行階段錯誤，並顯示備用 UI。

app/dashboard/error.tsx

'use client' // Error boundaries must be Client Components
 
import { useEffect } from 'react'
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Log the error to an error reporting service
    console.error(error)
  }, [error])
 
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // Attempt to recover by trying to re-render the segment
          () => reset()
        }
      >
        Try again
      </button>
    </div>
  )
}

error.js 將路由區段及其巢狀子元件包裝在 React Error Boundary 中。當邊界內拋出錯誤時，error 元件會顯示為備用 UI。

要知道:

React DevTools 可讓您切換錯誤邊界以測試錯誤狀態。

如果您希望錯誤向上冒泡到父錯誤邊界，您可以在渲染 error 元件時 throw。

參考

Props

`error`

傳遞至 error.js 用戶端元件的 Error 物件的實例。

要知道： 在開發期間，傳遞至用戶端的 Error 物件將會被序列化，並包含原始錯誤的 message，以便於除錯。但是，在生產環境中，此行為有所不同，以避免將錯誤中可能包含的敏感詳細資訊洩漏給用戶端。

`error.message`

從用戶端元件轉發的錯誤會顯示原始的 Error 訊息。
從伺服器元件轉發的錯誤會顯示帶有識別碼的通用訊息。這是為了防止洩漏敏感詳細資訊。您可以使用 errors.digest 下的識別碼來比對對應的伺服器端日誌。

`error.digest`

拋出的錯誤自動產生的雜湊值。它可用於比對伺服器端日誌中的對應錯誤。

`reset`

錯誤的原因有時可能是暫時性的。在這些情況下，再次嘗試可能會解決問題。

錯誤元件可以使用 reset() 函式提示使用者嘗試從錯誤中恢復。執行時，該函式將嘗試重新渲染錯誤邊界的內容。如果成功，備用錯誤元件將被重新渲染的結果取代。

app/dashboard/error.tsx

'use client' // Error boundaries must be Client Components
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

範例

全域錯誤

雖然較不常見，但您可以使用位於根應用程式目錄中的 global-error.js 來處理根版面配置或樣板中的錯誤，即使在使用國際化時也是如此。全域錯誤 UI 必須定義自己的 <html> 和 <body> 標籤。此檔案在啟用時會取代根版面配置或樣板。

app/global-error.tsx

'use client' // Error boundaries must be Client Components
 
export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    // global-error must include html and body tags
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

要知道： global-error.js 始終顯示。在開發中，將會顯示錯誤覆蓋層。

版本歷史

版本	變更
`v15.2.0`	在開發中也顯示 `global-error`。
`v13.1.0`	引入 `global-error`。
`v13.0.0`	引入 `error`。