Visual Studio Code のデバッグ構成

Name: Visual Studio Code
Author: Microsoft

複雑なデバッグシナリオやアプリケーションの場合、デバッガーの構成を指定するためにlaunch.jsonファイルを作成する必要があります。たとえば、アプリケーションのエントリポイントを指定したり、実行中のアプリケーションにアタッチしたり、環境変数を設定したりする場合などです。

VS Code でのデバッグについて詳しくは、「Visual Studio Code でのデバッグ」を参照してください。

ヒント

VS Code の Copilot は、プロジェクトの起動構成を作成するのに役立ちます。Copilot で起動構成を生成する方法について、さらに情報を確認してください。

起動構成

シンプルなアプリケーションやデバッグシナリオの場合、特定のデバッグ構成なしでプログラムを実行およびデバッグできます。F5 キーを使用すると、VS Code は現在アクティブなファイルを実行しようとします。

ただし、ほとんどのデバッグシナリオでは、デバッグ構成 (起動構成) を作成する必要があります。たとえば、アプリケーションのエントリポイントを指定したり、実行中のアプリケーションにアタッチしたり、環境変数を設定したりする場合などです。起動構成ファイルを作成することは、デバッグセットアップの詳細をプロジェクトと共に構成して保存できるため、有益でもあります。

VS Code は、デバッグ構成情報をワークスペース (プロジェクトのルートフォルダー) 内の.vscodeフォルダーにあるlaunch.jsonファイル、またはユーザー設定、あるいはワークスペース設定に保存します。

次のスニペットは、Node.js アプリケーションのデバッグ用のサンプル構成を説明しています。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}\\app.js"
    }
  ]
}

VS Code は、複数の構成を同時に起動するための複合起動構成もサポートしています。

注

VS Code でフォルダーを開いていない場合でも、シンプルなアプリケーションをデバッグできますが、起動構成を管理したり、高度なデバッグを設定したりすることはできません。

デバッグ構成ファイルの作成

初期のlaunch.jsonファイルを作成するには

実行とデバッグビューでlaunch.json ファイルを作成を選択します。
VS Code はデバッグ環境を検出しようとします。検出できない場合は、手動で選択できます。

選択したデバッグ環境に基づいて、VS Code はlaunch.jsonファイルにスターター構成を作成します。
エクスプローラービュー (⇧⌘E (Windows、Linux Ctrl+Shift+E)) で、VS Code が.vscodeフォルダーを作成し、launch.jsonファイルをワークスペースに追加したことに注目してください。

これで、launch.jsonファイルを編集して、構成を追加したり、既存の構成を変更したりできます。

launch.json に構成を追加する

既存のlaunch.jsonに新しい構成を追加するには、次のいずれかの方法を使用します。

構成の追加ボタンを押し、スニペットを選択して定義済み構成を追加します。
カーソルが構成配列内にある場合は IntelliSense を使用します。
実行 > 構成の追加 メニューオプションを選択します。

launch json suggestions

AI で起動構成を生成する

VS Code の Copilot を使用すると、プロジェクトの起動構成の作成プロセスを加速できます。Copilot で起動構成を生成するには

⌃⌘I (Windows、Linux Ctrl+Alt+I) を使用してチャットビューを開くか、タイトルバーの Copilot メニューからチャットを開くを選択します。
/startDebuggingチャットプロンプトを入力してデバッグ構成を生成します。

あるいは、express app #codebase のデバッグ構成を生成してください のように、カスタムプロンプトを入力することもできます。

これは、ワークスペースに異なる言語のファイルがある場合に役立ちます。

注
#codebaseチャット変数は、Copilot にプロジェクトのコンテキストを提供し、より正確な応答を生成するのに役立ちます。
提案された構成を適用し、デバッグを開始します。

起動構成でデバッグセッションを開始する

起動構成でデバッグセッションを開始するには

実行とデバッグビューの構成ドロップダウンを使用して、プログラムの起動という名前の構成を選択します。

利用可能な構成のリストは、launch.jsonファイルの構成と一致します。
F5 でデバッグセッションを開始するか、実行とデバッグビューでデバッグの開始 (再生アイコン) を選択します。

