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

デバッグ

このドキュメントでは、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": "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/.bin/next",
"runtimeArgs": ["--inspect"],
"skipFiles": ["<node_internals>/**"],
"serverReadyAction": {
"action": "debugWithEdge",
"killOnServerStop": true,
"pattern": "- Local:.+(https?://.+)",
"uriFormat": "%s",
"webRoot": "${workspaceFolder}"
}
}
]
}

Note: 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:30003000を使用しているポートに置き換えてください。

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をクリックします。このデバッグ構成を実行すると、選択したブラウザが自動的に開きます。この時点で、NextJSノードアプリケーションとクライアント/ブラウザアプリケーションの2つがデバッグモードになります。

ブラウザDevToolsでのデバッグ

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

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

Terminal
NODE_OPTIONS='--inspect' next dev

Good to know: NODE_OPTIONS='--inspect=0.0.0.0'を使用すると、Dockerコンテナでアプリを実行する場合など、localhost以外でのリモートデバッグアクセスが可能になります。

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

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の場合:

  1. 新しいタブを開き、chrome://inspectにアクセス
  2. **Configure...**をクリックして、両方のデバッグポートがリストされていることを確認
  3. localhost:9229localhost: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パッケージを開発依存関係としてインストールし(npmyarnでは-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デバッガーの使用方法について詳しく学ぶには、次のドキュメントをご覧ください: