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' を使用して、localhost 外からのリモートデバッグアクセスを許可します。これは、Docker コンテナでアプリを実行する場合などに役立ちます。

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

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

--inspect フラグを付けて Next.js dev サーバーを起動すると、次のようになります。

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