あるいは、コマンドパレット (⇧⌘P (Windows、Linux Ctrl+Shift+P)) を介して、デバッグ: 構成を選択してデバッグを開始でフィルタリングするか、'debug 'と入力してデバッグしたい構成を選択することで、構成を実行することもできます。

起動構成とアタッチ構成

VS Code には、起動とアタッチという 2 つの主要なデバッグモードがあり、これらは 2 つの異なるワークフローと開発者層に対応しています。ワークフローによっては、プロジェクトにどの種類の構成が適切かを知ることが混乱を招く可能性があります。

ブラウザーの開発者ツールのバックグラウンドをお持ちの場合、ブラウザーインスタンスがすでに開いているため、「ツールから起動する」ことに慣れていないかもしれません。DevTools を開くとき、単に開いているブラウザータブに DevTools をアタッチしているだけです。一方、サーバーまたはデスクトップのバックグラウンドをお持ちの場合、エディターにプロセスを起動させ、エディターが新しく起動されたプロセスに自動的にデバッガーをアタッチさせるのはごく普通のことです。

起動とアタッチの違いを説明する最良の方法は、起動構成を VS Code がアタッチする前にアプリをデバッグモードで開始する方法のレシピと考え、アタッチ構成を VS Code のデバッガーをすでに実行中のアプリまたはプロセスに接続する方法のレシピと考えることです。

VS Code デバッガーは通常、プログラムをデバッグモードで起動したり、すでに実行中のプログラムにデバッグモードでアタッチしたりすることをサポートしています。リクエスト (attachまたはlaunch) に応じて、異なる属性が必要とされ、VS Code のlaunch.jsonの検証と提案がそれに役立つはずです。

launch.json の属性

さまざまなデバッガーとデバッグシナリオをサポートするためのlaunch.json属性が多数あります。type属性の値を指定すると、IntelliSense (⌃Space (Windows、Linux Ctrl+Space)) を使用して、利用可能な属性のリストを表示できます。起動構成で利用できる属性は、デバッガーごとに異なります。

launch json suggestions

あるデバッガーで利用できる属性が、他のデバッガーでも自動的に機能するわけではありません。起動構成に赤い波線が表示された場合は、それらにカーソルを合わせると問題が何であるかがわかり、デバッグセッションを開始する前に修正を試みてください。

次の属性は、すべての起動構成で必須です。

type - この起動構成で使用するデバッガーの種類。インストールされているすべてのデバッグ拡張機能は種類を導入します。たとえば、組み込みの Node デバッガーにはnode、PHP と Go の拡張機能にはphpとgoなどです。
request - この起動構成のリクエストタイプ。現在、起動とattachがサポートされています。
name - デバッグ起動構成ドロップダウンに表示される、読みやすい名前。

すべての起動構成で利用できるオプションの属性をいくつか紹介します。

presentation - presentationオブジェクト内のorder、group、hidden属性を使用すると、デバッグ構成ドロップダウンとデバッグクイックピックで構成と複合をソート、グループ化、非表示にできます。
preLaunchTask - デバッグセッションの開始前にタスクを起動するには、この属性をtasks.json (ワークスペースの.vscodeフォルダー内) で指定されたタスクのラベルに設定します。または、デフォルトのビルドタスクを使用するために${defaultBuildTask}に設定することもできます。
postDebugTask - デバッグセッションの終了時にタスクを起動するには、この属性をtasks.json (ワークスペースの.vscodeフォルダー内) で指定されたタスクの名前に設定します。
internalConsoleOptions - この属性は、デバッグセッション中のデバッグコンソールパネルの表示を制御します。
debugServer - デバッグ拡張機能の作成者のみ: この属性を使用すると、デバッグアダプターを起動する代わりに、指定されたポートに接続できます。
serverReadyAction - デバッグ中のプログラムが特定のメッセージをデバッグコンソールまたは統合ターミナルに出力するたびに、WebブラウザーでURLを開きたい場合。詳細については、以下の「サーバープログラムのデバッグ時にURIを自動的に開く」セクションを参照してください。

多くのデバッガーは、次の属性の一部をサポートしています。

program - デバッガーを起動するときに実行する実行可能ファイルまたはファイル
args - デバッグするプログラムに渡される引数
env - 環境変数 (null値は変数を「未定義」にするために使用できます)
envFile - 環境変数を含む dotenv ファイルへのパス
cwd - 依存関係やその他のファイルを見つけるための現在の作業ディレクトリ
port - 実行中のプロセスにアタッチするときのポート
stopOnEntry - プログラムの起動時にすぐにブレークする
console - 使用するコンソールの種類。たとえば、internalConsole、integratedTerminal、またはexternalTerminal

変数の置換

VS Code は、一般的に使用されるパスやその他の値を変数として利用可能にし、launch.jsonの文字列内での変数の置換をサポートしています。これにより、デバッグ構成で絶対パスを使用する必要がなくなります。たとえば、${workspaceFolder}はワークスペースフォルダーのルートパス、${file}はアクティブなエディターで開いているファイル、${env:Name}は環境変数「Name」を提供します。

定義済みの変数の完全なリストは、「変数リファレンス」で確認するか、launch.json文字列属性内で IntelliSense を呼び出すことで確認できます。

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",
  "cwd": "${workspaceFolder}",
  "args": ["${env:USERNAME}"]
}

プラットフォーム固有のプロパティ

VS Code は、デバッガーが実行されているオペレーティングシステムに依存するデバッグ構成設定 (たとえば、プログラムに渡す引数) を定義することをサポートしています。これを行うには、launch.jsonファイルにプラットフォーム固有のリテラルを置き、そのリテラル内に対応するプロパティを指定します。

次の例は、Windows で"args"をプログラムに異なる方法で渡す方法を示しています。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js",
      "args": ["myFolder/path/app.js"],
      "windows": {
        "args": ["myFolder\\path\\app.js"]
      }
    }
  ]
}

有効なオペレーティングシステムプロパティは、Windows の場合は"windows"、Linux の場合は"linux"、macOS の場合は"osx"です。オペレーティングシステム固有のスコープで定義されたプロパティは、グローバルスコープで定義されたプロパティを上書きします。

typeプロパティはプラットフォーム固有のセクション内に配置できません。これは、リモートデバッグシナリオではtypeが間接的にプラットフォームを決定し、循環依存が発生するためです。

次の例では、プログラムのデバッグは macOS を除いて常にエントリで停止します。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js",
      "stopOnEntry": true,
      "osx": {
        "stopOnEntry": false
      }
    }
  ]
}

グローバル起動構成

すべてのワークスペースで利用できる起動構成を定義できます。グローバル起動構成を指定するには、launchユーザー設定に起動構成オブジェクトを追加します。このlaunch構成は、すべてのワークスペースで共有されます。例:

"launch": {
    "version": "0.2.0",
    "configurations": [{
        "type": "node",
        "request": "launch",
        "name": "Launch Program",
        "program": "${file}"
    }]
}

デバッグターゲットへの入出力のリダイレクト

入出力のリダイレクトはデバッガーまたはランタイムに固有のものであるため、VS Code にはすべてのデバッガーに機能する組み込みのソリューションはありません。

検討すべき 2 つのアプローチを次に示します。

デバッグするプログラム (「デバッグターゲット」) をターミナルまたはコマンドプロンプトで手動で起動し、必要に応じて入出力をリダイレクトします。デバッガーがそれにアタッチできるように、適切なコマンドラインオプションをデバッグターゲットに渡してください。「アタッチ」デバッグ構成を作成して実行し、デバッグターゲットにアタッチします。
使用しているデバッガー拡張機能が VS Code の統合ターミナル (または外部ターミナル) でデバッグターゲットを実行できる場合、シェルリダイレクト構文 (たとえば、「<」または「>」) を引数として渡すことができます。

launch.json構成の例を次に示します。
```
{
  "name": "launch program that reads a file from stdin",
  "type": "node",
  "request": "launch",
  "program": "program.js",
  "console": "integratedTerminal",
  "args": ["<", "in.txt"]
}
```
このアプローチでは、<構文がデバッガー拡張機能を通じて渡され、統合ターミナルで変更されずに残ることが必要です。

複合起動構成

