[和訳] Nuxt3 公式サイト~Error Handling
この記事について
この記事はNuxt3 公式サイト Error Handling を和訳したものになります（日本語が不自然になってしまっている箇所があるのはごめんなさい）。
Error Handling
ライフサイクルに応じたエラーキャッチ方法を学びます。
Handling Errors
Nuxt3 はフルスタックフレームワークであり、それはさまざまな文脈で起こりうる、防止できないユーザー実行時エラーの原因がいくつかあることを意味します。
- Vue のレンダリングライフサイクル（SSR + SPA）中のエラー
- API または Nitro サーバのライフサイクル中のエラー
- サーバおよびクライアントの起動エラー（SSR + SPA）
Error During the Vue Rendering Lifecycle (SSR + SPA)
Vue のエラーは onErrorCaptured を使用してフックすることができます。
加えて、Nuxt は vue:error フックを提供し、何らかのエラーがトップレベルまで伝播した際に呼び出せるようになっています。
エラー報告フレームワークを使用している場合、vueApp.config.errorHandler を通じてグローバルハンドラを提供することができます。これは、たとえ処理されたとしても全ての Vue エラーを受け取ります。
Example With Global Error Reporting Framework
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.config.errorHandler = (error, context) => {
// ...
}
})
Server and Client Startup Errors (SSR + SPA)
Nuxt は Nuxt のアプリケーション起動時に何らかのエラーが発生した場合、app:error フックを呼び出します。
これには以下が含まれます。
- Nuxt プラグインの実行
-
app:createとapp:beforeMountフックの処理 - アプリのマウント（クライアント側）
- ただし、この場合は
onCreateCapturedまたはvue:errorで処理する必要があります
- ただし、この場合は
-
app:mountedフックの処理
Errors During API or Nitro Server Lifecycle
現在、これらのエラーに対するサーバーサイドの処理を定義できませんが、エラーページをレンダリングすることは可能です（次のセクションを参照してください）。
Rendering an Error Page
Nuxt が致命的なエラーに遭遇した場合、サーバーのライフサイクル中であれ、Vue アプリケーション（SSR と SPA の両方）のレンダリング中であれ、JSON レスポンス（Accept:application/json ヘッダーでリクエストした場合）または HTML のエラーページのいずれかをレンダリングします。
このエラーページはアプリケーションのソースディレクトリにapp.vue と一緒に ~/error.vue を加えることでカスタマイズできます。このページはあなたが処理するエラーを含む単一のプロパティ error を持っています。
エラーページを削除する準備ができたら、オプションでリダイレクト先（例えば「安全」なページに移動させたい、など）のパスを受け取る clearError ヘルパー関数呼ぶことができます。
Example
<template>
<button @click="handleError">Clear errors</button>
</template>
<script setup>
const props = defineProps({
error: Object
})
const handleError = () => clearError({ redirect: '/' })
</script>
Error Helper Methods
useError
function useError(): Ref<Error | { url, statusCode, statusMessage, message, description, data }>
この関数は処理中のグローバルな Nuxt エラーを返します。
詳細は下記ページを参照してください。
createError
function createError (err: { cause, data, message, name, stack, statusCode, statusMessage, fatal }): Error
メタデータを持つエラーオブジェクトを作成するためにこの関数を使うことができます。アプリの Vue と Nitro の両方で使用でき、スローされることを意味しています。
createError で作成したエラーを投げるケース
- サーバーサイドで、
clearErrorで削除できるフルスクリーンのエラーページをトリガーするとき。 - クライアントサイドで、自分で処理する必要のある致命的ではないエラーを投げるとき。フルスクリーンエラーページを表示させたいときは、
fatal: trueを設定すれば可能です。
Example
<script setup>
const route = useRoute()
const { data } = await useFetch(`/api/movies/${route.params.slug}`)
if (!data.value) {
throw createError({ statusCode: 404, statusMessage: 'Page Not Found' })
}
</script>
showError
function showError (err: string | Error | {statusCode, statusMessage}): Error
この関数はクライアントサイドの任意の場所で呼ぶことができますし、（サーバーサイドでは）ミドルウェア、プラグイン、setup() 関数の中で直接呼ぶこともできます。この関数は clearError で削除できるフルスクリーンのエラーページをトリガーします。
代わりに throw createError() を使用することが推奨されます。
詳細は下記ページを参照してください。
clearError
function clearError (options?: { redirect?: string }): Promise<void>
この関数は現在処理されている Nuxt のエラーを削除します。また、オプションでリダイレクト先のパス（例えば「安全」なページに移動させたい、など）を受け取ります。
詳細は下記ページを参照してください。
Rendering Errors Within Your App
また、Nuxt はサイト全体をエラーページで置き換えることなくクライアントサイドのエラーをアプリ内で処理できる <NuxtEErrorBoundary> コンポーネントを提供します。
このコンポーネントはデフォルトのスロット内で起きたエラーを処理する責任があります。クライアントサイドでは、エラーがトップレベルまで伝播するのを防ぎ、代わりに #error スロットをレンダリングします。
#error スロットは error をプロパティとして受け取ります（error = null とした場合、デフォルトのスロットを再レンダリングすることになります。エラーが完全に解消していないと、エラースロットが2回レンダリングされるだけです）。
別のルートに移動すると、エラーは自動的に解消されます。
Example
<template>
<!-- 何らかのコンテンツ -->
<NuxtErrorBoundary @error="someErrorLogger">
<!-- コンテンツをレンダリングするために、デフォルトスロットを使用します -->
<template #error="{ error }">
You can display the error locally here.
<button @click="error = null">
This will clear the error.
</button>
</template>
</NuxtErrorBoundary>
</template>
下記ページで実際の例を見たり編集したりできます。
Discussion