エラー処理

異なるライフサイクルでエラーをキャッチする方法を学びましょう。

エラー処理

Nuxt3はフルスタックのフレームワークです。そのため、さまざまなコンテキストで発生するユーザーのランタイムエラーは、防止できないソースから発生する可能性があります。

• Vueのレンダリングライフサイクル中のエラー（SSR + SPA）
• APIやNitroサーバーのライフサイクル中のエラー
• サーバーおよびクライアントの起動エラー（SSR + SPA）
• JSチャンク(データの細分化)のダウンロードエラー

Vueのレンダリングライフサイクル中のエラー（SSR + SPA）

onErrorCapturedを使用してVueのエラーにフックすることができます。

さらに、Nuxtはvue:errorフックも提供しており、エラーがトップレベルまで伝播した場合に呼び出されます。

エラーレポートフレームワークを使用している場合は、vueApp.config.errorHandlerを介してグローバルなハンドラを提供することができます。これにより、処理されているエラーも含めて、すべてのVueのエラーを受け取ることができます。

グローバルエラーリポートフレームワークの事例

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.config.errorHandler = (error, context) => {
    // ...
  };
});

サーバーとクライアントセットアップエラー (SSR + SPA)

Nuxtアプリケーションの起動中にエラーが発生した場合、Nuxtはapp:errorフックを呼び出します。

これには以下が含まれます。:

• Nuxtプラグインの実行
• app:createdとapp:beforeMountフックの処理
• VueアプリケーションをHTMLにレンダリングする（サーバーサイド）
• アプリケーションのマウント（クライアントサイド）。ただし、このケースはonErrorCapturedまたはvue:errorで処理する必要があります。
• app:mountedフックの処理

APIまたはNitroサーバーライフサイクル中のエラー

これらのエラーに対しては、現在サーバーサイドのハンドラを定義することはできませんが、エラーページをレンダリングすることは可能です（次のセクションを参照）。

JavaScriptのダウンロードエラー

ネットワーク接続障害または新しいデプロイメント (古いハッシュ化された JS チャンク URL が無効になる) が原因で、チャンク読み込みエラーが発生する可能性があります。 Nuxt は、ルート ナビゲーション中にチャンクのロードに失敗した場合にハード リロードを実行することにより、チャンクのロード エラーを処理するための組み込みサポートを提供します。

この動作を変更するには、experimental.emitRouteChunkErrorをfalseに設定する（これにより、これらのエラーにフックが行われなくなる）か、manualに設定することで自分自身で処理できます。チャンクの読み込みエラーを手動で処理する場合は、自動的な実装を参考にすることができます。

エラーページのレンダリング

Nuxtが致命的なエラーに遭遇した場合、サーバーライフサイクル中またはVueアプリケーションのレンダリング中（SSRおよびSPAの両方）、JSONレスポンス（Accept: application/jsonヘッダーでリクエストされた場合）またはHTMLのエラーページをレンダリングします。

エラーページをカスタマイズするには、アプリケーションのソースディレクトリにapp.vueと同じ階層に~/error.vueを追加します。このページは単一のプロパティerrorを持ち、ハンドリングするためのエラーオブジェクトが含まれています。

事例

<template>
  <button @click="handleError">Clear errors</button>
</template>

<script setup>
  const props = defineProps({
    error: Object,
  });

  const handleError = () => clearError({ redirect: "/" });
</script>

エラーの補助メソッド

useError

function useError (): Ref<Error | { url, statusCode, statusMessage, message, description, data }>

この関数は、処理されているグローバルな Nuxt エラーを返します。

Info 詳細は「Docs > API > Composables > Use Error」を参照してください。

createError

function createError (err: { cause, data, message, name, stack, statusCode, statusMessage, fatal }): Error

この関数を使用して、追加のメタデータを持つエラーオブジェクトを作成できます。これは、Vue ポーションと Nitro ポーションの両方で使用でき、スローするために意図されています。

もし、createErrorで作成されたエラーをスローする場合：

• サーバーサイドでは、フルスクリーンのエラーページが表示され、clearErrorでクリアすることができます。
• クライアントサイドでは、ハンドルするために非致命的なエラーがスローされます。フルスクリーンのエラーページをトリガーする必要がある場合は、fatal:trueを設定することもできます。

事例

<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() を使用することをおすすめします。

Info 詳細は「Docs > API > Utils > Show Error」を参照してください。

clearError

function clearError (options?: { redirect?: string }): Promise<void>

この関数は現在処理中の Nuxt エラーをクリアします。オプションでリダイレクト先のパスを指定することもできます（例えば、'安全な' ページに移動する場合など）。

Info 詳細は「Docs > API > Utils > Clear Error」を参照してください。

アプリ内でエラーをレンダリング

Nuxtは、<NuxtErrorBoundary>コンポーネントも提供しており、これを使用すると、エラーページ全体を置き換えることなく、アプリ内でクライアントサイドのエラーを処理できます。

このコンポーネントは、デフォルトのスロット内で発生するエラーを処理する責任があります。クライアントサイドでは、エラーをトップレベルに伝播させず、代わりに #errorスロットをレンダリングします。

#errorスロットは、エラーをプロップとして受け取ります（error = nullに設定するとデフォルトのスロットを再レンダリングします。ただし、エラーが完全に解決されていない場合、エラースロットは2回レンダリングされる可能性があるため、最初にエラーが完全に解決されていることを確認する必要があります）。

Example

<template>
  <!-- some content -->
  <NuxtErrorBoundary @error="someErrorLogger">
    <!-- デフォルトのスロットを使用してコンテンツをレンダリングする -->
    <template #error="{ error, clearError }">
      You can display the error locally here: {{ error }}
      <button @click="clearError">This will clear the error.</button>
    </template>
  </NuxtErrorBoundary>
</template>

Info 詳細と事例は「Docs > Examples > Advanced > Error Handling」から確認することができます。