【Node.js24.x】Error::prepareStackTrace()メソッドの使い方

prepareStackTraceメソッドは、JavaScriptのErrorオブジェクトがそのスタックトレースを文字列として整形する際の挙動をカスタマイズするために実行するメソッドです。このメソッドは、通常、Errorオブジェクトのstackプロパティが初めてアクセスされたときに、Node.jsの内部で自動的に呼び出されます。エラーオブジェクトは、発生源のファイル名、行番号、呼び出し関数などの情報を含むスタックトレースを保持しており、これらはエラーのデバッグにおいて非常に重要な手がかりとなります。

デフォルトでは、V8 JavaScriptエンジンの標準的な形式でスタックトレースが文字列化されますが、prepareStackTraceメソッドを開発者が定義したカスタム関数で上書きすることで、この標準動作を変更できます。メソッドが呼び出される際には、第一引数としてエラーオブジェクト自身が、第二引数としてエラー発生時のコールスタックを解析したCallSiteオブジェクトの配列が渡されます。CallSiteオブジェクトは、各スタックフレームのファイル名、行番号、関数名といった詳細な情報を提供します。

開発者はこれらの情報に基づいて、スタックトレースの表示形式を自由に調整できます。たとえば、特定のパスを省略して簡潔に表示したり、環境固有の情報を追加したり、あるいはセキュリティ上の理由から一部の情報を除去したりすることが可能です。このメソッドが返す文字列が、最終的にError.prototype.stackプロパティの値として設定され、エラーメッセージと共に表示されるスタックトレースとなります。主に、高度なエラーログシステムやデバッグツールを構築する際に、エラー表示を細かく制御するために利用されます。

Copy
1Error.prepareStackTrace = (error, stackTraces) => {
2  // error: 処理中のErrorオブジェクト
3  // stackTraces: V8 CallSiteオブジェクトの配列
4  // この関数は、カスタムフォーマットされたスタックトレースの文字列を返す必要があります
5  return '';
6};

error, trace

• error: Error: スタックトレースが生成される元となるエラーオブジェクト
• trace: object: エラーのスタックトレース情報を含むオブジェクト

string | object

このメソッドは、エラー発生時のスタックトレースを整形して文字列として返すか、あるいはスタックトレースの詳細情報を持つオブジェクトを返します。