紀錄工作經驗、相關知識,解決技術相關問題。

Next

Next.js error.js 用法:錯誤邊界、retry 重試、digest 與 layout 錯誤處理

Next.js error.js 用法:錯誤邊界、retry 重試、digest 與 layout 錯誤處理 特色圖片

Next.js App Router 的 error.js(TypeScript 專案寫成 error.tsx)是路由區段的錯誤畫面:它把同一個區段與底下的巢狀內容包進 React 錯誤邊界(Error Boundary),渲染時丟出錯誤就改顯示這個檔案匯出的元件,錯誤邊界外面的上層 layout 照常顯示。本文以 Next.js 16(範例在 16.4.3 執行)說明 error.js 的寫法、error 與 error.digest 在開發模式和正式環境的差異、retry() 與 reset() 怎麼選、為什麼同一層 layout.js 的錯誤接不到,以及事件處理器裡的錯誤要怎麼處理。

error.js 基本寫法

在路由資料夾放一個 error.tsx,預設匯出一個 React 元件。錯誤邊界必須是 Client Component,所以檔案第一行要加 'use client':

// app/dashboard/error.tsx
'use client' // 錯誤邊界必須是 Client Component

import { useEffect } from 'react'

export default function ErrorPage({
  error,
  retry,
}: {
  error: unknown
  retry: () => void
}) {
  useEffect(() => {
    // 送到錯誤回報服務,這裡先印在瀏覽器 Console
    console.error(error)
  }, [error])

  // error 不一定是 Error 物件,先收斂型別再讀 message 與 digest
  const message = error instanceof Error ? error.message : String(error)
  const digest =
    error instanceof Error ? (error as Error & { digest?: string }).digest : undefined

  return (
    <div role="alert">
      <h2>儀表板載入失敗</h2>
      <p>訊息:{message}</p>
      {digest && <p>錯誤代碼(digest):{digest}</p>}
      <button onClick={() => retry()}>重試</button>
    </div>
  )
}

元件收到的 props:

prop內容
error被丟出的值。Server Component 的錯誤會是 Error 實例;Client Component 丟出什麼就傳什麼,不一定是 Error
retry重新抓取並重新渲染錯誤邊界內的內容,Next.js 16.2.0 以 unstable_retry 加入,16.3.0 轉為穩定
reset清除錯誤狀態並重新渲染,不重新抓取內容,官方建議多數情況用 retry

官方把 error 的型別寫成 unknown,並要求讀 message、digest 之前先用 instanceof Error 之類的方式收斂型別。'use client' 的作用與限制可以參考 Next.js use client 指令用法。

搭配的頁面用一個會失敗的 Server Component 示範:第 1、3、5 次請求丟出錯誤,下一次就成功,模擬資料庫暫時逾時:

// app/dashboard/page.tsx
import { Suspense } from 'react'
import { connection } from 'next/server'

let requestCount = 0

async function Stats() {
  await connection() // 每次請求都在伺服器重新執行
  requestCount++
  // 模擬暫時性錯誤:第 1、3、5… 次請求失敗,下一次就成功
  if (requestCount % 2 === 1) {
    throw new Error(`資料庫連線逾時(第 ${requestCount} 次請求)`)
  }
  return <p>本月訂單:128 筆(第 {requestCount} 次請求)</p>
}

export default function Page() {
  return (
    <main>
      <h1>儀表板</h1>
      <Suspense fallback={<p>載入中…</p>}>
        <Stats />
      </Suspense>
    </main>
  )
}

connection() 讓渲染等到實際收到請求才繼續,Stats 因此不會在建置時預先渲染,每次請求都在伺服器重新執行;外層的 <Suspense> 負責在等待時顯示「載入中…」。

元件不要命名為 Error

官方 error.js 文件的範例把元件命名為 Error。如果照抄這個名稱,又照官方建議寫 error instanceof Error,模組裡的 Error 指的就變成元件函式本身,而不是 JavaScript 內建的 Error,next build 的型別檢查會失敗:

app/tests/nextjs-error-js/dashboard/error.tsx(18,50): error TS2339: Property 'message' does not exist on type '{}'.

把元件改名(例如官方 Error Handling 入門頁用的 ErrorPage)就能通過建置。

error 與 error.digest:開發模式與正式環境不同

同一個錯誤,在開發模式與正式環境傳到瀏覽器的內容不一樣。開發模式(next dev)會把原始錯誤的 message 序列化後傳給用戶端,方便除錯:

Next.js 16.4.3 開發模式:error.tsx 顯示原始錯誤訊息「資料庫連線逾時(第 3 次請求)」與 digest,左下角有 1 Issue 提示

正式環境(next build 後 next start)為了避免洩漏敏感資訊,Server Component 的錯誤不會帶原始訊息。下圖是 Chrome 執行的結果,message 變成 React 壓縮過的錯誤代碼 #441,看不到「資料庫連線逾時」:

Next.js 16.4.3 正式環境:error.tsx 的訊息顯示 Minified React error #441,錯誤代碼 digest 為 3259546862

這時要靠 error.digest。它是 Next.js 自動產生的錯誤雜湊值,同一筆錯誤也會印在伺服器的記錄裡,可以拿畫面上的代碼回頭找完整訊息。上圖對應的 next start 終端輸出(節錄):

⨯ Error: 資料庫連線逾時(第 5 次請求)
    at f (.next\server\chunks\ssr\…) {
  digest: '3259546862'
}

實務上可以把 digest 顯示給使用者或送進錯誤回報服務,客服或工程師就能用這個代碼對應伺服器記錄,錯誤細節不會出現在瀏覽器。

retry 與 reset 的差別

retry() 會重新向伺服器抓取並重新渲染錯誤邊界內的內容,重新渲染成功時,錯誤畫面就被正常內容取代。上面的儀表板範例,在第 3 次請求失敗的畫面按「重試」,送出第 4 次請求後顯示「本月訂單:128 筆(第 4 次請求)」。

reset() 只清除錯誤狀態、重新渲染錯誤邊界的子項,不會重新抓取內容。在後面 Client Component 的範例觀察瀏覽器發出的請求:按 retry() 會多一個帶 ?_rsc= 參數的請求,按 reset() 沒有任何請求。

方法重新向伺服器抓取適合的情境
retry()會資料來源暫時失敗、網路中斷這類可能自己恢復的錯誤,官方建議多數情況用這個
reset()不會有明確理由只想清掉錯誤狀態、用現有內容重新渲染時

如果錯誤畫面本身也處理不了,在渲染 error 元件時再 throw,錯誤就會往更上層的錯誤邊界傳。

error.js 包住哪些檔案:同一層 layout 的錯誤接不到

在元件階層裡,error.js 包住同一個區段的 loading.js、not-found.js、page.js 與更深層的巢狀 layout.js,但不包住同一個區段、位在它上方的 layout.js 與 template.js。錯誤會往上冒泡到最近的上層錯誤邊界,所以 layout 的錯誤要由上一層的 error.js 處理。

用購物車範例確認,資料夾結構如下:

app/shop/
├── error.tsx          ← 上層錯誤邊界
└── cart/
    ├── error.tsx      ← 只包得到 cart 的 page 與更深層內容
    ├── layout.tsx     ← 在這裡丟出錯誤
    └── page.tsx

cart/layout.tsx 讀取購物車數量時失敗:

// app/shop/cart/layout.tsx
import { Suspense } from 'react'
import { connection } from 'next/server'

async function CartBadge(): Promise<React.ReactNode> {
  await connection()
  throw new Error('layout 讀取購物車數量失敗')
}

export default function CartLayout({ children }: { children: React.ReactNode }) {
  return (
    <section>
      <Suspense fallback={<p>購物車數量載入中…</p>}>
        <CartBadge />
      </Suspense>
      {children}
    </section>
  )
}

兩個 error.tsx 只差標題文字:

// app/shop/error.tsx(cart/error.tsx 只把標題改成「shop/cart/error.tsx:購物車發生錯誤」)
'use client'

export default function ShopError({ retry }: { error: unknown; retry: () => void }) {
  return (
    <div role="alert">
      <h2>shop/error.tsx:商店區塊發生錯誤</h2>
      <button onClick={() => retry()}>重試</button>
    </div>
  )
}

開啟 /shop/cart,顯示的是上層 shop/error.tsx,同一層的 cart/error.tsx 沒有作用:

Next.js 16.4.3 正式環境:cart 的 layout 丟出錯誤,畫面顯示上層 shop/error.tsx 的「商店區塊發生錯誤」

想讓 layout 的錯誤只影響局部,可以把容易出錯的部分移到 page 或更深層的區段,或在上一層放 error.js。根 layout 上面沒有其他區段,要用下面的 global-error.js。

錯誤邊界接不到的錯誤:事件處理器與非同步程式碼

錯誤邊界只處理渲染過程中丟出的錯誤。React 文件列出錯誤邊界不會捕捉的情況:事件處理器、伺服器端渲染、錯誤邊界自己丟出的錯誤,以及 setTimeout 這類非同步回呼;例外是 useTransition 回傳的 startTransition,在裡面丟出的錯誤會被錯誤邊界接到。

下面的 Client Component 有兩個按鈕,第一個改 state,下一次渲染時丟出字串;第二個直接在 onClick 裡丟出錯誤:

// app/client/bomb.tsx
'use client'

import { useState } from 'react'

export default function Bomb() {
  const [broken, setBroken] = useState(false)

  if (broken) {
    // 渲染時丟出的值不一定是 Error,這裡故意丟字串
    throw '庫存數量格式錯誤'
  }

  return (
    <div>
      <button onClick={() => setBroken(true)}>在渲染時丟出錯誤</button>
      <button
        onClick={() => {
          // 事件處理器裡的錯誤,錯誤邊界接不到
          throw new Error('事件處理器內的錯誤')
        }}
      >
        在 onClick 裡丟出錯誤
      </button>
    </div>
  )
}

同資料夾的 error.tsx 把收到的值印出來:

// app/client/error.tsx
'use client'

export default function ErrorPage({
  error,
  retry,
  reset,
}: {
  error: unknown
  retry: () => void
  reset: () => void
}) {
  return (
    <div role="alert">
      <h2>元件發生錯誤</h2>
      <p>typeof error:{typeof error}</p>
      <p>error instanceof Error:{String(error instanceof Error)}</p>
      <p>內容:{error instanceof Error ? error.message : String(error)}</p>
      <button onClick={() => retry()}>retry()</button>
      <button onClick={() => reset()}>reset()</button>
    </div>
  )
}

在正式環境依序按兩個按鈕的結果:

  • 按「在 onClick 裡丟出錯誤」:畫面不變,error.tsx 沒有出現,Console 顯示 Uncaught Error: 事件處理器內的錯誤。
  • 按「在渲染時丟出錯誤」:換成 error.tsx 的畫面,顯示 typeof error:string、error instanceof Error:false、內容:庫存數量格式錯誤。Client Component 丟出的值原樣傳給 error,這也是 error 型別要寫成 unknown 的原因。

事件處理器與非同步程式碼的錯誤,官方建議自己 try...catch,把錯誤存進 useState 或 useReducer,再依 state 顯示提示:

'use client'

import { useState } from 'react'

export function SaveButton() {
  const [error, setError] = useState<string | null>(null)

  const handleClick = () => {
    try {
      throw new Error('儲存失敗')
    } catch (reason) {
      setError(reason instanceof Error ? reason.message : String(reason))
    }
  }

  return (
    <div>
      <button type="button" onClick={handleClick}>儲存</button>
      {error && <p role="alert">{error}</p>}
    </div>
  )
}

Client Component 裡 useEffect 清除函式寫錯造成的錯誤,可以參考 React useEffect TypeError: destroy is not a function 報錯分析。不是綁在路由區段、只想包住頁面中某一塊元件時,官方另外提供 next/error 的 catchError 函式建立元件層級的錯誤邊界。

global-error.js:處理根 layout 的錯誤

error.js 接不到同一層 layout 的錯誤,根 layout(app/layout.tsx)上面又沒有其他區段,所以 Next.js 另外提供 global-error.js,放在根 app 目錄:

  • 它在啟用時會取代根 layout 或 template,所以必須自己寫 <html> 與 <body> 標籤,錯誤頁需要的全域樣式、字型也要自己載入。
  • global-error 和內建的 500 頁面都自己渲染整份文件,不包含專案的全域樣式;用 class 或 data-theme 做的深色模式切換不會套用到這裡。
  • 一樣是錯誤邊界,必須是 Client Component,因此不支援 metadata 與 generateMetadata 匯出,頁面標題可以改用 React 的 <title> 元件。
  • props 和 error.js 相同(error、retry)。global-error 在 Next.js 13.1.0 推出,15.2.0 起開發模式也會顯示。

官方形容根 layout 出錯是較少見的情況,日常的錯誤處理仍以各路由區段的 error.js 為主。

參考資料與延伸閱讀

發佈留言