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

這時要靠 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 沒有作用:

想讓 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 為主。
發佈留言