Debugging

このドキュメンテーションでは、VS Code debugger またはChrome DevTools を使用して、フルの source マップのサポートを使用してフロントエンドとバックエンドの Next.js code を debugging する方法について説明しています。

Node.js にアタッチできるあらゆるデバッガは、Next.js アプリケーションのデバッグにも使用できます。詳細は Node.js のデバッグガイド をご覧ください。

Debugging with VS Code

.vscode/launch.jsonという名前のファイルをプロジェクトの root に作成し、以下の内容を含めてください。

{
  "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-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

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

もしアプリケーションが起動するport number の変更を行うなら、replace を行い、http://localhost:3000 の 3000 を代わりに使用している port に書き換えてください。

あなたが root 以外のディレクトリから Next.js を実行している場合(例えば、Turborepo を使用している場合)、cwdを server-side と完全な stack debugging タスクに追加する必要があります。例えば、"cwd": "${workspaceFolder}/apps/web"のようにします。

次に Debug パネルに移動します(Windows/Linux ではCtrl+Shift+D、macOS では⇧+⌘+D)、起動設定を選択し、その後F5を押すか、Command パレットからDebug: Start Debuggingを選択して、start すると、debugging セッションが開始されます。

Using the Debugger in Jetbrains WebStorm

runtime 設定を一覧表示するドロップダウンメニューをクリックし、Edit Configurations...をクリックします。http://localhost:3000を URL としたJavascript Debugデバッグ設定を作成します。お好みに合わせてカスタマイズ(例: debugging 用のブラウザ、プロジェクトファイルとして保存など)し、OKをクリックしてください。このデバッグ設定を実行すると、選択したブラウザが自動的に開きます。この時点で、次の 2 つのアプリケーションがデバッグモードになります：NextJS のノードアプリケーションとクライアント/ブラウザアプリケーション。

Debugging with Chrome DevTools

Client サイドの code

Start というボタンを押して、development server を通常通りに起動します。next dev、npm run dev、またはyarn devを実行します。server が起動したら、http://localhost:3000 (またはあなたの選択した URL)を Next で開きます。次に、Chrome の開発者ツールを開き(Windows/Linux ではCtrl+Shift+J、macOS では⌥+⌘+I)、Sourcesタブに移動します。

さて、Client 側の code がdebugger ステートメントに到達すると、いつでも code の実行が一時停止し、そのファイルが debugging エリアに表示されます。また、Windows/Linux ではCtrl+Pを、macOS では⌘+Pを押してファイルを検索し、手動でブレークポイントを設定することもできます。ここで検索するときには、source ファイルはwebpack://_N_E/./で始まる paths を持つことに注意してください。

Server-side code

Chrome DevTools を使用して server-side Next.js code をデバッグするには、下層の 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 dev server を起動すると、次のようになります：

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

NODE_OPTIONS='--inspect' npm run dev や NODE_OPTIONS='--inspect' yarn devを実行すると機能しないことに注意してください。これにより、同じ port 上で複数のデバッガーを start しようとすることになります：一つは npm/yarn プロセス用、もう一つは Next.js 用です。結果として、コンソール上でStarting inspector on 127.0.0.1:9229 failed: address already in useのような error が表示されるでしょう。

server が起動したら、Chrome で新しいタブを開き、chrome://inspectにアクセスします。そこで Next.js アプリケーションがRemoteTargetセクション内に表示されるはずです。アプリケーションの下にあるinspectをクリックして別の DevToolswindow を開き、その後Sourcesタブに移動します。

Debugging server-side code はここでは debuggingClient サイドの code が ChromeDevTools で行うのと同じように機能します。ただし、ここでCtrl+Pまたは⌘+Pを使用してファイルを検索すると、あなたの source ファイルは webpack://{application-name}/./(ここで、{application-name}はあなたのpackage.jsonファイルによってあなたのアプリケーションの名前に置き換えられます)で始まる paths を持つことになります。

Windows での Debugging

Windows ユーザーは、NODE_OPTIONS='--inspect'を使用する際に問題に遭遇する可能性があります。その syntax は Windows プラットフォームではサポートされていません。これを回避するために、cross-env パッケージを development の依存関係としてインストールする(npm および yarnで -D)し、devscript を次のように replace ください。

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

cross-envは、あなたがどのプラットフォーム(Mac、Linux、Windows を含む)にいても、常にNODE_OPTIONS環境 variable を設定し、デバイスやオペレーティングシステム間で一貫して debugging を行うことができます。

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

More information

JavaScript デバッガーの使用方法について詳しく学ぶには、次のドキュメンテーションをご覧ください：

• Node.js debugging in VS Code: ブレイクポイント
• Chrome DevTools：debugging JavaScript