なぜ今さら「sourceMap」なのか？デバッグの深淵を覗くための必須知識
現場でコードを書いていると、つい疎かにしがちな `tsconfig.json` の設定項目たち。その中でも `sourceMap` は、「とりあえず `true` にしておけば動くし、何が起きているかよくわからないから触らない」というエンジニアが意外と多い。
しかし、フロントエンドのシニアとして断言しよう。Source Mapを理解していないエンジニアは、本番環境で発生したクリティカルなバグの解決を、運任せにしているのと同じだ。
今日は、ブラウザが裏側でどうやって「難読化されたJS」と「君が書いた美しいTS」を繋いでいるのか、その泥臭い仕組みと、実務で絶対に守るべき設定を伝授する。
—
1. Source Mapがやっている「魔法」の正体
TypeScriptをコンパイルして生成されるJavaScriptは、もはや元のコードの面影すらないことがほとんどだ。変数名は圧縮され、関数はインライン化され、ロジックは細切れになる。
ブラウザのデベロッパーツール（DevTools）は、そのままではこれらのJSを人間が読める形式で表示できない。そこで登場するのが `.map` ファイルだ。
これは、「生成されたJSのこの行は、元のTSのこの行の、この文字位置に対応している」という巨大なインデックス地図だ。ブラウザはJSを読み込む際、末尾にある `//# sourceMappingURL=…` というコメントを見つけると、裏でこっそりこの地図をダウンロードし、JSの実行結果をTSのソースコード上にオーバーレイ表示してくれる。
この仕組みがあるからこそ、我々は本番に近い環境でも「デバッガを止めて、TypeScriptの行数で変数を監視する」という体験ができているわけだ。
—
2. 実務で「これだけは外すな」という設定例
中級レベルに差し掛かった君たちが、現場のプロジェクトで設定すべき `tsconfig.json` のベストプラクティスがこれだ。
{
“compilerOptions”: {
// ソースマップを生成する。これがないとデバッグが地獄になる
“sourceMap”: true,
// 【重要】ソースマップ内にTSのソースコードそのものを埋め込むかどうかの設定
// “inlineSourceMap”: false,
// ソースファイルへのパスを、コンパイル後のJSから見て相対パスではなく絶対パスとして解決する
“mapRoot”: “”,
// ソースマップ内に元のTSファイルをコピーして含めるか
// これをtrueにすると、ブラウザ上で「ファイルが見つからない」という事態を防げる
“inlineSources”: true
}
}
なぜ `inlineSources: true` が必要なのか？
CI/CDでJSファイルをS3やCDNにアップロードした後、ローカルのTSファイルが手元になかったり、バージョンがズレていたりすると、デバッガは「ソースが見つかりません」と悲鳴を上げる。`inlineSources` を有効にしておけば、ソースマップの中にTSのコード自体が埋め込まれるため、ネットワーク経由で別途TSファイルをフェッチする必要がなくなり、デバッグの確実性が劇的に向上する。
—
3. 注意点：本番環境での「情報漏洩」リスク
ここでシニアとして一つ忠告しておこう。Source Mapは、「誰でも君の書いたソースコードを丸裸にできる地図」でもある。
本番環境のJSファイルに `sourceMappingURL` が含まれていると、ChromeのDevToolsを開くだけで、誰でもソースコードを盗み見ることができる。これが社外秘のロジックであれば致命的だ。
現場での運用ルール：
1. 開発・検証環境: `sourceMap: true` で恩恵をフル活用する。
2. 本番環境:
- `sourceMap: true` のままで生成し、ビルド後のプロセスで `.map` ファイルだけをSentryなどのエラー監視ツールにアップロードし、サーバー上からは削除する。
- もしくは、webpack等のバンドラーの設定で、Source Mapを分離（Hidden Source Map）し、公開ディレクトリに置かない。
—
最後に：デバッグは「勘」ではなく「仕組み」
「デバッグが苦手だ」と言っている若手に限って、ログ出力だけで問題を解決しようとする。だが、本当に凄腕のエンジニアは、ブラウザの実行エンジンと自分の書いたコードの架け橋である「Source Map」という仕組みを完璧にコントロールしている。
`tsconfig.json` の一行を変えるだけで、君のデバッグ効率は明日から2倍、いや5倍になるかもしれない。
まずは今のプロジェクトの `tsconfig.json` を開いて、`sourceMap` がどうなっているか確認してほしい。もし `false` になっていたら、明日の朝、迷わず `true` に書き換えること。それが、プロのフロントエンドエンジニアへの第一歩だ。
何か詰まったら、いつでも聞いてくれ。現場からは以上だ。
コメント