フロントエンドエンジニアのこん(@k0n_karin)です！今回はNuxt3でSentryを扱ったときに遭遇した事象について投稿します。
※NuxtとSentryそのものの説明は割愛します。
※本記事執筆時点のバージョンは以下のとおりです。
- nuxt: 3.12.2
- @sentry/vue: 8.13.0
解決策
先に解決策です。事象の解説も見たい方は次の章以降を参考にしてください。
Nuxt3で@sentry/vueを使う際、エラー発生時に500エラーの画面を表示したくない場合は、Sentry.init()の前にapp.config.errorHandlerに任意の関数を代入しましょう。
（エラーハンドリングが不要ならundefinedでも可）
// plugins/sentry.ts import * as Sentry from '@sentry/vue' export default defineNuxtPlugin((nuxtApp) => { nuxtApp.vueApp.config.errorHandler = (error) => { // 必要に応じてここでエラーハンドリングする } Sentry.init({ app: nuxtApp.vueApp, dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0' }) })
Nuxt3とSentry
本ブログの執筆時点（2024-07-10）では、Nuxt3用のSentry SDKはまだありません。絶賛開発中のようです。
代わりに、Vue向けのSentry SDK（@sentry/vue）を使うことができます。使い方はNuxtチームの方のブログがとても参考になります。
Nuxt3で@sentry/vueを使うとエラー発生時に500エラーが表示される
しかし、上記のブログのようにNuxtのプラグインで@sentry/vueを使うと、クライアントでエラー発生時にSentryにエラー通知されますが、同時に500エラー画面も表示されます😭
これは以下のデモ用リポジトリから確認できます。
この500エラーが表示される仕組みを説明するために、前提となる4つの知識をそれぞれ解説していきます。
前提知識1：Vueのapp.config.errorHandler
Vueのapp.config.errorHandlerは1つのVueアプリケーションにつき1つの関数を登録できます。複数の関数は登録できません。
app.config.errorHandlerはアプリケーションでハンドリングされなかった全てのエラーをハンドリングできます。
app.config.errorHandler = (err, instance, info) => { // エラー処理（例 サービスに報告） }
前提知識2：@sentry/vueのapp.config.errorHandlerの使い方
@sentry/vueは、エラー発生時にあらかじめ指定されたDSNにエラーの内容を送る関数をapp.config.errorHandlerに代入します。
ただし、前提知識1の通り、1つのVueアプリケーションにつき1つの関数しか登録できません。
そのため、@sentry/vueが提供する関数は、もともと定義されていたapp.config.errorHandlerの関数を保持し、@sentry/vueの関数内でその関数も実行してくれます。
const { errorHandler, warnHandler, silent } = app.config; app.config.errorHandler = (error: Error, vm: ViewModel, lifecycleHook: string): void => { // 省略 if (typeof errorHandler === 'function') { (errorHandler as UnknownFunc).call(app, error, vm, lifecycleHook); } }
前提知識3：Nuxtのapp.config.errorHandlerの使い方
Nuxtはapp.config.errorHandlerを以下のように使います。
- Nuxtの初期化の最中だけ
app.config.errorHandlerに関数を渡す。 - Nuxtプラグインで
app.config.errorHandlerが上書きされたら、以降エラー発生時に上書きされた関数を使う。（＝リセットしない） - Nuxtプラグインで
app.config.errorHandlerが上書きされなかったら、app.config.errorHandlerをundefinedにする。（＝リセットする）
実際のコードを見てみましょう。
vueApp.config.errorHandler = handleVueError // 省略 // If the errorHandler is not overridden by the user, we unset it if (vueApp.config.errorHandler === handleVueError) { vueApp.config.errorHandler = undefined }
このように、Nuxtの初期化中にapp.config.errorHandlerがhandleVueErrorのままだったら、app.config.errorHandlerはundefinedになります。
前提知識4：Nuxtの初期化中のエラーハンドラーの副作用
最後に、前提知識3のコードで登場したhandleVueError関数が何をしているか見ましょう。
async function handleVueError (error: any) { await nuxt.callHook('app:error', error) nuxt.payload.error = nuxt.payload.error || createError(error as any) }
重要なのはnuxt.payload.error = nuxt.payload.error || createError(error as any)です。
createErrorはエラーオブジェクトを生成するNuxtのユーティリティ関数です。
ではnuxt.payload.errorが何なのかというと、これはuseErrorというNuxtのcomposables関数で参照されます。
export const useError = () => toRef(useNuxtApp().payload, 'error')
useNuxtApp().payloadがnuxt.payloadに当たります。
さらに、useErrorはNuxtのルートコンポーネントで参照されています。
useErrorの返り値はRefなので、これで<ErrorComponent>をリアクティブに出し分けています。
<template> <!-- 省略 --> <ErrorComponent v-else-if="error" :error="error" /> <!-- 省略 --> </template> <script setup lang="ts"> // 省略 // error handling const error = useError() </script>
- https://github.com/nuxt/nuxt/blob/72a94881b6cdf39a14db2ad14bdf695368205596/packages/nuxt/src/app/components/nuxt-root.vue#L4-L7
- https://github.com/nuxt/nuxt/blob/72a94881b6cdf39a14db2ad14bdf695368205596/packages/nuxt/src/app/components/nuxt-root.vue#L56
つまり、Nuxtの初期化中のエラーハンドラーのhandlerVueErrorは、<ErrorComponent>を表示する副作用を持っています。
<ErrorComponent>が500エラーの正体のようですね。
500エラーが表示される事象に立ち向かう
では前提知識とともに、この事象を整理します。
まず、前提知識1のとおり、Vueではapp.config.errorHandlerは1つの関数しか代入できません。
また、前提知識2・3により、Nuxtプラグインで@sentry/vueを初期化すると、以下のような処理になります。
- Nuxtの初期化が始まり、Vueの
app.config.errorHandlerにNuxtのエラーハンドラーが登録される。（前提知識3） - プラグインの初期化が始まる。
- プラグインで@sentry/vueが初期化され、
app.config.errorHandlerに@sentry/vueの関数が代入される。 この時、NuxtのエラーハンドラーもSentry SDKのハンドラーに保持される。（前提知識2） - プラグインの初期化が終わる。
- 3で
app.config.errorHandlerが上書きされたため、Nuxtはapp.config.errorHandlerをundefinedにしない。（前提知識3）
では、実際にエラーが発生するとどうなるかというと、以下の2つの関数が実行されます。
- @sentry/vueの関数
- Nuxtのエラーハンドラー
ここで、前提知識4の通り、Nuxtのエラーハンドラーによって500エラーが表示されます。
これがこの事象の裏側で起きている処理の流れです。
おわりに
Yappliでは本番環境とステージング環境のみSentryを有効化してエラー監視をしています。ただし、開発時に使う検証環境やローカル環境ではSentryを無効にしています。
このため、本番とステージングでは500エラーが表示されましたが、検証環境とローカル環境では500エラーが表示されなかったので、たまたまこの挙動に気づくことができました。
この事象に遭遇したことで、Nuxtの初期化や@sentry/vueの初期化の流れを実際のOSSのコードを追う機会ができ、とても良い勉強になりました。
ヤプリではただ開発するだけでなく、事象と向き合い知見を深める機会を重要視しています。もしご興味を持っていただけた方は、是非カジュアル面談でお話しましょう！
