コンテンツへスキップ
アプリケーションの構築設定デバッグ

デバッグ

このドキュメントでは、VS Codeデバッガー、Chrome DevTools、またはFirefox DevToolsを使用して、Next.jsのフロントエンドおよびバックエンドコードを完全なソースマップサポートでデバッグする方法を説明します。

Node.jsにアタッチできるデバッガーはすべて、Next.jsアプリケーションのデバッグにも使用できます。詳細については、Node.jsのデバッグガイドを参照してください。

VS Codeでのデバッグ

プロジェクトのルートに.vscode/launch.jsonという名前のファイルを作成し、以下の内容を記述します

launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "https://:3000"
    },
    {
      "name": "Next.js: debug client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "https://:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

注: VS CodeでFirefoxデバッグを使用するには、Firefox Debugger拡張機能をインストールする必要があります。

npm run dev は、Yarnを使用している場合は yarn dev に、pnpmを使用している場合は pnpm dev に置き換えることができます。

「Next.js: debug full stack」設定では、serverReadyAction.actionはサーバーの準備ができたときに開くブラウザを指定します。debugWithEdgeはEdgeブラウザを起動することを意味します。Chromeを使用している場合は、この値をdebugWithChromeに変更してください。

アプリケーションが起動するポート番号を変更している場合は、https://:3000の3000を使用しているポートに置き換えてください。

ルート以外のディレクトリからNext.jsを実行している場合（例えば、Turborepoを使用している場合）は、サーバーサイドおよびフルスタックのデバッグタスクにcwdを追加する必要があります。例: "cwd": "${workspaceFolder}/apps/web"。

デバッグパネル（Windows/LinuxではCtrl+Shift+D、macOSでは⇧+⌘+D）に移動し、起動構成を選択し、F5を押すか、コマンドパレットから「デバッグ: デバッグの開始」を選択してデバッグセッションを開始します。

Jetbrains WebStormでのデバッガーの使用

実行構成を一覧表示するドロップダウンメニューをクリックし、「構成の編集...」をクリックします。URLをhttps://:3000としてJavaScript Debugデバッグ構成を作成します。好みに合わせてカスタマイズ（例: デバッグ用ブラウザ、プロジェクトファイルとして保存）し、「OK」をクリックします。このデバッグ構成を実行すると、選択したブラウザが自動的に開くはずです。この時点で、Next.jsノードアプリケーションとクライアント/ブラウザアプリケーションの2つのアプリケーションがデバッグモードになっているはずです。

ブラウザDevToolsでのデバッグ

クライアントサイドのコード

next dev、npm run dev、またはyarn devを実行して、通常どおり開発サーバーを起動します。サーバーが起動したら、お好みのブラウザでhttps://:3000（または別のURL）を開きます。

Chromeの場合

  • Chromeの開発者ツールを開きます（Windows/LinuxではCtrl+Shift+J、macOSでは⌥+⌘+I）
  • 「Sources」タブに移動します

Firefoxの場合

  • Firefoxの開発者ツールを開きます（Windows/LinuxではCtrl+Shift+I、macOSでは⌥+⌘+I）
  • 「Debugger」タブに移動します

どちらのブラウザでも、クライアントサイドのコードがdebugger文に到達すると、コードの実行が一時停止し、そのファイルがデバッグエリアに表示されます。ファイル名を検索して手動でブレークポイントを設定することもできます

  • Chromeの場合: Windows/LinuxではCtrl+P、macOSでは⌘+Pを押します
  • Firefoxの場合: Windows/LinuxではCtrl+P、macOSでは⌘+Pを押すか、左パネルのファイルツリーを使用します

検索時、ソースファイルのパスはwebpack://_N_E/./で始まることに注意してください。

サーバーサイドのコード

ブラウザDevToolsでサーバーサイドのNext.jsコードをデバッグするには、基盤となるNode.jsプロセスに--inspectフラグを渡す必要があります

ターミナル
NODE_OPTIONS='--inspect' next dev

補足: NODE_OPTIONS='--inspect=0.0.0.0'を使用すると、Dockerコンテナでアプリを実行している場合など、localhost以外からのリモートデバッグアクセスを許可できます。

npm run devまたはyarn devを使用している場合は、package.jsonのdevスクリプトを更新する必要があります

package.json
{
  "scripts": {
    "dev": "NODE_OPTIONS='--inspect' next dev"
  }
}

--inspectフラグ付きでNext.js開発サーバーを起動すると、次のようになります

ターミナル
Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://node.dokyumento.jp/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: https://:3000

Chromeの場合

  1. 新しいタブを開き、chrome://inspectにアクセスします
  2. 「Configure...」をクリックして、両方のデバッグポートがリストされていることを確認します
  3. まだ存在しない場合は、localhost:9229とlocalhost:9230の両方を追加します
  4. 「Remote Target」セクションでNext.jsアプリケーションを探します
  5. 「inspect」をクリックして、別のDevToolsウィンドウを開きます
  6. 「Sources」タブに移動します

Firefoxの場合

  1. 新しいタブを開き、about:debuggingにアクセスします
  2. 左側のサイドバーで「This Firefox」をクリックします
  3. 「Remote Targets」の下で、Next.jsアプリケーションを見つけます
  4. 「Inspect」をクリックしてデバッガーを開きます
  5. 「Debugger」タブに移動します

サーバーサイドコードのデバッグは、クライアントサイドデバッグと似ています。ファイルを検索する際（Ctrl+P/⌘+P）、ソースファイルのパスはwebpack://{application-name}/./で始まります（{application-name}はpackage.jsonファイルに従ってアプリケーションの名前に置き換えられます）。

ブラウザDevToolsでサーバーエラーを検査する

エラーに遭遇した場合、ソースコードを検査することでエラーの根本原因を特定するのに役立ちます。

Next.jsは、エラーオーバーレイ上のNext.jsバージョンインジケーターの下にNode.jsアイコンを表示します。そのアイコンをクリックすると、DevToolsのURLがクリップボードにコピーされます。そのURLを使って新しいブラウザタブを開き、Next.jsサーバープロセスを検査できます。

Windowsでのデバッグ

Windowsユーザーは、NODE_OPTIONS='--inspect'の構文がWindowsプラットフォームでサポートされていないため、問題に遭遇する可能性があります。これを回避するには、cross-envパッケージを開発依存関係としてインストールし（npmとyarnでは-D）、devスクリプトを次のように置き換えます。

package.json
{
  "scripts": {
    "dev": "cross-env NODE_OPTIONS='--inspect' next dev"
  }
}

cross-envは、どのプラットフォーム（Mac、Linux、Windowsを含む）を使用しているかに関わらずNODE_OPTIONS環境変数を設定し、デバイスやオペレーティングシステム間で一貫したデバッグを可能にします。

補足: マシン上のWindows Defenderを無効にしてください。この外部サービスは「すべてのファイル読み取り」をチェックするため、next devでのFast Refreshの時間が大幅に増加することが報告されています。これはNext.jsとは関係ありませんが、Next.jsの開発に影響を与える既知の問題です。

詳細情報

JavaScriptデバッガーの使用方法の詳細については、以下のドキュメントを参照してください