Next.js でデバッグツールを使用する方法

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

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": "https://:3000"
    },
    {
      "name": "Next.js: debug client-side (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "https://: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 拡張機能 をインストールする必要があります。

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

「Next.js: debug full stack」構成では、serverReadyAction.action はサーバーの準備ができたときにどのブラウザを開くかを指定します。debugWithEdge は Edge ブラウザを起動することを意味します。Chrome を使用している場合は、この値を debugWithChrome に変更してください。

アプリケーションの起動ポート番号を変更している場合は、https://: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 として https://:3000 を指定して JavaScript Debug デバッグ構成を作成します。お好みに合わせてカスタマイズし（例：デバッグ用のブラウザ、プロジェクトファイルとして保存）、OK をクリックします。このデバッグ構成を実行すると、選択したブラウザが自動的に開きます。この時点で、デバッグモードで 2 つのアプリケーション（NextJS ノードアプリケーションとクライアント/ブラウザアプリケーション）が動作しているはずです。

ブラウザ開発者ツールでのデバッグ

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

通常通り next dev、npm run dev、または yarn dev を実行して開発サーバーを起動します。サーバーが起動したら、お好みのブラウザで https://: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/./ から始まるパスを持つことに注意してください。

React Developer Tools

React 固有のデバッグのために、React Developer Tools ブラウザ拡張機能をインストールします。この必須ツールは、以下のことに役立ちます。

• React コンポーネントの検査
• Props と State の編集
• パフォーマンスの問題の特定

サーバーサイドコード

ブラウザ開発者ツールでサーバーサイド Next.js コードをデバッグするには、基盤となる Node.js プロセスに --inspect フラグを渡す必要があります。

NODE_OPTIONS='--inspect' next dev

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

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://node.dokyumento.jp/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: https://:3000

Chrome の場合

1. 新しいタブを開き、chrome://inspect にアクセスします。
2. Configure... をクリックして、両方のデバッグポートがリストされていることを確認します。
3. localhost:9229 と localhost: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 ファイルに従ってアプリケーション名に置き換えられます）。

ブラウザ開発者ツールでサーバーエラーを検査

エラーが発生した場合、ソースコードを検査することでエラーの原因を特定するのに役立ちます。

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 デバッガーの使用方法について詳しくは、以下のドキュメントをご覧ください。

• VS Code での Node.js デバッグ: ブレークポイント
• Chrome DevTools: JavaScript のデバッグ
• Firefox DevTools: Debugger