Fairy Devices の mishi です。
本記事では「VS Code で Angular Web アプリのブレークポイントが無効になる」現象と、その解決を実体験に基づいてまとめています。
結論から言いますと、VS Code の設定ファイル[1]でパス設定を調整することで、ブレークポイントが有効な状態でデバッグできるようになりました。
やや唐突に出てきた「パス設定を調整する」とは、具体的には何をどのようにすればよいのでしょうか。順を追って記事本文で解説を進めます。
同じ課題で悩んでいる方や、Angular + VS Code 環境で快適にデバッグしたい方の参考になれば幸いです。
🗒️ 環境
本記事の動作確認環境は以下の通りです。
- OS: macOS Sequoia 15.6
- エディタ: Visual Studio Code 1.103.1
- Angular: v19.0.4
- ビルダー: @angular-devkit/build-angular:application
- デバッグブラウザ: Google Chrome 139.0.7258.128
ポイントは、ビルダーが esbuild ベースの Angular application ビルダー（@angular-devkit/build-angular:application）[2] である点です。
📌 Fairy Devices での Angular 活用
Fairy Devices が提供している mimi 各種サービス（音声認識、音声合成、機械翻訳、話者識別、態度認識、感情認識） のデモンストレーションを手軽に試せる mimi API Console で Angular を使用しています。
🔍 問題の発端と原因の追跡
何があった？
エディタを VS Code に変えて開発することにしたタイミングで
「デバッグ環境（デバッグサーバとデバッグブラウザ）を起動していない状態でブレークポイントをつけると有効表示（🔴）になるが、デバッグ環境を起動すると無効表示（○）になる」
という現象が起きました。
トラブルシュート情報の確認
無効表示のブレークポイント（○）をクリックすると、"バインドされていないブレークポイント" という見出しのメッセージが表示されます。
そこからトラブルシューティングのリンクを辿ると、下記のメッセージが確認できました。
You may need to adjust the webRoot in your launch.json if you're building from a subfolder, or tweak your sourceMapPathOverrides.
対象のプロジェクトでは、launch.json の webRoot や sourceMapPathOverrides のパスの調整が必要なようです[3]。
🧩 問題の解決方法
1. ブレークポイントを有効にする設定
ここでは、ブレークポイントを有効にするために設定を見直す手順をまとめます。
なお、Angular の新規プロジェクト（ng new コマンド実行直後など）のようなデフォルト構成では、ソースマップ内のパスとローカルのパスが自動的に一致することが多く、その場合、パスの調整なしでもブレークポイントが有効になります。
しかしプロジェクト構成や baseHref などのパス設定をカスタマイズしている場合は一致しないこともあり得ます。一致しない場合、ブレークポイントは無効になります。
仕組みを理解して、自分の環境に合ったパスを指定しましょう。
【 前提 】: ソースマップを有効にする
まずは、デバッグに必要なソースマップが正しく生成されるよう、angular.json のデバッグ環境用の設定項目 sourceMap と launch.json の sourceMaps を true に設定してください。
これらが無効になっている場合ソースマップが生成されず、デバッグブラウザのデベロッパーツール（DevTools ソースパネルの概要）でソースマップのリソースが表示されません。
（１） ブラウザのソースマップ内に記述されるパスを確認する
次に、DevTools「Sources」タブの「Page」ツリーで、実際にどのパスでリソースが認識されているか確認します（雲アイコンのオリジン配下）。
（２） ローカルファイルシステム上のソース配置パスを確認する
続いて、（１）で確認したパスと対応するローカルのディレクトリ（通常はプロジェクトルートや src ディレクトリ）のパスを把握します。
お手元の環境のディレクトリ構成次第で、適宜 launch.json の webRoot に該当ディレクトリへのパスを指定します。
（３） ソースマップ内のパス（（１））とローカルのパス（（２））を関連づける
最後に、ソースマップ内のパス（（１））とローカルのパス（（２））が正しく対応するように sourceMapPathOverrides でキーに（１）を、値に（２）を指定してマッピングします。
たとえば angular.json の sourceRoot が "src" の場合、launch.json の sourceMapPathOverrides には "src/*": "${webRoot}/src/*" のように設定する（（１）に "src/*"、（２）に "${webRoot}/src/*" を指定）と、マッピングが適切に機能します。
また、src 配下に限定せず全体を対象にしたい場合は、"*": "${webRoot}/*" のように設定してください。
（１）と（２）のパスが一致しない場合、ブレークポイントが無効になります。
2. 設定ファイルの具体例 （ launch.json / tasks.json ）
VS Code エディタでつけたブレークポイントが有効な状態でデバッグ環境を起動できるようになった設定内容は、下記の通りです。
VS Code の設定ファイル launch.json や tasks.json がまだ存在しない場合は新規作成してください。
環境によって必要な設定が異なります。お手元の環境で必要な項目と照らし合わせて適宜適用してください。
📄 .vscode/launch.json
launch.json は、VS Code がデバッグセッションを開始するための設定ファイルです。
webRoot にはソースコードの基準とするディレクトリ（通常はプロジェクトルート ${workspaceFolder} や src ディレクトリ）へのパスを指定します。
お手元の環境次第で、このパスを書き換えてください。
{
"version": "0.2.0",
"configurations": [
{
"name": "launch chrome",
"type": "pwa-chrome",
"request": "launch",
"url": "http://localhost:4200/",
"webRoot": "${workspaceFolder}/path/to/your/root",
"preLaunchTask": "npm: start",
"sourceMaps": true,
"sourceMapPathOverrides": {
"*": "${webRoot}/*"
}
},
]
}
📄 .vscode/tasks.json
tasks.json にはデバッグサーバ起動のタスクを設定しています。
タスクのラベル "npm: start" を launch.json の preLaunchTask に指定することで、「デバッグブラウザ起動前にはデバッグサーバを起動する」という設定になっています。
cwd には、npm コマンド（ここでは npm start）を実行する際の作業ディレクトリ（通常はプロジェクトルート）へのパスを指定します。
お手元の環境次第で、このパスを書き換えてください。
{
"version": "2.0.0",
"tasks": [
{
"label": "npm: start",
"type": "npm",
"script": "start",
"isBackground": true,
"problemMatcher": {
"owner": "typescript",
"pattern": "$tsc",
"background": {
"activeOnStart": true,
"beginsPattern": {
"regexp": "Generating browser application bundles"
},
"endsPattern": {
"regexp": "Compiled successfully"
}
}
},
"options": {
"cwd": "${workspaceFolder}/path/to/your/root"
}
},
]
}
3. デバッグ環境の起動手順
最終的に解決した設定 の launch.json、tasks.json の設定の場合、VS Code のデバッグツールで configuration 名 launch chrome を選択して"デバッグの開始"（＝緑の右向き矢印）をクリックすると、デバッグ環境を起動できます。
こうして起動したデバッグブラウザであれば、ブレークポイントが動作することを確認できました。
なお、方法は他にもあるようです[4]が、実際には検証していません。
🍵 最後に
ブレークポイントが無効になる現象解決の鍵は「ソースマップ内のパスとローカルファイルシステムでの配備パスの対応関係を意識し、正しく設定すること」でした。
対応関係を整理できていれば、ビルドツールが異なる場合やパス設定、ディレクトリ構造が複雑な場合でもブレークポイントを有効にしてデバッグできるでしょう。
最後まで読んでいただき、ありがとうございました。
-
VS Code は、ワークスペース設定をプロジェクトのルートにある
.vscodeフォルダに保存します。詳しくは、VS Code 公式ドキュメント ワークスペース設定 を参照ください。 ↩︎ -
@angular-devkit/build-angular:application：
パフォーマンスとビルド効率の向上を目的として、Angular v17 から追加されたビルダーです。esbuild を使用してクライアント側をバンドルします。また、当記事では触れていませんが、Node サーバーのサポートやビルド時に事前レンダリングされたルート（プリレンダリング）にも対応しています。 ↩︎ -
リンク先のページの中でも Here are some things to try when your breakpoints turn gray はブレークポイントがグレーになる際のヒントやチェックリストが掲載されています。 ↩︎
-
サーバを手動で起動し、VS Codeの「アタッチ」機能（VS Code - Browser debugging in VS Code）を使って既存のブラウザに接続する方法があるようです。 ↩︎
Discussion