source-maps-debugging

ソースマップを使って TypeScript をデバッグする

概要

ソースマップは、TypeScript のソースコードと実際に実行されるコンパイル済み JavaScript の間をつなぎます。デバッガーで元の TypeScript コードを表示したり、.ts ファイルにブレークポイントを設定したり、意味のあるスタックトレースを確認したりできます。ソースマップがなければ、コンパイル済み JavaScript をデバッグすることになり、手間がかかるうえ、ミスも起きやすくなります。

TypeScript アプリケーションを効率よくデバッグするには、ソースマップを適切に設定することが不可欠です。

このスキルを使う場面

• ブラウザーまたは Node.js で TypeScript をデバッグするとき
• ビルドツール（webpack、vite、rollup）を設定するとき
• スタックトレースにコンパイル済み JavaScript が表示されるとき
• TypeScript ファイルでブレークポイントが機能しないとき
• 本番ビルドを設定するとき

鉄則

デバッグのため、開発環境ではソースマップを有効にします。バンドルサイズを小さく保ちながらエラーを報告できるよう、本番環境では別途ソースマップを用意することを検討してください。

検出

次のようなデバッグ上の問題に注意してください。

// Stack trace shows compiled JavaScript:
Error: Something went wrong
    at Object.<anonymous> (app.js:42:15)
    at Module._compile (internal/modules/cjs/loader.js:1137:30)

// Should show TypeScript:
Error: Something went wrong
    at fetchUser (api.ts:15:10)
    at async loadData (app.ts:42:5)

ソースマップを有効にする

TypeScript コンパイラー

// tsconfig.json
{
  "compilerOptions": {
    "sourceMap": true,        // Generate .js.map files
    "inlineSourceMap": false, // Don't inline (for development)
    "inlineSources": false,   // Include source in map
    "sourceRoot": "/",        // Root for source paths
    "mapRoot": "/"            // Root for map paths
  }
}

ビルドツール

// webpack.config.js
module.exports = {
  devtool: 'source-map',  // or 'eval-source-map' for faster builds
};

// vite.config.ts
export default {
  build: {
    sourcemap: true,
  },
};

// rollup.config.js
export default {
  output: {
    sourcemap: true,
  },
  plugins: [typescript({ sourceMap: true })],
};

ソースマップのオプション

オプション	用途	ビルド速度	品質
source-map	本番環境	遅い	最高
eval-source-map	開発環境	速い	良好
inline-source-map	単一ファイル	普通	良好
hidden-source-map	本番環境（エラー報告）	遅い	最高
nosources-source-map	本番環境（コードなし）	遅い	スタックトレースのみ

本番環境での注意点

// webpack.config.js - different for dev/prod
module.exports = (env) => ({
  devtool: env.production 
    ? 'hidden-source-map'  // Separate file, not referenced
    : 'eval-source-map',   // Fast, good for development
});

ソースマップをエラー報告サービスにアップロードします。

// Sentry example
Sentry.init({
  dsn: 'your-dsn',
  release: process.env.RELEASE,
  // Source maps uploaded separately
});

ソースマップを検証する

# Check if source map was generated
ls dist/*.js.map

# Inspect source map content
npx source-map-explorer dist/app.js

# Test in browser DevTools
# 1. Open DevTools
# 2. Go to Sources tab
# 3. Look for original .ts files
# 4. Set breakpoint in TypeScript

プレッシャー耐性プロトコル

ソースマップを設定するときは、次の点に注意してください。

1. 開発環境で有効にする：デバッグに不可欠です
2. 本番環境での方針を選ぶ：hidden、nosources、または無効
3. ブレークポイントをテストする：TypeScript ファイルで機能することを確認します
4. スタックトレースを確認する：.ts ファイル名と行番号が表示されるはずです
5. バンドルサイズを監視する：ソースマップは大きくなることがあります

要注意の兆候

症状	問題	解決策
.ts のブレークポイントが機能しない	ソースマップが読み込まれていない	ビルド設定で有効にする
スタックトレースに .js が表示される	ソースマップが生成されていない	tsconfig／ビルドツールを確認する
行番号が間違っている	ソースマップが古い	ビルドして再生成する
バンドルサイズが非常に大きい	インラインソースマップを使用している	別ファイルを使う

よくある正当化

「ソースマップはビルドを遅くする」

実際のところ：開発環境では速度を優先して eval-source-map を使います。完全なソースマップは本番ビルドでのみ使用します。

「必要ありません。JS を読めます」

実際のところ：型や async/await の変換などを含むコンパイル済み JS のデバッグは大変です。ソースマップを使えば何時間もの作業を省けます。

「ソースコードが公開されてしまう」

実際のところ：本番環境では hidden-source-map または nosources-source-map を使います。エラー報告サービスにのみアップロードしてください。

クイックリファレンス

環境	推奨設定	備考
開発環境	eval-source-map	再ビルドが速い
本番環境＋デバッグ	source-map	最高品質
本番環境＋エラー報告	hidden-source-map	サービスにアップロード
本番環境（最小構成）	nosources-source-map	スタックトレースのみ

まとめ

TypeScript のデバッグにはソースマップを有効にします。開発環境では高速なオプションを使い、本番環境では hidden／nosources の使用を検討してください。ソースマップを使うと、デバッグが格段に簡単になります。

参考資料

• Dan Vanderkam 著『Effective TypeScript』第 2 版
• 項目 73：ソースマップを使って TypeScript をデバッグする