メインコンテンツまでスキップ

デバッグ

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

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

VS Codeでのデバッグ​

プロジェクトのrootに、次の内容で.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": "http://localhost: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に置き換えることができます。

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

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

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

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

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

Chrome DevToolsでのデバッグ​

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

通常どおりにnext dev、npm run dev、またはyarn devを実行して、開発サーバーを起動します。サーバーが起動したら、Chromeでhttp://localhost: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フラグを渡す必要があります：

Terminal
NODE_OPTIONS='--inspect' next dev

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

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

--inspectフラグ付きのNext.js開発サーバーの起動は次のようになります：

Terminal
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の新しいタブを開き、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で新しいブラウザタブを開くことで、Next.jsサーバープロセスをChrome DevToolで検査できます。

Chrome DevToolのURLをコピーする例Chrome DevToolのURLをコピーする例

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環境変数を設定し、デバイスやオペレーティングシステムを超えて一貫したデバッグを可能にします。

Good to know: Windows Defenderが無効になっていることを確認してください。この外部サービスはすべてのファイル読み取りを確認します。これにより、next devを使用した場合にFast Refresh時間が大幅に増加することが報告されています。これはNext.jsに関連しない既知の問題で、Next.jsの開発に影響を与えます。

詳細情報​

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