エラー処理 · Nuxt入門

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

Vueレンダリングライフサイクル中のエラー（SSRとCSR）
サーバーとクライアントの起動エラー（SSR + CSR）
Nitroサーバーライフサイクル中のエラー（server/ ディレクトリ）
JSチャンクのダウンロードエラー

SSR は サーバーサイドレンダリング、CSR は クライアントサイドレンダリング を表します。

Vueエラー

onErrorCaptured を使用してVueエラーをフックできます。

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

エラー報告フレームワークを使用している場合は、vueApp.config.errorHandler を介してグローバルハンドラーを提供できます。処理された場合でも、すべてのVueエラーを受け取ります。

plugins/error-handler.ts

export default defineNuxtPlugin
((nuxtApp
) => {
  nuxtApp
.vueApp
.config
.errorHandler
 = (error
, instance
, info
) => {
    // handle error, e.g. report to a service
  }

  // Also possible
  nuxtApp
.hook
('vue:error', (error
, instance
, info
) => {
    // handle error, e.g. report to a service
  })
})

vue:error フックは、onErrorCaptured ライフサイクルフックに基づいていることに注意してください。

起動エラー

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

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

Nuxtプラグインの実行
app:created および app:beforeMount フックの処理
VueアプリをHTMLにレンダリングする（SSR中）
アプリのマウント（クライアント側）。ただし、この場合は onErrorCaptured または vue:error で処理する必要があります
app:mounted フックの処理

Nitroサーバーエラー

現在、これらのエラーのサーバー側ハンドラーを定義することはできませんが、エラーページをレンダリングできます。エラーページのレンダリングセクションを参照してください。

JSチャンクのエラー

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

この動作を変更するには、experimental.emitRouteChunkError を false（これらのエラーへのフッキングを完全に無効にする）または manual（手動で処理する場合）に設定します。チャンクの読み込みエラーを手動で処理する場合は、自動実装を参考にしてください。

エラーページ

Nuxtが致命的なエラー（サーバーで処理されないエラー、またはクライアントでfatal: trueで作成されたエラー）に遭遇した場合、Accept: application/jsonヘッダーで要求された場合はJSONレスポンスをレンダリングするか、フルスクリーンエラーページをトリガーします。

サーバーライフサイクル中に、以下の場合にエラーが発生する可能性があります。

Nuxtプラグインの処理中
VueアプリをHTMLにレンダリングする際
サーバーAPIルートがエラーをスローした場合

また、クライアント側では、以下の場合に発生する可能性があります。

Nuxtプラグインの処理中
アプリケーションのマウント前（app:beforeMount フック）
onErrorCaptured または vue:error フックでエラーが処理されなかった場合にアプリをマウントする際
Vueアプリがブラウザで初期化およびマウントされた場合（app:mounted）

すべてのNuxtライフサイクルフックをご覧ください。

アプリケーションのソースディレクトリにapp.vueと並んで~/error.vueを追加することで、デフォルトのエラーページをカスタマイズできます。

error.vue

<script setup lang="ts">
import type { NuxtError } from '#app'

const props = defineProps({
  error: Object as () => NuxtError
})

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

<template>
  <div>
    <h2>{{ error.statusCode }}</h2>
    <button @click="handleError">Clear errors</button>
  </div>
</template>

error.vueとその使用方法の詳細をご覧ください。

カスタムエラーの場合、ページ/コンポーネントのsetup関数で呼び出すことができるonErrorCapturedコンポーザブル、またはnuxtプラグインで設定できるvue:errorランタイムnuxtフックを使用することを強くお勧めします。

plugins/error-handler.ts

export default defineNuxtPlugin
(nuxtApp
 => {
  nuxtApp
.hook
('vue:error', (err
) => {
    //
  })
})

エラーページを削除する準備ができたら、clearError ヘルパー関数を呼び出すことができます。この関数は、リダイレクト先のパスをオプションで指定できます（たとえば、「安全な」ページに移動する場合）。

プラグインでエラーが発生した場合、エラーがクリアされるまで再実行されないため、Nuxtプラグインに依存するもの（$routeやuseRouterなど）を使用する前に確認してください。

エラーページのレンダリングは完全に別のページの読み込みであるため、登録されているミドルウェアは再び実行されます。ミドルウェアでuseErrorを使用して、エラーが処理されているかどうかを確認できます。

Node 16で実行していて、エラーページのレンダリング時にCookieを設定すると、以前に設定されたCookieが上書きされます。 Node 16は2023年9月にサポート終了となったため、新しいバージョンのNodeを使用することをお勧めします。

エラーユーティリティ

`useError`

TSシグネチャ

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

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

useErrorコンポーザブルの詳細をご覧ください。

`createError`

TSシグネチャ

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

追加のメタデータを含むエラーオブジェクトを作成します。エラーのmessageとして設定する文字列、またはエラープロパティを含むオブジェクトを渡すことができます。アプリのVue部分とサーバー部分の両方で使用でき、スローすることを意図しています。

createErrorで作成されたエラーをスローした場合

サーバー側では、clearErrorでクリアできるフルスクリーンエラーページがトリガーされます。
クライアント側では、処理するための致命的でないエラーがスローされます。フルスクリーンエラーページをトリガーする必要がある場合は、fatal: trueを設定することで実行できます。

pages/movies/[slug].vue

<script setup lang="ts">
const route
 = useRoute
()
const { data
 } = await useFetch
(`/api/movies/${route
.params
.slug
}`)

if (!data
.value
) {
  throw createError
({
    statusCode
: 404,
    statusMessage
: 'Page Not Found'
  })
}
</script>

createErrorユーティリティの詳細をご覧ください。

`showError`

TSシグネチャ

function showError (err: string | Error | { statusCode, statusMessage }): Error

この関数は、クライアント側の任意の時点、または（サーバー側）ミドルウェア、プラグイン、またはsetup()関数内で直接呼び出すことができます。 clearErrorでクリアできるフルスクリーンエラーページがトリガーされます。

代わりにthrow createError()を使用することをお勧めします。

showErrorユーティリティの詳細をご覧ください。

`clearError`

TSシグネチャ

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

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

clearErrorユーティリティの詳細をご覧ください。

コンポーネントでのエラーのレンダリング

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

このコンポーネントは、デフォルトスロット内で発生するエラーを処理します。クライアント側では、エラーがトップレベルにバブリングするのを防ぎ、代わりに#errorスロットをレンダリングします。

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

別のルートに移動すると、エラーは自動的にクリアされます。

pages/index.vue

<template>
  <!-- some content -->
  <NuxtErrorBoundary @error="someErrorLogger">
    <!-- You use the default slot to render your content -->
    <template #error="{ error, clearError }">
      You can display the error locally here: {{ error }}
      <button @click="clearError">
        This will clear the error.
      </button>
    </template>
  </NuxtErrorBoundary>
</template>

ドキュメント > サンプル > 詳細 > エラー処理でライブサンプルを読んで編集してください。

状態管理

Nuxtは、強力な状態管理ライブラリとuseStateコンポーザブルを提供して、リアクティブでSSRフレンドリーな共有状態を作成します。

サーバー

Nuxtのサーバーフレームワークを使用して、フルスタックアプリケーションを構築します。データベースまたは別のサーバーからデータをフェッチしたり、APIを作成したり、サイトマップやRSSフィードなどの静的サーバーサイドコンテンツを生成したりできます。すべて単一のコードベースからです。