スタックトレース分析

スタックトレース分析をマスターして、アプリケーション内のJavaScriptエラーを素早く特定して修正します。

スタックトレースを理解する

スタックトレースの構成

TypeError: Cannot read property 'email' of undefined
    at getUserEmail (user-service.js:45:12)    ← エラーの場所
    at validateForm (form-handler.js:123:8)    ← ここから呼ばれた
    at HTMLFormElement.<anonymous> (form.js:67:5) ← イベントハンドラ
    at HTMLFormElement.dispatch (jquery.min.js:3:10456)
    at HTMLFormElement.v.handle (jquery.min.js:3:8765)

スタックフレームのコンポーネント

各行には以下が含まれます:

コンポーネント	例	説明
関数	getUserEmail	関数名
ファイル	user-service.js	ソースファイル
行	45	行番号
列	12	列位置

読む方向

スタックトレースを上から下へ読みます:

1. 上部フレーム: エラーが発生した場所
2. 中部フレーム: 呼び出し連鎖
3. 下部フレーム: エントリーポイント

Zenovayでスタックトレースを表示する

エラー追跡はPro機能です。ウェブサイトで有効になると、キャプチャされたエラーはフィンガープリントでグループ化され、サイトダッシュボードのエラータブに表示されます（/domains/{your-site}?tab=errors）。

有効にするには、ウェブサイトの設定を開き、詳細セクションに移動して、フィーチャーフラグの下のエラー追跡をオンにします。

エラー詳細ビュー

エラーグループを[エラー]タブから開いて、その最近の発生を確認します。各発生について以下を確認できます：

• エラーの種類とメッセージ
• エラーが発生したページURL
• ブラウザ、OS、デバイスの内訳
• エラーに至るブレッドクラム（ユーザーが実行した操作）
• フレームの展開可能なリストとして表示されるスタックトレース

スタックトレースはデフォルトで折りたたまれています。展開して各フレームを以下のように表示します：

at getUserById (user-service.js:45:12)
at handleGetUser (api-handler.js:78:5)
at <anonymous> (router.js:23:3)

長いトレースは最初のフレームに切り詰められ、残りの部分に「さらにフレーム」インジケーターがあります。各フレームについて関数名、ファイル、行、列が表示されるため、エディタで関連するコードに直接ジャンプできます。

ソースマップ

ソースマップを使用すると、Zenovayは本番環境の縮小されたスタックトレースを元のソースファイル、行、列に変換できます。

ソースマップなし

縮小されたコードは暗号化されたトレースを生成します：

TypeError: a is not a function
    at e (main.abc123.js:1:34567)
    at t.handleClick (main.abc123.js:1:45678)
    at Object.onClick (main.abc123.js:1:56789)

ソースマップあり

同じエラーですが読みやすい形式：

TypeError: processPayment is not a function
    at handleCheckout (checkout.tsx:89:12)
    at CheckoutButton.handleClick (CheckoutButton.tsx:45:8)
    at onClick (form-events.ts:23:5)

ソースマップの生成

最初のステップはビルド中にソースマップを生成することです。本番環境では非表示のソースマップを使用して、.mapファイルが作成されるが、公開バンドルから参照（または提供）されないようにします。

Webpack – 非表示のソースマップを生成：

// webpack.config.js
module.exports = {
  devtool: 'hidden-source-map',
  // ソースマップは生成されますが、出力では参照されません
};

Vite – 非表示のソースマップを生成：

// vite.config.js
export default {
  build: {
    sourcemap: 'hidden'
  }
};

Rollup – 非表示のソースマップを生成：

// rollup.config.js
export default {
  output: {
    sourcemap: 'hidden'
  }
};

各ビルドにリリースバージョンのタグを付けます（下のリリース相関を参照）。これにより、ソースマップとエラーが同じデプロイに対して一致します。

一般的なパターンの分析

未定義のプロパティへのアクセス

TypeError: Cannot read property 'name' of undefined
    at renderUser (user-card.js:23:15)

分析:

• 23行目の予期されたオブジェクトは未定義です
• renderUserへのデータフローを確認します
• nullチェックが不足している可能性があります

修正パターン:

// 前
const name = user.name;

// 後
const name = user?.name ?? 'Unknown';

関数が定義されていない

ReferenceError: processPayment is not defined
    at handleSubmit (checkout.js:45:5)

