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拡張機能をインストールする必要があります。
Yarnを使用している場合はnpm run dev
を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のノードアプリケーションとクライアント/ブラウザアプリケーションです。
ブラウザDevToolsでのデバッグ
クライアントサイドコード
通常通りnext dev
、npm run dev
、またはyarn dev
を実行して開発サーバーを起動します。サーバーが起動したら、好みのブラウザでhttp://localhost:3000
(または別のURL)を開きます。
Chromeの場合:
- ChromeのDeveloper Tools(WindowsとLinuxでは
Ctrl+Shift+J
、macOSでは⌥+⌘+I
)を開きます - Sourcesタブに移動します
Firefoxの場合:
- FirefoxのDeveloper Tools(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
補足: Dockerコンテナ内でアプリを実行する場合など、localhostの外部からのリモートデバッグアクセスを許可するには
NODE_OPTIONS='--inspect=0.0.0.0'
を使用してください。
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の場合:
- 新しいタブを開き、
chrome://inspect
にアクセスします - **Configure...**をクリックして、両方のデバッグポートがリストされていることを確認します
- まだ存在しない場合は
localhost:9229
とlocalhost:9230
の両方を追加します - Remote TargetセクションでNext.jsアプリケーションを探します
- inspectをクリックして、別のDevToolsウィンドウを開きます
- Sourcesタブに移動します
Firefoxの場合:
- 新しいタブを開き、
about:debugging
にアクセスします - 左サイドバーのThis Firefoxをクリックします
- Remote Targetsの下で、Next.jsアプリケーションを探します
- デバッガーを開くにはInspectをクリックします
- 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 Defenderが無効になっていることを確認してください。この外部サービスは_読み込まれるすべてのファイル_をチェックするため、
next dev
でのFast Refreshの時間が大幅に増加することが報告されています。これはNext.jsに関連していない既知の問題ですが、Next.jsの開発に影響します。
詳細情報
JavaScriptデバッガーの使い方について詳しく学ぶには、以下のドキュメントを参照してください: