Next.jsでデバッグツールを使用する方法

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

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

VS Codeでのデバッグ

プロジェクトのルートに.vscode/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": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/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に変更します。

ポート番号を変更している場合は、http://localhost:3000の3000を使用しているポートに置き換えます。

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

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

Jetbrains WebStormでデバッガーを使用する

実行時構成をリストするドロップダウンメニューをクリックし、Edit Configurations...をクリックします。URLとしてhttp://localhost:3000を持つJavaScript Debugデバッグ構成を作成します。好みに応じてカスタマイズし（例えば、デバッグ用ブラウザー、プロジェクトファイルとして保存）、OKをクリックします。このデバッグ構成を実行すると、選択したブラウザーが自動的に開きます。この時点で、デバッグモードで2つのアプリケーションが実行されている必要があります：NextJS Nodeアプリケーションとクライアントブラウザーアプリケーションです。

ブラウザーDevToolsでのデバッグ

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

next dev、npm run dev、またはyarn devを実行して、通常通り開発サーバーを起動します。サーバーが起動したら、希望のブラウザーでhttp://localhost:3000（またはあなたの代替URL）を開きます。

Chrome用：

• Chrome DevToolsを開きます（Windows/LinuxではCtrl+Shift+J、macOSでは⌥+⌘+I）
• Sourcesタブに移動します

Firefox用：

• Firefox DevToolsを開きます（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/./で始まることに注意してください。

React Developer Tools

React固有のデバッグの場合は、React Developer Toolsブラウザー拡張機能をインストールします。このツールは以下を実行するのに役立ちます：

• Reactコンポーネントを検査する
• propsとstateを編集する
• パフォーマンスの問題を特定する

サーバーサイドコード

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

NODE_OPTIONS='--inspect' next dev

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

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

{
  "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://nodejs.org/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost: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スクリプトを以下に置き換えます。

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

cross-envは、使用しているプラットフォーム（Mac、Linux、Windows含む）に関係なくNODE_OPTIONS環境変数を設定し、デバイスとオペレーティングシステム全体で一貫してデバッグできるようにします。

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

詳細情報

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

• VS CodeでのNode.jsデバッグ：ブレークポイント
• Chrome DevTools：JavaScriptをデバッグする
• Firefox DevTools：デバッガー