錯誤處理

錯誤可以分為兩類：預期錯誤和未攔截的例外

將預期錯誤作為返回值建模：避免在伺服器動作中使用 try/catch 處理預期錯誤。使用 useFormState 管理這些錯誤並將其返回給客戶端。
使用錯誤邊界處理非預期錯誤：使用 error.tsx 和 global-error.tsx 檔案實作錯誤邊界，以處理非預期錯誤並提供後備 UI。

處理預期錯誤

預期錯誤是指在應用程式正常運行期間可能發生的錯誤，例如來自伺服器端表單驗證或請求失敗的錯誤。這些錯誤應明確處理並返回給客戶端。

從伺服器動作處理預期錯誤

使用 useFormState hook 來管理伺服器動作的狀態，包括處理錯誤。這種方法避免了針對預期錯誤使用 try/catch 區塊，這些錯誤應該建模為返回值而不是拋出異常。

app/actions.ts

'use server'
 
import { redirect } from 'next/navigation'
 
export async function createUser(prevState: any, formData: FormData) {
  const res = await fetch('https://...')
  const json = await res.json()
 
  if (!res.ok) {
    return { message: 'Please enter a valid email' }
  }
 
  redirect('/dashboard')
}

然後，您可以將您的動作傳遞給 useFormState hook，並使用返回的 state 顯示錯誤訊息。

app/ui/signup.tsx

'use client'
 
import { useFormState } from 'react'
import { createUser } from '@/app/actions'
 
const initialState = {
  message: '',
}
 
export function Signup() {
  const [state, formAction] = useFormState(createUser, initialState)
 
  return (
    <form action={formAction}>
      <label htmlFor="email">Email</label>
      <input type="text" id="email" name="email" required />
      {/* ... */}
      <p aria-live="polite">{state?.message}</p>
      <button>Sign up</button>
    </form>
  )
}

注意事項：這些範例使用 React 的 useFormState hook，它與 Next.js App Router 捆綁在一起。如果您使用的是 React 19，請改用 useActionState。詳情請參閱React 文件。

您也可以使用返回的狀態從客戶端組件顯示 toast 訊息。

從伺服器組件處理預期錯誤

在伺服器組件內擷取資料時，您可以使用回應來有條件地呈現錯誤訊息或重新導向。

app/page.tsx

export default async function Page() {
  const res = await fetch(`https://...`)
  const data = await res.json()
 
  if (!res.ok) {
    return 'There was an error.'
  }
 
  return '...'
}

未捕捉的例外狀況

未捕捉的例外狀況是指在應用程式正常流程中不應發生的錯誤或問題。這些錯誤應透過拋出錯誤來處理，然後由錯誤邊界捕捉。

常見：使用 error.js 處理根佈局下的未捕捉錯誤。
選用：使用巢狀的 error.js 檔案（例如 app/dashboard/error.js）處理細粒度的未捕捉錯誤。
不常見：使用 global-error.js 處理根佈局中的未捕捉錯誤。

使用錯誤邊界

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 組件時使用 throw。

處理巢狀路由中的錯誤的不同層級放置 `error.tsx` 檔案來進行細粒度的錯誤處理。

處理全域錯誤功能時也是如此。全域錯誤 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>
  )
}

後續步驟

error.js

error.js 特殊檔案的 API 參考。

這有幫助嗎？