デバッグ

このドキュメントでは、VS Code デバッガーまたは Chrome 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 full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

Yarn を使用している場合は npm run dev を yarn dev に、pnpm を使用している場合は pnpm dev に置き換えてください。

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

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

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

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

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

NODE_OPTIONS='--inspect' npm run dev または NODE_OPTIONS='--inspect' yarn dev を実行しても動作しないことに注意してください。これにより、同じポートで npm/yarn プロセスと Next.js の複数のデバッガーが起動しようとします。コンソールに Starting inspector on 127.0.0.1:9229 failed: address already in use のようなエラーが表示されます。

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

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

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

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

追加情報

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