複数のデバッグセッションを開始する別の方法は、複合起動構成を使用することです。複合起動構成は、launch.jsonファイルのcompoundsプロパティで定義できます。

configurations属性を使用して、並行して起動する必要がある 2 つ以上の起動構成の名前をリストします。

オプションとして、個々のデバッグセッションが開始される前に実行されるpreLaunchTaskタスクを指定します。ブールフラグstopAllは、1 つのセッションを手動で終了した場合に、すべての複合セッションが停止するかどうかを制御します。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Server",
      "program": "${workspaceFolder}/server.js"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Client",
      "program": "${workspaceFolder}/client.js"
    }
  ],
  "compounds": [
    {
      "name": "Server/Client",
      "configurations": ["Server", "Client"],
      "preLaunchTask": "${defaultBuildTask}",
      "stopAll": true
    }
  ]
}

複合起動構成も、起動構成ドロップダウンメニューに表示されます。

サーバープログラムのデバッグ時にURIを自動的に開く

Web プログラムの開発では、デバッガーでサーバーコードにヒットさせるために、Web ブラウザーで特定の URL を開くことが一般的に必要です。VS Code には、このタスクを自動化する組み込み機能「serverReadyAction」があります。

次に、シンプルなNode.js Expressアプリケーションの例を示します。

var express = require('express');
var app = express();

app.get('/', function(req, res) {
  res.send('Hello World!');
});

app.listen(3000, function() {
  console.log('Example app listening on port 3000!');
});

このアプリケーションは、最初に「/」URL 用の「Hello World」ハンドラーをインストールし、次にポート 3000 で HTTP 接続をリッスンし始めます。ポートはデバッグコンソールで通知され、通常、開発者はブラウザアプリケーションにhttps://:3000と入力します。

serverReadyAction機能を使用すると、任意の起動構成に構造化されたプロパティserverReadyActionを追加し、実行する「アクション」を選択できます。

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",

  "serverReadyAction": {
    "pattern": "listening on port ([0-9]+)",
    "uriFormat": "https://:%s",
    "action": "openExternally"
  }
}

ここで、patternプロパティは、ポートを通知するプログラムの出力文字列を一致させるための正規表現を記述します。ポート番号のパターンは、正規表現のキャプチャグループとして利用できるように括弧で囲まれています。この例ではポート番号のみを抽出していますが、完全な URI を抽出することも可能です。

uriFormatプロパティは、ポート番号が URI に変換される方法を記述します。最初の%sは、一致するパターンの最初のキャプチャグループで置換されます。

結果の URI は、URI のスキームに対して構成された標準アプリケーションで、VS Code の外部 (「外部で」) で開かれます。

Microsoft Edge または Chrome 経由でデバッグをトリガーする

あるいは、actionをdebugWithEdgeまたはdebugWithChromeに設定することもできます。このモードでは、Chrome または Microsoft Edge のデバッグセッションに渡されるwebRootプロパティを追加できます。

物事を少し単純化するために、ほとんどのプロパティはオプションであり、次のフォールバック値を使用します。

pattern: "listening on.* (https?://\\S+|[0-9]+)" これは、一般的に使用されるメッセージ「listening on port 3000」または「Now listening on: https://:5001」に一致します。
uriFormat: "https://:%s"
webRoot: "${workspaceFolder}"

任意の起動構成をトリガーする

場合によっては、ブラウザーデバッグセッションのオプションをさらに構成したり、まったく別のデバッガーを使用したりする必要があるかもしれません。これを行うには、actionをstartDebuggingに設定し、patternが一致したときに開始する起動構成の名前に設定されたnameプロパティを使用します。

指定された起動構成は、serverReadyActionを持つ構成と同じファイルまたはフォルダーにある必要があります。

serverReadyAction機能の動作例

次のステップ

タスク - Gulp、Grunt、Jake を使用してタスクを実行する方法と、エラーや警告を表示する方法について説明します。
変数リファレンス - VS Code で利用できる変数について説明します。

よくある質問

最も一般的な問題は、launch.jsonを設定していないか、そのファイルに構文エラーがあることです。あるいは、フォルダーを開く必要があるかもしれません。フォルダーなしデバッグは起動構成をサポートしていないためです。

07/09/2025