デバッグ

このドキュメントでは、VS Code デバッガーまたはChrome 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": "https://127.0.0.1:3000"
    },
    {
      "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}"
      }
    }
  ]
}

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

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

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

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

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

ランタイム設定がリストされたドロップダウンメニューをクリックし、Edit Configurations...をクリックします。URLにhttps://127.0.0.1:3000を指定したJavaScript Debugデバッグ設定を作成します。お好みに合わせてカスタマイズ（例：デバッグ用ブラウザ、プロジェクトファイルとして保存）し、OKをクリックします。このデバッグ設定を実行すると、選択したブラウザが自動的に開きます。この時点で、NextJSのNodeアプリケーションとクライアント/ブラウザアプリケーションの2つのアプリケーションがデバッグモードになっているはずです。

Chrome DevToolsでのデバッグ

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

通常どおりnext dev、npm run dev、またはyarn devを実行して開発サーバーを起動します。サーバーが起動したら、Chromeでhttps://127.0.0.1:3000（または別のURL）を開きます。次に、Chromeのデベロッパーツールを開き（Windows/Linuxの場合はCtrl+Shift+J、macOSの場合は⌥+⌘+I）、Sourcesタブに移動します。

これで、クライアントサイドのコードがdebuggerステートメントに到達するたびに、コードの実行が一時停止し、そのファイルがデバッグ領域に表示されます。また、Windows/LinuxではCtrl+P、macOSでは⌘+Pを押してファイルを検索し、手動でブレークポイントを設定することもできます。ここで検索する場合、ソースファイルのパスはwebpack://_N_E/./で始まることに注意してください。

サーバーサイドのコード

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

NODE_OPTIONS='--inspect' next dev

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://node.dokyumento.jp/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: https://127.0.0.1:3000

サーバーが起動したら、Chromeで新しいタブを開き、chrome://inspectにアクセスします。すると、Remote TargetセクションにNext.jsアプリケーションが表示されるはずです。アプリケーションの下にあるinspectをクリックして別のDevToolsウィンドウを開き、Sourcesタブに移動します。

ここでのサーバーサイドコードのデバッグは、Chrome DevToolsを使用したクライアントサイドコードのデバッグとほぼ同じように機能しますが、ここでCtrl+Pまたは⌘+Pでファイルを検索する場合、ソースファイルのパスはwebpack://{application-name}/./（{application-name}はpackage.jsonファイルに従ってアプリケーションの名前に置き換えられます）で始まることに注意してください。

Chrome DevToolsでサーバーエラーを検査する

エラーが発生した場合、ソースコードを検査すると、エラーの根本原因を追跡するのに役立ちます。

Next.jsは、開発オーバーレイに緑色のボタンのようなNode.jsロゴを表示します。そのボタンをクリックすると、Chrome DevToolのURLがクリップボードにコピーされ、そのURLを使用して新しいブラウザタブを開き、Chrome DevToolでNext.jsサーバープロセスを検査できます。

Windowsでのデバッグ

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

{
  "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デバッガーの使用方法の詳細については、次のドキュメントを参照してください。

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