分析:

• 関数が呼ばれていますがスコープ内にありません
• インポート/エクスポートを確認します
• モジュール読み込み順序を確認します

型エラー

TypeError: users.map is not a function
    at renderUserList (list.js:12:20)

分析:

• usersは配列ではありません
• API応答フォーマットを確認します
• データ型の仮定を確認します

高度な分析

非同期スタックトレース

モダンJavaScriptには非同期コンテキストが含まれます：

Error: API request failed
    at fetchUser (api.js:34:11)
    at async loadUserData (user-loader.js:56:18)
    at async initApp (app.js:12:5)

クロスオリジンフレーム

サードパーティスクリプトは限定的な情報を表示します：

Error: Script error.
    at <anonymous> (https://third-party.com/widget.js:1:1)

解決策: サードパーティスクリプトにCORSヘッダーを追加します：

<script src="https://third-party.com/widget.js" crossorigin="anonymous"></script>

縮小されたサードパーティコード

ソースマップのないライブラリの場合：

• URLパターンからライブラリを特定します
• ライブラリバージョンを確認します
• 既知の問題を検索します
• 代替案を検討します

デバッグワークフロー

ステップ1: エラーの場所を特定する

1. スタックの上部フレームを見ます
2. ファイル、行、列をメモします
3. コードが何をしているかを理解します

ステップ2: 呼び出しパスをトレースする

1. スタック内のフレームを下へ追跡します
2. データフローを特定します
3. 不正なデータが発生する場所を探します

ステップ3: コンテキストを確認する

1. [エラー]タブでエラー発生の時間経過を表示します
2. 内訳で影響を受けたブラウザ/デバイスを確認します
3. エラーに至るブレッドクラムを読みます

ステップ4: 再現する

1. セッションリプレイを使用します（プランで利用可能な場合）
2. エラーの前のユーザーアクションを確認します
3. 同じブラウザ/条件でテストします

ステップ5: 修正して検証する

1. 修正を実装します
2. 新しいバージョンをデプロイします
3. エラー詳細ビューからエラーグループを解決済みとしてマークします
4. リグレッションを監視します

エラー状態を管理する

エラー詳細ビューから、グループの状態を変更してリストを集中させることができます：

• 未解決 – 注意が必要（デフォルト）
• 調査中 – 誰かが対応しています
• 解決済み – 修正及び検証済み
• 無視 – 既知で意図的に対応していない

ステータスの変更にはワークスペースの編集者アクセスが必要であり、ワークスペース監査ログに記録されます。

リリース相関

トラッキングにリリースでタグを付けると、キャプチャされた各エラーはそのリリースを記録するため、どのデプロイが問題を導入したかを判断できます。

リリースをタグ付けする

ビルドにリリース値を設定して、トラッカーが各イベントで報告するようにします。基本スニペットは次のようになります：

<script
  defer
  data-tracking-code="YOUR_TRACKING_CODE"
  src="https://api.zenovay.com/z.js"
></script>

これを対応するビルドのソースマップ（同じリリースでタグ付け）と組み合わせて、本番環境のトレースが正しいバージョンに対してシンボル化されます。

ベストプラクティス

ソースマップの管理

• 本番環境では非表示のソースマップを使用します
• ソースマップをリリース別に整理します
• 各ビルドにデプロイに対応するリリースバージョンをタグ付けします

スタックトレースの品質

• 意味のある関数名を使用します
• 匿名関数を避けます
• コールスタックの深さを合理的に保ちます
• 必要に応じてエラーコンテキストを追加します

デバッグの効率

• 最も影響を受けたエラーから始めます
• ステータス（調査中、解決済み、無視）を使用してリストを集中させます
• 調査結果を文書化します
• チームと共有します

トラブルシューティング

ソースマップが不足しています

確認してください：

• このリリースのソースマップが生成されました
• リリースバージョンはトラッカーが報告するものと一致します
• ファイル名がデプロイされたバンドルと一致します

不完全なスタックトレース

原因：

• 非同期コードが正しくトレースされていません
• eval()または動的コードからのエラー
• ブラウザの制限

「Script error」メッセージ

ソリューション：

• CORSヘッダーを追加します
• crossorigin属性を使用します
• サードパーティスクリプトを自分でホストします

次のステップ

• JavaScriptエラー追跡
• セッションリプレイ
• パフォーマンス監視