JavaScript エラーが本番で発生すると、スタックトレースはミニファイされたバンドル (main.a8f42b.js:1:42819) を指します。これではデバッグに役立ちません。ソースマップ はバンドラーが出力する JSON ファイルで、それらの行 / 列番号を元のソースコードに戻すための情報を含みます。
エラー追跡 — およびそれに付随するソースマップ — は Pro プラン以上 で利用できます。
Zenovay でのソースマップの仕組み
- ビルドはバンドル (例:
main.a8f42b.js) と対応するソースマップ (main.a8f42b.js.map) を生成します。 - エラー追跡 API を通じてソースマップを Zenovay にアップロードします。
- エラーが届くと、トラッカーはバンドルファイルと
releaseを使ってアップロード済みマップと照合します。 - ダッシュボードは元のファイル、行、列、コードスニペットを表示します。
ソースマップは リリース識別子 に紐づけて保存されます — Git SHA、semver タグ、または任意の文字列です。エラーのリリースがアップロード済みマップと一致しない場合、ダッシュボードにはミニファイされた行が表示されます。
ソースマップのアップロード
ソースマップはエラー追跡 API を通じてアップロードします。エンドポイントは JSON ボディを受け入れます:
POST https://api.zenovay.com/api/errors/{websiteId}/sourcemap
| フィールド | 必須 | 説明 |
|---|---|---|
fileName | はい | マップを保存する名前 (例: main.js) |
fileUrl | はい | マップが属するバンドルの公開 URL |
release | 推奨 | このマップが適用されるリリース識別子 (省略すると default に保存) |
mapContent | 推奨 | .map ファイルの内容 |
mapUrl | オプション | mapContent を埋め込む代わりにマップを取得できる URL |
これらのエンドポイントには認証済みの Zenovay セッションが必要です — ダッシュボード アクセストークンを Bearer トークンとして渡します (app.zenovay.com にサインインしているときにブラウザが使用する短期間有効なトークン)。zv_* REST API キーではアクセスできません。
curl -X POST "https://api.zenovay.com/api/errors/{websiteId}/sourcemap" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<'JSON'
{
"fileName": "main.js",
"fileUrl": "https://example.com/static/main.js",
"release": "v2.4.1",
"mapContent": "<contents of main.js.map>"
}
JSON
サイト用にすでにアップロードされたものを確認するには、マップをリストします:
GET https://api.zenovay.com/api/errors/{websiteId}/sourcemaps — 特定のリリースにフィルタするには ?release=v2.4.1 を追加します。
本番ビルドの直後にアップロードを実行して、すべてのリリースにマップが付くようにし、応答ステータスを確認してアップロード失敗が静かにスキップされるのではなく検出されるようにします。アクセストークンは短期間有効であるため、アップロードのたびに更新される必要があります — ダッシュボードからキャプチャされたセッショントークンは長期間有効なままではありません。
リリース識別子について
release フィールドは、キャプチャされたエラーとアップロード済みマップの間のリンクです。エラーはそれらが報告された release 値で保存され、マップはエラーと同じリリースを共有する場合にマップはエラーと一致します。
ダッシュボードでエラーをリリースでタグ付けしたい場合、アプリケーションは送信するすべてのエラーでそのリリースを報告する必要があります。同じ識別子の下でマップをアップロードすると、2 つが一致します。
動作の検証
- マップをアップロードし、本番で既知のエラーをトリガーします。
- ウェブサイトのダッシュボードを開き、Errors タブに移動してエラーを開きます。
- スタックトレースセクションは 元の ファイルパス (例:
src/components/Checkout.tsx:42) と短いコードプレビューを表示するはずです。
それでもミニファイされた行が表示される場合は、以下をご確認ください:
- エラーが報告されたリリースが、マップをアップロードしたリリースと一致している。
- アップロードした
fileUrlがエラーが来たバンドルと一致している。 .mapファイルが切り詰められていない (部分アップロードは使用可能なマップのない状態につながる可能性があります)。
プライバシー
ソースマップには元のコード全体が含まれます。プライベートに保存され、ウェブサイトにスコープされ、公開配信されることはありません。